SDK Expo

Le SDK Traqio pour Expo est @traqio/expo, un alias de @traqio/react-native : un seul paquet qui contient un module natif Expo (Kotlin et Swift) et le moteur JavaScript partagé. Sur Android, il lit l’Install Referrer de Google Play — la preuve déterministe du lien qui a généré l’installation — et sur iOS, il enregistre l’installation auprès de SKAdNetwork, définit les valeurs de conversion à partir de votre mapping et transmet le jeton d’attribution Apple Ads. Il ne lit ni l’IDFA ni le GAID, sauf si vous l’activez.

Prérequis#

• Expo SDK 51 ou ultérieur, React Native 0.74 ou ultérieur.
• Un development build ou EAS Build — pas Expo Go, qui ne peut pas charger un module natif tiers.
• iOS 15.1 ou ultérieur (la cible de déploiement du module). Android ne demande aucune permission (sauf si vous activez l’identifiant publicitaire).

Mise en place#

1. Installez le paquet#

   npx expo install @traqio/expo @react-native-async-storage/async-storage

   @react-native-async-storage/async-storage permet au SDK de se souvenir que l’installation a déjà été signalée et de conserver les événements en file d’attente entre deux redémarrages. Sans lui, le SDK émet un avertissement au lancement et signale l’installation à nouveau à chaque démarrage.

2. Compilez un development client#

   npx expo prebuild --clean
   npx expo run:android   # or: npx expo run:ios — a development build, not Expo Go

   Le prebuild génère les projets android/ et ios/ avec le module Traqio lié. Sur EAS, un eas build classique fait la même chose.

3. Initialisez au lancement#

   // app/_layout.tsx — once, at module level, before the first screen renders
   import { Traqio, getNativeBridge } from "@traqio/expo";
   import Constants from "expo-constants";
   
   Traqio.init({
     sdkKey: "YOUR_SDK_KEY",
     endpoint: "https://api.traqio.app",
     native: getNativeBridge(), // Install Referrer on Android, SKAdNetwork + Apple Ads on iOS
     appVersion: Constants.expoConfig?.version,
   });

   Appelez-le une seule fois, au niveau module, pour qu’il s’exécute avant le premier écran — pas dans un composant, où un nouveau rendu l’appellerait à nouveau (il est idempotent, mais un appel tardif rate le lien qui a ouvert l’app). getNativeBridge() renvoie undefined là où le module natif est absent (Expo Go, web, tests) : le SDK envoie alors toujours les événements mais ne peut pas attribuer.

4. Configurez app.json#

   Deux réglages natifs se trouvent dans app.json, et le prebuild les écrit dans les projets natifs :

   app.json

   {
     "expo": {
       "plugins": [["@traqio/expo", { "domains": ["go.example.com"] }]],
       "ios": {
         "infoPlist": {
           "NSAdvertisingAttributionReportEndpoint": "https://api.traqio.app"
         }
       }
     }
   }

   • NSAdvertisingAttributionReportEndpoint indique à iOS d’envoyer à Traqio une copie des postbacks SKAdNetwork de votre app. La valeur est l’origine seule — iOS ajoute son propre chemin.
   • Le plugin @traqio/expo fait que les liens de votre domaine personnalisé ouvrent l’app : il ajoute applinks:go.example.com à ios.associatedDomains et un intent filter autoVerify pour https://go.example.com/c/ à android.intentFilters. Remplacez go.example.com par votre propre domaine de tracking ; listez-en plusieurs si besoin. Avec EAS Build, Associated Domains est ensuite activé sur votre App ID pour vous — la suite, dont les empreintes Android, est dans Universal links en 2 minutes.

5. Suivez les événements et définissez l’identifiant utilisateur#

   // after sign-in — the SAME id you give RevenueCat (Purchases.logIn)
   Traqio.setUserId(user.id);

   Traqio.track("signup");
   
   Traqio.track("purchase", {
     value: 9.99,
     currency: "EUR",
     transactionId: purchase.transactionId, // the store's id: StoreKit transactionId, Play orderId
   });

   Utilisez les noms d’événements que Traqio fait correspondre aux événements standard de Meta et de TikTok — voir Noms d’événements. Passez le transactionId du store à chaque achat : grâce à lui, un achat déclaré à la fois par votre app et par RevenueCat est compté une seule fois.

