Apple, Expo et TestFlight : procédure Snag

État vérifié le 31 octobre 2026. Ce guide décrit la configuration, la livraison d'une bêta et les contrôles fonctionnels. Il ne contient aucune donnée d'authentification, coordonnées personnelles ou chemin de stockage sensible.

1. Comprendre les trois circuits

Circuit	Rôle	Résultat attendu
EAS Build et signature Apple	Compiler et signer l'application iOS	Un build iOS installable via TestFlight
EAS Submit et App Store Connect	Transmettre le build à Apple	Un build visible dans TestFlight après traitement
Sign in with Apple et backend Snag	Connecter un utilisateur à son compte Snag	Une session utilisable dans l'application

Ces circuits sont indépendants. Une signature prête ne prouve pas que la connexion Apple fonctionne. Un transfert réussi vers App Store Connect ne publie pas l'application sur l'App Store.

2. État réel et limites de validation

Point	État au 31 octobre
Nouveau projet Expo accessible	Vérifié
Fiche Snag dans App Store Connect	Créée
Groupe de testeurs internes	Créé
Configuration de signature EAS	Profil récupéré et accepté par EAS lors du build 3
Configuration iOS Sign in with Apple	Autorisation générée vérifiée localement
Profil de soumission production	Fusionné sur staging, PR mobile #967
Validation mobile	Lint et typage réussis ; 3 298 tests réussis, 11 ignorés
Migration OAuth sur le VPS	Appliquée après sauvegarde vérifiée
API et routage public OAuth Apple	Activés et contrôlés
Connexion réelle Apple sur iPhone	À tester
Réception des e-mails « Masquer mon adresse »	À tester
Connexion Google	Non activée dans cette intervention
Nouveau build iOS	1.0.2 (3), réussi selon la capture EAS fournie par l'opérateur
Soumission et disponibilité TestFlight	Envoi automatique programmé ; réception effective par les testeurs à confirmer

