# SDK Capacitor

URL: https://traqio.app/fr/docs/sdks/capacitor
Last updated: 2026-10-22

Ajoutez Traqio à une app Capacitor ou Ionic : @traqio/capacitor lit l’Install Referrer et fait tourner le moteur JS ; votre app câble stockage et cycle de vie.

`@traqio/capacitor` est le SDK Traqio pour les apps Capacitor et Ionic. Il fait tourner le même moteur JavaScript que le SDK React Native — [@traqio/core](https://traqio.app/fr/docs/sdks/javascript), avec sa file d’attente, les identifiants de transaction des stores, les revenus publicitaires AdMob, le consentement et l’effacement depuis l’app — et ajoute un petit plugin natif : il lit **l’Install Referrer de Google Play** sur Android et, sur iOS, enregistre l’installation auprès de **SKAdNetwork**, définit ses valeurs de conversion et transmet le jeton **Apple Ads**. Comme Capacitor n’est pas React Native, deux choses que le SDK React Native fait tout seul sont à câbler de votre côté : le stockage persistant et le cycle de vie de l’app.

## Prérequis

- `@capacitor/core` 5 ou ultérieur. Le plugin Android est compilé avec Capacitor 6.
- `@capacitor/preferences` (stockage) et `@capacitor/app` (cycle de vie et URL).
- Android 5.1 (API 22) ou ultérieur ; iOS 13 ou ultérieur (attribution Apple Ads à partir d’iOS 14.3).

## Mise en place

### Installez les paquets

```bash
npm install @traqio/capacitor @capacitor/preferences @capacitor/app
npx cap sync
```

### Initialisez avec un stockage

```ts
import { App } from "@capacitor/app";
import { Preferences } from "@capacitor/preferences";
import { Traqio, getNativeBridge } from "@traqio/capacitor";

// Persistence is what makes the install fire exactly once — Capacitor has no default.
const storage = {
  getItem: async (key: string) => (await Preferences.get({ key })).value,
  setItem: (key: string, value: string) => Preferences.set({ key, value }),
};

await Traqio.init({
  sdkKey: "YOUR_SDK_KEY",
  endpoint: "https://api.traqio.app",
  native: getNativeBridge(),
  storage,
});

// Capacitor has no React Native AppState: wire the lifecycle and the URLs yourself.
App.addListener("appStateChange", ({ isActive }) => (isActive ? Traqio.appOpened() : Traqio.flush()));
App.addListener("appUrlOpen", ({ url }) => void Traqio.handleUrl(url));
```

> **Ne sautez pas l’adaptateur de stockage** Sans lui, le SDK ne peut pas se souvenir que l’installation a été signalée : il émet un avertissement dans la console et la signale à nouveau à chaque lancement.

### Câblez le cycle de vie et les URL

Les deux dernières lignes de l’extrait ci-dessus : `appOpened()` quand l’app revient au premier plan — dédoublonné par un délai de session de 30 minutes, donc appelez-le à chaque reprise —, `flush()` quand elle passe en arrière-plan, et chaque URL qui ouvre l’app vers `handleUrl`. Seules les URL de tracking Traqio quittent l’appareil.

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

```ts
Traqio.setUserId(user.id); // after sign-in — same id as RevenueCat's app_user_id
Traqio.track("purchase", { value: 9.99, currency: "EUR", transactionId: purchase.transactionId });
```

L’ensemble de l’API — `trackAdRevenue`, `setConsent`, `forgetMe`, `getDeferredDeepLink` — est dans la [référence de l’API JavaScript](https://traqio.app/fr/docs/sdks/javascript#reference).

## Pas encore dans ce SDK

- **Nouvelles tentatives de l’Install Referrer.** Le referrer est lu une seule fois ; si Google Play ne répond pas au premier lancement, l’installation est signalée comme organique.

> **Preuves à ce jour** Le TypeScript est vérifié au typecheck, compilé et testé en CI. Le code natif du plugin, iOS et Android, n’est pas compilé en CI, et le plugin n’a pas encore tourné dans une app Capacitor en production.

## Questions fréquentes

**Pourquoi le SDK Capacitor a-t-il besoin d’un adaptateur de stockage ?**
Le SDK doit se souvenir qu’il a déjà signalé l’installation, et conserver les événements en file d’attente entre deux redémarrages. Sur React Native, il trouve AsyncStorage tout seul ; Capacitor n’a pas d’équivalent dont il puisse supposer la présence, donc vous lui en passez un — quelques lignes au-dessus de @capacitor/preferences. Sans lui, l’installation est signalée à nouveau à chaque lancement.

**Le SDK Capacitor attribue-t-il les installations iOS ?**
Oui, comme le SDK React Native. Le plugin iOS enregistre chaque installation auprès de SKAdNetwork à son chargement, définit les valeurs de conversion à partir du mapping publié dans la console à mesure que des événements avec une valeur arrivent, et transmet le jeton Apple Ads à partir d’iOS 14.3, que le serveur résout auprès d’Apple. Ni demande de suivi, ni IDFA — l’option d’identifiant publicitaire du SDK React Native n’est pas encore dans ce plugin.