Deep links avec Expo Router#

Un seul callback reçoit à la fois le lien qui a ouvert l’app installée et le lien qui a mené à une nouvelle installation. Le Linking de React Native est branché par le SDK : rien d’autre à transmettre.

import { router } from "expo-router";

// Direct opens AND the deferred link of a fresh install, one callback.
Traqio.onDeepLink(({ deepLink }) => {
  if (deepLink) router.push(deepLink); // "/product/42"
});

Un lien résolu avant le montage de l’écran qui porte ce callback est conservé et livré à l’abonnement : un démarrage à froid ne le perd donc pas.

Notes par plateforme#

Android#

• Le module déclare une entrée <queries> pour le Play Store. Sans elle, Android 11+ masque Google Play aux apps qu’il n’a pas installées, et le referrer apparaît comme absent sur les builds de développement.
• Quand Google Play est momentanément indisponible au premier lancement, le SDK ne signale pas l’installation comme organique : il réessaie aux lancements suivants (jusqu’à trois) avant de la signaler sans referrer.

iOS#

• Le SDK n’affiche jamais d’invite App Tracking Transparency et n’en a pas besoin : SKAdNetwork et le jeton Apple Ads fonctionnent sans elle.
• Les valeurs de conversion suivent le mapping que vous publiez dans la console ; publiez-le avant votre première campagne iOS. Voir Attribution iOS.

Identifiant publicitaire (à activer)#

Désactivé par défaut : le SDK n’envoie ni IDFA ni GAID. Activez collectAdvertisingId seulement si vous achetez sur des régies qui attribuent par l’identifiant publicitaire — Unity Ads et AppLovin rattachent leur clic à votre installation grâce à lui. Il est envoyé avec l’installation et ne lui sert jamais d’identité.

Traqio.init({
  sdkKey: "YOUR_SDK_KEY",
  endpoint: "https://api.traqio.app",
  native: getNativeBridge(),
  collectAdvertisingId: true, // off by default
});

• iOS : le SDK n’affiche jamais l’invite App Tracking Transparency — demandez-la vous-même avantinit, et liez AdSupport. L’IDFA n’est lu que si l’utilisateur a déjà autorisé le suivi.
• Android : ajoutez com.google.android.gms:play-services-ads-identifier et la permissioncom.google.android.gms.permission.AD_ID à votre app ; le SDK ne déclare ni l’une ni l’autre.
• Déclarez l’identifiant publicitaire dans vos informations de confidentialité App Store et le formulaire Sécurité des données de Google Play.

Configuration et API#

Chaque option de init et chaque méthode — setConsent, forgetMe, trackAdRevenue, getInstallReferrer — est documentée une seule fois, dans la référence de l’API JavaScript. Les options que vous définirez le plus probablement :

Questions fréquentes#

Le SDK Traqio fonctionne-t-il dans Expo Go ?

Non. Le SDK inclut un module natif — il lit l’Install Referrer de Google Play sur Android et pilote SKAdNetwork sur iOS — et Expo Go ne contient que les modules natifs fournis par Expo. Utilisez un development build (npx expo run:android / run:ios) ou EAS Build. Dans Expo Go, la partie JavaScript envoie toujours les événements, mais sans le module natif il n’y a pas d’attribution.

Quelle est la différence entre @traqio/expo et @traqio/react-native ?

Aucune en matière de comportement : @traqio/expo est un alias qui réexporte @traqio/react-native, épinglé à une version exacte, pour que le SDK soit trouvable sous le nom Expo. Installez l’un des deux, jamais les deux — deux copies feraient tourner deux files d’événements et compteraient chaque installation deux fois.

Ai-je besoin d’un config plugin ?

Pas pour le SDK : l’autolinking d’Expo lie le module natif pendant le prebuild. Pour les deep links, @traqio/expo fournit un config plugin facultatif — ["@traqio/expo", { "domains": ["go.example.com"] }] dans app.json ajoute l’entrée Associated Domains côté iOS et l’intent filter App Links côté Android pour votre domaine personnalisé, sans doublonner ce que vous déclarez déjà. L’endpoint SKAdNetwork reste dans ios.infoPlist.