Cœur JavaScript et référence de l’API

@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 (et son alias @traqio/expo) et @traqio/capacitor le réexportent avec leur bridge : cette page est donc la référence d’API des trois.

Installation#

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)#

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
});

interface InitOptions {
  sdkKey: string;
  endpoint: string;
  storage?: { getItem(key: string): Promise<string | null>; setItem(key: string, value: string): Promise<void> };
  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?)#

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
});

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.

trackAdRevenue(ad)#

// 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.

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é.

onDeepLink, handleUrl, getDeferredDeepLink#

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#

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é.

flush, appOpened#

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#

interface NativeBridge {
  platform: "ios" | "android";
  getInstallReferrer(): Promise<InstallReferrerResult>;   // Android; never rejects
  getContext?(): Promise<{ deviceModel?: string; osVersion?: string }>;
  updateConversionValue?(fine: number, coarse?: "low" | "medium" | "high", lockWindow?: boolean): void; // iOS
  getAttributionToken?(): Promise<string | null>;         // iOS 14.3+, Apple Ads
  getAdvertisingId?(): Promise<string | null>;            // 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é.

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.

Ce qu’il envoie#

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.

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.