Les modifications mobiles sont fusionnées sur staging au commit 11770b4 (PR #967). La documentation initiale a été fusionnée par la PR documentation #350. Le backend a ensuite été déployé au commit bf1a35c, avec les PR #608, #610 et #612.

Identifiants techniques de référence

Ces identifiants publics ne sont pas des moyens d'authentification.

Élément	Valeur
Projet Expo	@snag-bis/snagapp
EAS Project ID	9cde6413-cdf8-4525-90ee-4030ff02b7a5
Bundle ID iOS	io.snag-app.tcg
Package Android	io.snagapp.tcg
App Store Connect App ID	6828577293
Services ID Apple OAuth	io.snag-app.tcg.signin
Domaine OAuth	snag-app.io
Retour OAuth Apple	https://snag-app.io/auth/oauth/apple/callback

Ne pas recréer un projet Expo ou une fiche Apple pour chaque build.

3. Préparer le code avant chaque build

1. Utiliser le worktree dédié snag-staging-run.
2. Vérifier la branche et les modifications avec git status --short --branch.
3. Exécuter git fetch origin staging pour connaître la dernière version distante.
4. Si le worktree contient des modifications, les préserver et les intégrer par la procédure de PR. Ne pas utiliser reset --hard ou supprimer les fichiers.
5. Sur un worktree propre destiné à reproduire exactement staging, sélectionner origin/staging, puis installer les dépendances avec npm ci.
6. Vérifier que les corrections de configuration nécessaires sont présentes avant de lancer un build payant. Consigner le commit utilisé et l'éventuel écart local.

Un worktree possède ses propres dépendances. Les dépendances installées dans le dépôt voisin ne suffisent pas.

npx --yes eas-cli@latest whoami
npx --yes eas-cli@latest project:info

Vérifier que le projet affiché est celui de l'équipe actuelle. La session Expo et la session Apple sont deux connexions distinctes.

4. Configuration mobile nécessaire

L'identifiant iOS doit correspondre à la fiche Apple. L'identifiant Android est distinct : ne pas recopier automatiquement celui d'iOS.

Dans la configuration Expo iOS, conserver :

usesAppleSignIn: true,
entitlements: {
  'com.apple.developer.applesignin': ['Default'],
},

Dans cette application, le drapeau seul ne suffisait pas à produire l'autorisation attendue. L'autorisation explicite a été vérifiée avec l'introspection Expo. La présence de cette autorisation ne remplace pas l'activation du backend.

Dans eas.json, le profil submit.production.ios.ascAppId doit désigner l'identifiant numérique de la nouvelle fiche App Store Connect. Ce numéro est différent du Bundle ID et du compte utilisé pour se connecter à Apple.

Contrôles locaux :

npx expo config --type introspect
npx jest __tests__/expo --runInBand

Inspecter la configuration localement ; ne pas copier sa sortie intégrale dans une discussion publique.

5. Actualiser la signature iOS

Après une modification des capacités dans Apple Developer :

npx --yes eas-cli@latest credentials --platform ios

1. Choisir production.
2. Se connecter au compte Apple autorisé et sélectionner la bonne équipe.
3. Choisir Build Credentials.
4. Choisir All: Set up all the required credentials.
5. Réutiliser le certificat de distribution encore valide.
6. Accepter le renouvellement du profil de provisioning si nécessaire.
7. Attendre le résultat final, puis quitter le menu.

Le retour au menu est normal. Il ne lance aucun build. Un ancien profil indiqué « active » dans le résumé ne garantit pas qu'il inclut la nouvelle capacité.

Pour configurer l'envoi, revenir au menu principal de credentials, sélectionner App Store Connect: Manage your API Key, puis Use an existing API Key for EAS Submit si la clé d'envoi existe déjà. Vérifier l'équipe et attendre le message confirmant son affectation à l'application. Si aucune clé n'existe, utiliser Set up your project to use an API Key for EAS Submit avec le responsable Apple. Cette configuration est distincte de la clé Sign in with Apple.

6. Construire et envoyer vers TestFlight

Une fois le code, la signature et le profil de soumission vérifiés :

npx --yes eas-cli@latest build --platform ios --profile production --auto-submit

Cette commande consomme un build EAS. Elle compile puis transmet le résultat à App Store Connect. Le nom production désigne le profil technique de distribution. Il ne déclenche pas une publication publique.

Suivre séparément la réussite du build et celle de la soumission. Si la soumission échoue après un build réussi, corriger la soumission puis envoyer ce build précis ; ne pas reconstruire inutilement :

npx --yes eas-cli@latest submit --platform ios --profile production --id <BUILD_ID>

Vérifier l'identité et le commit de ce build avant l'envoi. Après traitement Apple, ouvrir Snag → TestFlight, traiter les éventuelles demandes de conformité, puis associer le build au groupe prévu si la distribution automatique ne l'a pas déjà fait.

Numéro de version et numéro de build

1.0.2 (3) signifie version applicative 1.0.2, build technique 3. cli.appVersionSource: "remote" et build.production.autoIncrement: true dans eas.json incrémentent automatiquement le numéro technique. Ne pas le réinitialiser et ne pas modifier les identifiants du projet pour cela.

Une nouvelle livraison de correctifs peut devenir 1.0.3 même en bêta ; une livraison de fonctionnalités peut devenir 1.1.0. Modifier la version dans la configuration mobile via une PR, puis fusionner avant le build. Ce changement ne publie rien sur l'App Store. Au 31 octobre, 1.0.3 a été proposé mais n'a pas été appliqué. Sans autre build intermédiaire, le prochain numéro sera 4.

Livraison du 31 octobre 2026

• Source mobile : staging, commit 11770b4.
• Build iOS 1.0.2 (3).
• Soumission programmée.
• GitHub Actions n'a pas démarré en raison d'une limite de facturation du compte. Les contrôles ont été exécutés localement ; ne pas présenter la CI distante comme verte.
• Le build réussi ne suffit pas à confirmer sa disponibilité dans TestFlight.

7. Testeurs

• Les testeurs internes doivent disposer d'un accès App Store Connect éligible à l'application, avoir accepté l'invitation et appartenir au groupe TestFlight.
• Un testeur n'a pas besoin d'acheter son propre abonnement Apple Developer.
• Le statut No Builds Available signifie qu'aucun build utilisable n'est encore associé au groupe ; ce n'est pas une demande de paiement.
• Les testeurs installent TestFlight sur leur iPhone puis acceptent l'invitation.
• Pour des personnes qui testent uniquement le produit, préférer les tests externes plutôt que leur attribuer des droits d'administration. Ce parcours peut demander une validation bêta Apple.

8. Connexion Apple : architecture et activation

Le parcours actuel utilise le navigateur système : l'app demande un démarrage au backend, ouvre Apple, puis reprend une fois le retour traité par le backend. Le retour applicatif utilise snag://auth/complete.

Les éléments Apple à associer sont : App ID principal, capacité Sign in with Apple, Services ID pour l'authentification web, domaine et URL de retour exacte.

Retrouver ou reconstruire la configuration Apple

1. Dans Apple Developer → Certificates, Identifiers & Profiles → Identifiers, ouvrir l'App ID iOS indiqué en section 2.
2. Activer Sign in with Apple, en tant qu'App ID principal, puis enregistrer. Une modification des capacités peut nécessiter de renouveler le profil EAS.
3. Dans Services IDs, ouvrir le Services ID existant ; le créer uniquement s'il est absent. Activer Sign in with Apple et sélectionner l'App ID principal.
4. Dans Configure, renseigner le domaine sans protocole et l'URL de retour HTTPS exacte de la section 2. Valider chaque écran jusqu'au dernier Save.
5. Dans Keys, vérifier qu'une clé Sign in with Apple est associée à cet App ID. Sa gestion relève du coffre sécurisé de l'équipe ; ne pas la confondre avec celle d'EAS Submit et ne rien ajouter au dépôt mobile.
6. Faire préparer la configuration serveur par l'opérateur autorisé, puis suivre les contrôles de la section 9. La seule configuration Apple Developer n'active pas les boutons dans l'application.

La caméra se configure via les permissions de l'application et leur texte d'explication, pas via une capacité Apple Developer à ajouter pour OAuth.

Lors de l'activation OAuth du 31 octobre, l'image API déjà en service contenait OAuth. Aucune nouvelle image n'était nécessaire pour cette activation. Une mise à jour distincte du backend a eu lieu ensuite (voir section 12). L'activation a consisté à :

1. Sauvegarder la base et vérifier la lisibilité de l'archive PostgreSQL.
2. Sauvegarder la configuration de l'API et du proxy.
3. Appliquer uniquement 0051_oauth.sql, dans une transaction.
4. Activer la configuration serveur Apple.
5. Recréer uniquement l'API, en conservant les autres paramètres de déploiement.
6. Ajouter le routage /auth/oauth/* vers l'API sans retirer ce préfixe.
7. Valider la configuration du proxy avant son redémarrage.

Ne pas refaire la migration ou remplacer la configuration à chaque build mobile. Un prochain déploiement doit préserver la configuration OAuth effective.

9. Contrôles effectués et recette à terminer

Contrôles techniques réussis :

• santé et disponibilité API : HTTP 200 ;
• fournisseurs OAuth, avec et sans préfixe /api : Apple annoncé ;
• démarrage : destination Apple, Services ID et URL de retour attendus ;
• attente de connexion : HTTP 202 ;
• retour Apple avec état invalide : page de retour vers l'application ;
• page d'accueil du site : HTTP 200 après intervention.

Ces contrôles ne constituent pas une connexion Apple réelle réussie. La recette sur iPhone reste obligatoire :

Scénario	Résultat à vérifier
Nouveau compte Apple	Retour dans Snag et compte accessible
Déconnexion puis nouvelle connexion	Même compte et même collection
Annulation chez Apple	Retour utilisable, sans session créée
Adresse déjà liée à un compte existant	Message explicite ; aucune fusion silencieuse
« Masquer mon adresse »	Connexion et réception des e-mails de récupération/suppression
Suppression d'un compte de test	Suppression effective et traitement de la révocation

Le rattachement automatique à un compte existant n'est pas implémenté dans ce parcours bêta. Une adresse relais différente peut produire un compte distinct. Vérifier également dans Apple Developer que les sources d'envoi utilisées par l'application sont enregistrées pour le relais privé et que leur configuration de messagerie est valide.

10. Dépannage

Symptôme	Action
Failed to resolve plugin ... expo-build-properties	Vérifier le dossier courant et ses dépendances ; utiliser le worktree préparé
Missing submit profile ... production	Corriger submit.production ; vérifier si un build a néanmoins été créé avant de relancer
APPLE_ID_AUTH: OFF	Contrôler les autorisations iOS générées ; ne supprimer aucune app Apple
Avertissement proposant de supprimer le Bundle	Ne pas suivre cette suggestion comme solution OAuth ; vérifier d'abord la synchronisation des capacités
waiting for an available submitter	Soumission en file d'attente ; suivre le job existant
punycode ou avertissement npm de dépréciation	Chercher l'erreur bloquante réelle ; ces avertissements seuls n'expliquent pas un échec
Fournisseurs OAuth vides	Vérifier la configuration du backend réellement exécuté
URL OAuth affichant une page du site	Vérifier le routage public vers l'API
Build absent de TestFlight	Vérifier soumission, traitement Apple, fiche cible et groupe

11. Exploitation et retour arrière

Prévoir la maintenance de l'authentification Apple avant le 29 janvier 2027. Après chaque changement de déploiement, vérifier santé, disponibilité et liste des fournisseurs, puis effectuer une connexion avec un compte de test.

Pour revenir à la configuration précédente, utiliser les sauvegardes de configuration et l'image API identifiées lors de l'intervention. Restaurer le routage antérieur si nécessaire. Conserver les tables ajoutées tant qu'une analyse n'a pas autorisé leur retrait. Ne pas restaurer toute la base par-dessus les actions récentes des utilisateurs pour annuler une simple activation OAuth.

12. Mise à jour du backend et redémarrage du 31 octobre

Le backend staging au commit bf1a35c a été déployé après construction de l'image snag-api:staging-bf1a35c-20261031. Il comprend :

• PR #608 : tri des recherches par les prix exacts enregistrés ;
• PR #610 : ordre des Double Packs One Piece ;
• PR #612 : disponibilité du mot de passe local dans les réglages du compte.

Validation : compilation réussie, 205 tests ciblés réussis et 5 ignorés. Aucune nouvelle migration n'était nécessaire. Les variables d'environnement et montages du conteneur API ont été comparés avant/après : identiques. Les 17 conteneurs actifs ont été redémarrés ; API, accès public et administration répondent HTTP 200. Les contrôles de santé des bases et modèles passent. La passerelle d'administration précédemment en erreur est redevenue saine. Cela ne constitue pas une recette complète du scan ou de la connexion Apple.

Procédure pour les déploiements suivants

1. Récupérer origin/staging, noter le commit et comparer avec l'image active.
2. Vérifier les migrations et changements de dépendances avant toute activation.
3. Exporter les sources suivies de ce commit, sans modifications locales ni fichiers privés.
4. Construire une image identifiée par le commit et exécuter les tests concernés.
5. Sauvegarder la configuration active dans le stockage d'exploitation protégé ; sauvegarder aussi la base avant une migration ou modification de données.
6. Lire les labels Compose du conteneur actif pour retrouver tous les fichiers de configuration superposés et le fichier d'environnement réellement utilisé. Le checkout historique du serveur ne décrit pas à lui seul l'état exécuté.
7. Ajouter une surcharge limitée à l'image API, conserver les autres réglages, puis recréer l'API avec --no-deps --no-build. Ne pas repartir du seul Compose de base.
8. Vérifier /healthz, /readyz, /auth/oauth/providers et les accès publics. Contrôler que les montages et paramètres effectifs ont été préservés.
9. Si un redémarrage général est demandé, redémarrer dans l'ordre : bases et cache, relais, modèles, API, interfaces et passerelles, observabilité, puis entrée publique. Vérifier ensuite chaque service ; un conteneur « Up » n'est pas une preuve de santé.
10. Conserver l'image précédente et les arguments Compose de retour arrière. Consigner commit, image, résultats de tests et contrôles dans le rapport d'exploitation.

Les détails privés d'exploitation restent dans le stockage protégé du serveur, pas dans ce dépôt. Ne pas copier un export complet de conteneur dans une PR.

Références

• Capacités iOS dans EAS
• Soumission iOS avec EAS
• Configurer Sign in with Apple pour le web
• Configurer le relais privé Apple