# Cœur JavaScript et référence de l’API URL: https://traqio.app/fr/docs/sdks/javascript Last updated: 2026-10-22 @traqio/core, le moteur des SDK React Native, Expo et Capacitor : options d’init, méthodes, file d’attente, stockage et bridge natif, documentés une fois. `@traqio/core` est le moteur JavaScript de Traqio, indépendant de toute plateforme : la file hors ligne persistée, l’envoi par lots et les nouvelles tentatives, le pilote des valeurs de conversion SKAdNetwork, la transmission du jeton Apple Ads et la résolution des deep links. Il ne dépend ni de React Native, ni d’Expo, ni du navigateur ; tout ce qui est propre à une plateforme arrive par un **bridge natif**. [@traqio/react-native](https://traqio.app/fr/docs/sdks/react-native) (et son alias [@traqio/expo](https://traqio.app/fr/docs/sdks/expo)) et [@traqio/capacitor](https://traqio.app/fr/docs/sdks/capacitor) le réexportent avec leur bridge : cette page est donc la référence d’API des trois. ## Installation ```bash npm install @traqio/core ``` Uniquement pour une intégration directe. Sur React Native, Expo ou Capacitor, installez plutôt le paquet de la plateforme — il dépend du cœur à une version exacte. ## Référence de l’API Le SDK est un singleton, `Traqio`. Les appels faits pendant que `init` est encore en cours de résolution sont mis en file d’attente ; les appels faits avant que `init` ait été appelé sont ignorés — sauf `setConsent`, qui est conservé et écrit dès que le stockage est disponible. Initialisez d’abord. ### init(options) ```ts import { Traqio } from "@traqio/core"; await Traqio.init({ sdkKey: "YOUR_SDK_KEY", endpoint: "https://api.traqio.app", // origin only — the SDK appends the paths userId: currentUserId, // optional, settable later with setUserId storage, // { getItem, setItem } — see "Storage" native, // a NativeBridge; omit and there is no attribution }); ``` InitOptions: ```ts interface InitOptions { sdkKey: string; endpoint: string; storage?: { getItem(key: string): Promise; setItem(key: string, value: string): Promise }; native?: NativeBridge; userId?: string; appVersion?: string; collectContext?: boolean; // default true — model, OS, locale; never an advertising id testAds?: boolean; // AdMob test ad units: logged, never counted as revenue skan?: boolean; // iOS: drive SKAdNetwork conversion values (default true) appleAds?: boolean; // iOS: report the AdServices token (default true) deepLinking?: boolean; // default true consent?: boolean; // the user's answer to YOUR consent prompt, when known at launch collectAdvertisingId?: boolean; // default false — send the IDFA / GAID with the install (never prompts) } ``` Idempotent : un second appel ne fait rien. Au premier lancement, il signale l’installation une seule fois — sur Android avec l’Install Referrer de Google Play, en attendant jusqu’à trois lancements si Google Play est momentanément indisponible — puis résout le deep link différé, enregistre l’ouverture de l’app, récupère le mapping SKAdNetwork et transmet le jeton Apple Ads sur iOS. `endpoint` est l’origine seule : `https://api.traqio.app`. ### track(name, props?) ```ts Traqio.track("signup"); Traqio.track("purchase", { value: 9.99, currency: "EUR", transactionId: "2000000812345678", // the store's id for this purchase store: "app_store", // defaults to the platform's store }); ``` | Prop | Type | Signification | | --- | --- | --- | | value | number | Revenu déclaré par l’app — le SDK ne le vérifie pas contre un reçu. | | currency | string | Code ISO 4217. | | transactionId | string | L’identifiant de l’achat dans le store (transactionId StoreKit, orderId Play). Sert de clé à l’événement comme le fait RevenueCat, pour qu’un achat déclaré par les deux soit compté une seule fois. | | store | string | app_store · play_store · mac_app_store · amazon · stripe. Par défaut, le store de la plateforme. | Sur iOS, chaque événement valorisé fait aussi évoluer la valeur de conversion SKAdNetwork. Les noms sur lesquels Meta et TikTok peuvent s’optimiser sont listés dans [Noms d’événements](https://traqio.app/fr/docs/concepts/events-and-revenue#names). ### trackAdRevenue(ad) ```ts // In AdMob's paid-event callback, once per impression: Traqio.trackAdRevenue({ valueMicros: 21500, // the AdValue in micros — 0.0215 of the currency; never pre-round it currency: "USD", // ISO 4217, as AdMob reports it precision: "estimated", // AdMob's precisionType adUnitId: "ca-app-pub-0000000000000000/0000000000", adFormat: "rewarded", adSourceName: "AdMob Network", // the mediation source that filled it, when known }); ``` Les impressions ont leur propre file (jusqu’à 1 000, envoyées par lots de 100) et un identifiant de lot persisté avec elle : un crash entre l’envoi et la réponse ne peut donc pas compter deux fois les mêmes revenus. Avec `testAds: true`, elles sont journalisées par le serveur et jamais comptées. Voir [AdMob](https://traqio.app/fr/docs/integrations/admob). ### setUserId(id) Associe votre propre identifiant utilisateur à tout ce qui est envoyé à partir de là — utilisez la même valeur que celle que vous donnez à RevenueCat comme `app_user_id`. Appelez-le après la connexion. Voir [Identité](https://traqio.app/fr/docs/concepts/identity). ### onDeepLink, handleUrl, getDeferredDeepLink ```ts const unsubscribe = Traqio.onDeepLink(({ deepLink, code, deferred, via }) => { if (deepLink) router.push(deepLink); }); await Traqio.handleUrl(url); // hosts other than React Native: a URL opened the app await Traqio.getDeferredDeepLink(); // this install's deferred link, or null await Traqio.getInstallReferrer(); // Android: the raw Play Install Referrer ``` `onDeepLink` renvoie sa fonction de désabonnement. Chaque lien a `deepLink` (la destination définie sur le lien, ou null), `code` (le slug du lien), `deferred` et `via` (`referrer`, `ip_match` ou `link`). React Native câble `Linking` lui-même ; les autres hôtes appellent `handleUrl`. ### setConsent, forgetMe ```ts await Traqio.setConsent(userAgreed); // sharing with ad networks — not measurement const ok = await Traqio.forgetMe(); // erase this device and user on the server, then go silent if (!ok) showError(); // nothing changed on either side — let the user retry ``` `setConsent` est lu au moment de l’envoi : les événements mis en file avant un « non » partent sous le « non ». `forgetMe` est irréversible des deux côtés : le serveur supprime les données de l’appareil et de l’utilisateur, et le SDK se tait définitivement sur cette installation. Voir [Confidentialité](https://traqio.app/fr/docs/concepts/privacy). ### flush, appOpened ```ts Traqio.flush(); // send the queue now (React Native does it on background) Traqio.appOpened(); // the app came back to the foreground (React Native does it for you) ``` Une ouverture de l’app est signalée à l’`init` et à chaque retour au premier plan après au moins 30 minutes d’absence — la convention que partagent GA4, Adjust et AppsFlyer. C’est à partir d’elle qu’est calculée la rétention au jour *n*. ### Propriétés en lecture seule - `Traqio.forgotten` — true dès que `forgetMe()` a été honoré. - `Traqio.skanMapping` — le mapping des valeurs de conversion en vigueur sur cet appareil, une fois récupéré (iOS). ## Stockage Le stockage est ce qui fait que l’installation n’est signalée qu’une seule fois et que la file survit à un arrêt forcé. Le cœur accepte tout objet doté de méthodes async `getItem` / `setItem` ; sur React Native, il utilise automatiquement AsyncStorage quand l’app l’a installé. Sans stockage, il émet un avertissement au lancement et signale l’installation à nouveau à chaque démarrage. ## Le bridge natif ```ts interface NativeBridge { platform: "ios" | "android"; getInstallReferrer(): Promise; // Android; never rejects getContext?(): Promise<{ deviceModel?: string; osVersion?: string }>; updateConversionValue?(fine: number, coarse?: "low" | "medium" | "high", lockWindow?: boolean): void; // iOS getAttributionToken?(): Promise; // iOS 14.3+, Apple Ads getAdvertisingId?(): Promise; // only with collectAdvertisingId; never prompts } ``` Les paquets de plateforme l’implémentent. Sans bridge, le cœur envoie les événements mais n’a ni referrer ni SKAdNetwork — des événements, pas d’attribution. ## 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é. ```ts 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 avant`init`, 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 permission`com.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. ## Ce qu’il envoie | Requête | Quand | | --- | --- | | POST /ingest | L’installation (une fois), puis des lots d’événements de 20 au plus. File plafonnée à 500 événements. | | POST /ingest/session | Une ouverture de l’app — pas mise en file : une ouverture qui échoue est retentée à l’ouverture suivante. | | POST /ingest/ad-revenue | Lots d’impressions AdMob de 100 au plus. | | POST /ingest/adservices | iOS : le jeton d’attribution Apple Ads. | | GET /skan/mapping/ | iOS : le mapping des valeurs de conversion. | | POST /deeplink/deferred · /deeplink/open | Résolution des deep links. | | POST /privacy/forget | forgetMe(). | Chaque requête transporte la clé SDK, l’identifiant first-party de l’appareil et — une fois définis — votre identifiant utilisateur et la réponse de consentement. Pas d’identifiant publicitaire, sauf si vous activez `collectAdvertisingId` : l’installation le transporte alors. Ce sont les routes propres au SDK, pas un contrat public de serveur à serveur ; pour lire des données depuis vos serveurs, utilisez l’[API publique](https://traqio.app/fr/docs/api). ## Questions fréquentes **Puis-je utiliser @traqio/core seul ?** Oui, mais ce que vous obtenez seul, c’est l’ingestion d’événements, pas l’attribution : l’attribution a besoin des preuves de la plateforme — l’Install Referrer de Google Play, SKAdNetwork — que seul un bridge natif peut lire. Les apps sous React Native, Expo ou Capacitor doivent installer le paquet de leur plateforme, qui inclut le cœur et son bridge. **Les appels de tracking sont-ils bloquants, ou peuvent-ils lever une exception ?** Ni l’un ni l’autre. track() et trackAdRevenue() ne font qu’ajouter à une file en mémoire persistée dans le stockage ; l’envoi se fait en arrière-plan, par lots, avec un backoff exponentiel jusqu’à cinq minutes. Les erreurs réseau et HTTP sont absorbées par conception, ce qui explique aussi qu’un endpoint mal saisi échoue silencieusement.