expo-adtrackeus

Mobile attribution SDK for Expo apps, with Meta Ads as the first partner.

Install

pnpm add expo-adtrackeus

Config Plugin

{
  "expo": {
    "plugins": [
      [
        "expo-adtrackeus",
        {
          "trackingDescription": "We use your data to measure install attribution.",
          "skanReportEndpoint": "https://attribution.yourdomain.com",
          "skanNetworkIds": ["v9wttpbfk9.skadnetwork", "n38lu8286q.skadnetwork"]
        }
      ]
    ]
  }
}

Then run npx expo prebuild --clean followed by npx expo run:ios|android.

Usage

import Adtrackeus from 'expo-adtrackeus';

await Adtrackeus.init({
  appToken: 'app_xxxxx',
  serverUrl: 'https://attribution.yourdomain.com',
  logLevel: 'info',
  autoSessionTracking: true,
  autoRequestTrackingPermission: false,
  conversionValueSchema: {
    events: { signup: 1, tutorial_complete: 2, purchase: 10 },
    revenueBuckets: [
      { maxAmount: 5, value: 20, currency: 'USD' },
      { maxAmount: 20, value: 30, currency: 'USD' },
      { maxAmount: 100, value: 40, currency: 'USD' },
    ],
  },
});

await Adtrackeus.requestTrackingPermission();
await Adtrackeus.trackEvent('signup', { method: 'email' });
await Adtrackeus.trackEvent({
  name: 'purchase',
  revenue: 9.99,
  currency: 'USD',
  orderId: 'ord_123',
  params: { product: 'pro_monthly' },
});

API

| Function | Description | | --- | --- | | init(opts) | Initializes the SDK, fires /install and starts the flush loop | | trackEvent(name, params?) or trackEvent({ name, revenue, currency, orderId, params }) | Sends an event | | setUserId(userId, traits?) | Links the device to a user identity (see "User identity" below) | | clearUserId() | Forgets the linked user — use on logout or GDPR opt-out | | requestTrackingPermission() | Triggers the iOS ATT prompt; on Android returns 'authorized' | | getTrackingAuthorizationStatus() | Current ATT status | | getAttribution() | Attribution captured via deep link / install referrer | | getDeviceInfo() | Snapshot of device info | | flush() | Forces an immediate flush of the pending queue |

User identity

Call setUserId(userId, traits) after login/signup so the Adtrackeus dashboard shows real users instead of anonymous device ids, and so events get hashed PII for Meta CAPI to boost Event Match Quality.

await Adtrackeus.setUserId('user_42', {
  email: '[email protected]',
  phone: '+14155551234',
  firstName: 'Jane',
  lastName: 'Doe',
  // anything else you want stored — visible as JSON in the device detail
  plan: 'pro',
  city: 'Quito',
});

After this call, every subsequent trackEvent automatically carries userId, userEmail, userPhone, and name fields. The server-side worker hashes them with sha256 (lowercase + trimmed for email; digits-only for phone) before forwarding to Meta — your raw values never leave your backend.

Trait conventions

| Key | Effect in dashboard | Effect in Meta CAPI | | --- | --- | --- | | name | Shown as the device's primary identity | — | | firstName / lastName | Combined into name when both present | Hashed as fn / ln | | email | Shown below the name | Hashed as em | | phone | Shown below the name | Hashed as ph (digits only) | | anything else | Stored in user_links.traits (jsonb), shown as JSON in the device detail | Ignored unless you map it explicitly server-side |

Logout / opt-out

await Adtrackeus.clearUserId();

This drops the user_links row server-side and clears the in-memory user, so subsequent events won't carry the previous user's PII.

Privacy note: raw email/phone live in your own Postgres (user_links.traits) — never in Meta. For GDPR/CCPA "right to forget", call clearUserId() and delete the user's user_links and event rows from your backend.

Platforms

• iOS 15.1+ (Swift, ATT, SKAdNetwork v2/3/4)
• Android API 23+ (Kotlin, GAID, Install Referrer)

iOS/Android simulators do not run inside Docker. To test native code, run from the host via npx expo run:ios / run:android.

Repo layout

.
├── src/                      # TypeScript SDK source
├── plugin/                   # Expo Config Plugin source
├── ios/                      # Swift native module (AdtrackeusModule)
├── android/                  # Kotlin native module (expo.modules.adtrackeus)
├── example/                  # Sample Expo app that consumes the SDK locally
├── expo-module.config.json
├── app.plugin.js
├── package.json
└── README.md

The example/ directory is a working Expo app you can run against a local backend to test changes end-to-end. It depends on the SDK via "expo-adtrackeus": "file:..", so any pnpm build at the SDK root is picked up by the next Metro bundle.

Development

pnpm install
pnpm build                       # tsc + plugin tsc
pnpm typecheck                   # both projects
npm pack --dry-run               # see what would ship

cd example
pnpm install
EXPO_PUBLIC_APP_TOKEN=app_xxxx \
EXPO_PUBLIC_SERVER_URL=http://localhost:4000 \
  npx expo prebuild --clean
npx expo run:ios

Publishing

pnpm build
npm publish               # uses `prepublishOnly: pnpm build` as a safety net

For prereleases, bump with npm version prerelease --preid=beta and publish with npm publish --tag next.