Núcleo JavaScript y referencia de la API

@traqio/core es el motor JavaScript de Traqio independiente de la plataforma: la cola sin conexión persistida, el envío por lotes y los reintentos, el gestor de valores de conversión de SKAdNetwork, el envío del token de Apple Ads y la resolución de deep links. No depende de React Native, de Expo ni del navegador; todo lo específico de cada plataforma llega a través de un bridge nativo. @traqio/react-native (y su alias @traqio/expo) y @traqio/capacitor lo reexportan con su bridge, así que esta página es la referencia de la API de los tres.

Instalación#

npm install @traqio/core

Solo para una integración directa. En React Native, Expo o Capacitor, instala en su lugar el paquete de la plataforma, que depende del núcleo en una versión exacta.

Referencia de la API#

El SDK es un singleton, Traqio. Las llamadas hechas mientras init aún se está resolviendo se ponen en cola; las hechas antes de llamar a init se ignoran, salvo setConsent, que se conserva y se escribe en cuanto el almacenamiento está disponible. Inicializa primero.

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

Idempotente: una segunda llamada no hace nada. En el primer arranque informa de la instalación una sola vez (en Android con el Play Install Referrer, esperando hasta tres arranques si Google Play no está disponible momentáneamente), luego resuelve el deep link diferido, registra la apertura de la app, obtiene el mapeo de SKAdNetwork e informa del token de Apple Ads en iOS. endpoint es solo el origen: 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
});

En iOS, cada evento con valor también actualiza el valor de conversión de SKAdNetwork. Los nombres con los que Meta y TikTok pueden optimizar se enumeran en Nombres de eventos.

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

Las impresiones tienen su propia cola (hasta 1.000, enviadas en lotes de 100) y un id de lote persistido con ella, así que un cierre inesperado entre el envío y la respuesta no puede contar dos veces los mismos ingresos. Con testAds: true el servidor las registra y nunca las cuenta. Consulta AdMob.

setUserId(id)#

Asocia tu propio id de usuario a todo lo que se envíe a partir de entonces: usa el mismo valor que le das a RevenueCat como app_user_id. Llámalo después del inicio de sesión. Consulta Identidad.

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 devuelve su función para cancelar la suscripción. Cada enlace tiene deepLink (el destino definido en el enlace, o null), code (el slug del enlace), deferred y via (referrer, ip_match o link). React Native conecta Linking por sí solo; los demás entornos llaman a 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 se lee en el momento del envío, así que los eventos puestos en cola antes de un “no” salen bajo ese “no”. forgetMe es irreversible en ambos lados: el servidor borra los datos del dispositivo y del usuario, y el SDK queda en silencio para siempre en esta instalación. Consulta Privacidad.

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)

Se informa de una apertura de la app en init y en cada vuelta al primer plano tras al menos 30 minutos fuera: la convención que comparten GA4, Adjust y AppsFlyer. Es la base para calcular la retención del día n.

Propiedades de solo lectura#

• Traqio.forgotten: true una vez que se ha atendido forgetMe().
• Traqio.skanMapping: el mapeo de valores de conversión vigente en este dispositivo, una vez obtenido (iOS).

Almacenamiento#

El almacenamiento es lo que hace que la instalación se envíe exactamente una vez y que la cola sobreviva a un cierre forzado. El núcleo acepta cualquier objeto con getItem / setItem asíncronos; en React Native usa AsyncStorage automáticamente cuando la app lo tiene. Sin almacenamiento, muestra una advertencia al arrancar y vuelve a informar de la instalación en cada inicio.

El bridge nativo#

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
}

Lo implementan los paquetes de cada plataforma. Sin bridge, el núcleo envía eventos pero no tiene referrer ni SKAdNetwork: eventos, no atribución.

Identificador publicitario (opcional)#

Desactivado por defecto: el SDK no envía ni IDFA ni GAID. Activa collectAdvertisingId solo si compras en redes que atribuyen por el identificador publicitario — Unity Ads y AppLovin vinculan su clic con tu instalación gracias a él. Se envía con la instalación y nunca se usa como su identidad.

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

• iOS: el SDK nunca muestra el aviso de App Tracking Transparency — pídelo tú antes de init y enlaza AdSupport. El IDFA solo se lee si el usuario ya permitió el seguimiento.
• Android: añade com.google.android.gms:play-services-ads-identifier y el permisocom.google.android.gms.permission.AD_ID a tu app; el SDK no declara ninguno de los dos.
• Declara el identificador publicitario en los detalles de privacidad de la App Store y en el formulario de Seguridad de los datos de Google Play.

Qué envía#

Cada petición lleva la clave SDK, el id propio del dispositivo y, una vez definidos, tu id de usuario y la respuesta de consentimiento. Ningún identificador publicitario, salvo que actives collectAdvertisingId: entonces la instalación lo lleva. Estas son las rutas propias del SDK, no un contrato público de servidor a servidor; para leer datos desde tus servidores, usa la API pública.

Preguntas frecuentes#

¿Puedo usar @traqio/core por sí solo?

Sí, pero lo que obtienes por sí solo es la ingesta de eventos, no la atribución: la atribución necesita las pruebas de la plataforma (el Install Referrer de Google Play, SKAdNetwork) que solo un bridge nativo puede leer. Las apps en React Native, Expo o Capacitor deben instalar el paquete de su plataforma, que incluye el núcleo y su bridge.

¿Las llamadas de registro son bloqueantes o pueden lanzar excepciones?

Ni lo uno ni lo otro. track() y trackAdRevenue() solo añaden a una cola en memoria persistida en el almacenamiento; el envío se hace en segundo plano, por lotes, con backoff exponencial hasta cinco minutos. Los errores de red y HTTP se ignoran por diseño, y por eso también un endpoint mal escrito falla en silencio.