Trakio Docs

Build with Trakio.

Trakio Docs provides production contracts for tracking links, S2S conversion reporting, SDK ingestion, attribution, and partner postbacks.

Start integrating API health

Quickstart

A predictable attribution handoff

Connect the click, identity, and conversion without changing the identifiers Trakio issues.

Create a tracking link

Choose an approved campaign and preserve the generated Trakio Click ID through the user journey.

Use the correct credentials

Keep production API and SDK credentials isolated. Never expose an S2S key inside a client application.

Send or record events

Let the SDK own install, bind the new account, and report later outcomes only after backend-confirmed success.

S2S conversion endpoint

Report an advertiser event

Send a valid Click ID, approved external account binding, or qualifying-action proof. Reuse one idempotency key for every retry of the same logical event.

POST https://api.trakiommp.com/v1/conversions
Authorization: Bearer YOUR_PRODUCTION_KEY
Content-Type: application/json

{
  "campaign_id": "cmp_xxxxxxxxx",
  "event_name": "user_registered",
  "click_id": "clk_xxxxxxxxx",
  "external_user_id": "user_123",
  "browser_id": "first_party_browser_cookie_value",
  "user_ip": "203.0.113.10",
  "idempotency_key": "registered_user_123",
  "event_time": "2026-08-22T10:30:00+05:30"
}

Optional browser_id and user_ip values provide risk context only. Use an opaque first-party browser identifier and the real end-user IP where legally permitted; Trakio stores keyed hashes, not raw values. Do not send the advertiser server IP as user_ip.

Canonical events

install

Created automatically once for the SDK installation identity after initialization and analytics consent. Never call it manually. S2S-only advertisers may report their own install.

user_registered

Successful account creation after the backend confirms a genuinely new user. Never send it on login, OTP request, reopen, or failure.

application_submitted

A lead, order, application, or other qualifying action began on the current device. Capture one-time proof and persist it with the advertiser’s business record.

application_approved

A later verified outcome reported by the trusted advertiser backend. It can arrive while the app is closed by using the saved account, device, and qualifying-action proof.

qualified_action_completed

A universal final business outcome such as an approved lead, funded account, purchase, trade, or another campaign-specific success.

Identity and protected attribution

Stable external account

Set a stable, opaque advertiser-generated user ID after login or session restoration. Clear active identity before logout. Never use a phone number, email, OTP, token, or government ID.

Immutable acquisition

A new account can bind to its original acquisition click and SDK installation. Logging back into the same account preserves that history; another account never inherits it.

Security modes

MONITOR_ONLY records risk, ACCOUNT_ONLY validates account ownership, and ACCOUNT_AND_DEVICE requires the original account and device. Mismatches become pending review, not deleted.

Privacy-safe device proof

Trakio exposes an opaque dbn_… binding. Supporting App Set ID and permitted Advertising ID signals are scoped and hashed; raw device identifiers are never shown to advertisers.

Closed-app conversion handoff

Capture now, report the verified outcome later

Capture proof when a qualifying business action begins and store it with the lead, order, or application. The advertiser backend can then report the outcome after the app closes.

final proof = await Trakio.captureQualifyingAction(
  'application_submitted',
  advertiserActionId: 'application:${application.id}',
);

// Persist proof.qualifyingActionId (qac_…)
// and proof.deviceBindingId (dbn_…) with the record.

POST https://api.trakiommp.com/v1/conversions
Authorization: Bearer YOUR_PRODUCTION_KEY
X-Trakio-Timestamp: 1787918400
X-Trakio-Nonce: nonce_example_7rN2kP4v
X-Trakio-Signature: sha256=YOUR_HMAC_SHA256
Content-Type: application/json

{
  "schema_version": "2026-08",
  "campaign_id": "cmp_xxxxxxxxx",
  "event_name": "application_approved",
  "external_user_id": "user_123",
  "qualifying_action_id": "qac_xxxxxxxxx",
  "device_binding_id": "dbn_xxxxxxxxx",
  "advertiser_conversion_id": "application:456",
  "idempotency_key": "application_approved_456",
  "event_time": "2026-08-27T12:30:00+05:30"
}

advertiser_conversion_id must match the action ID used to issue the proof. Pending conversions create no payout or partner postback until an advertiser approves them.

Protected requests sign timestamp + "\n" + nonce + "\n" + sha256(canonical JSON) with the Bearer API key. Use a new URL-safe nonce for every attempt and keep server clocks synchronized.

Tracking contract

Trakio creates the Click ID. Partners may pass pcid and pid; advertisers must preserve trk_id unchanged. Legacy integrations may continue sending trk_click_id during migration.

Flutter Android SDK

Install a versioned package

Download the reviewed bundle, extract it under your app's vendor directory, and use the Production SDK key only in the Production build. The current Android release requires Dart 3.10+, Flutter 3.44+, Android API 24+, and Java 17. Native iOS ingestion remains coming soon; use S2S for iOS meanwhile.

Download SDK 1.1.0-rc.1

dependencies:
  trakio_flutter:
    path: vendor/trakio-sdk/trakio_flutter

await Trakio.setExternalUserId(user.attributionId);
await Trakio.trackEvent(
  'user_registered',
  advertiserEventId: 'registered_${user.attributionId}',
);
await Trakio.clearExternalUserId();

Reinstall, re-engagement, and device migration

Original acquisition

A reinstall or later campaign click never overwrites the immutable original acquisition. Re-engagement and retargeting history are stored separately.

Different device

In strict mode, the same account on another device—or another account on the original device—moves the event to pending review with an explicit reason code.

Permanent migration

Approving one suspicious conversion does not permanently move the account. Permanent rebinding requires a separate audited device-migration approval.

Attribution type

Configure each event to use ORIGINAL_ACQUISITION, LATEST_REENGAGEMENT, or LATEST_ELIGIBLE_CLICK.

Google Play attribution

1 · App signing

Copy the App signing key certificate SHA-256 from Play Console → Setup → App integrity. Remove colons and save the 64-character value on the Production SDK key.

2 · Referrer

Open a Trakio tracking link before installing from Play. The destination carries an encoded trk_id through Google Play Install Referrer.

3 · Important distinction

The signing-certificate SHA-256 is not the AAB file checksum. A new AAB normally keeps the same Play app-signing certificate.

4 · App Links and disclosure

Add an Android autoVerify intent filter for your application-owned HTTPS host and publish /.well-known/assetlinks.json without a redirect. The package name and Play app-signing certificate must match. Complete the host app’s privacy notice and Play Data safety disclosure before release.

Privacy, consent, and retention

Data minimization

Send only stable opaque account IDs and campaign evidence. Never send passwords, OTPs, bank details, government IDs, email addresses, or phone numbers to Trakio.

Device signals

App Set ID and a consented Advertising ID are scoped to the advertiser, application, and environment and stored only as one-way hashes. Raw values are excluded from reports, exports, postbacks, and advertiser-facing APIs.

Consent withdrawal

Apply changes with Trakio.setConsent(). Advertising withdrawal removes its retained signal; analytics withdrawal also clears retained device observations and the active external identity. Collection remains off until the host app enables it again lawfully.

Identifier reset

Advertising ID may be unavailable, limited, zeroed, or reset. App Set ID may change after reinstall, restore, signing changes, or extended inactivity. Neither identifier is sole proof of account ownership.

Deletion and retention

Verified deletion requests remove or pseudonymize account identity. Restricted non-identifying audit evidence may be retained only for configured security, dispute, legal, or preservation requirements. See the Data Retention Policy for default periods.

Store disclosure

Keep the host app privacy notice and Google Play Data safety and Advertising ID declarations aligned with the production SDK configuration and actual purposes of collection.

Postbacks and retries

GET endpoints support query-value macros including {pcid}, {partner_id}, {event}, {conversion_id}, {click_id}, {order_id}, {payout}, and {currency}. POST endpoints receive JSON and an X-Trakio-Signature. Non-2xx responses and timeouts retry with exponential backoff; configure 1–10 attempts and a 1–15 second timeout.

A URL containing {pcid} requires every promoted link to supply a real pcid. For verification, read X-Trakio-Timestamp and X-Trakio-Signature-Input. Sign the raw POST body or, for GET, the exact path and query. The expected value is v1=HMAC_SHA256(secret, timestamp + "." + input). Compare in constant time and reject stale timestamps.

Release validation

Identity

Use only a stable non-sensitive external user ID, set it after login and consent, and clear it before logout completes.

Deduplication

Reuse one deterministic advertiserEventId for SDK retries and one idempotency_key for S2S retries.

End-to-end

Tracking link → Play install → SDK install → new account → qualifying-action proof → closed-app S2S outcome → partner postback. Verify every hop in Live debugger, protected attribution, reports, and the delivery monitor.

Financial events

Send payout-driving events from the trusted advertiser backend through S2S. Do not treat a client-only SDK event as financial proof. Pending events produce neither payout nor postback.

Attribution states

Automatic lifecycle events with a missing or stale Click ID are retained as unattributed. Payable or custom business events keep strict validation and reject an invalid supplied Click ID.

Consent and reset

Apply privacy changes with Trakio.setConsent() and call Trakio.reset() for account deletion or an explicit shared-device reset. Trakio does not require a separate analytics-settings screen; the host app owns its lawful notice and consent experience.

Reinstall

An uninstall may create a new installation identity. Preserve the immutable account acquisition, evaluate the submitteddbn_… binding, and use stable advertiser IDs and idempotency keys. Do not rely on permanent device fingerprinting.

Event sequencing

Configure optional event order. Out-of-order events are retained as pending review with a reason code instead of being silently discarded.

Troubleshooting

Install is unattributed

Confirm the user opened a fresh Trakio tracking link before installing from Google Play, the package matches, and the encoded trk_id reached Play Install Referrer. A direct APK or ADB install cannot prove that deferred path.

Protected event is pending

Inspect the reason code and compare the submitted account and opaque device binding with the original acquisition. Missing, revoked, expired, or mismatched evidence is retained for advertiser review and produces no payout or postback.

Closed-app S2S is rejected

Reuse the saved qac_… and dbn_…, the same stable external user, and the advertiser action ID used when proof was captured. Sign the canonical request with a fresh nonce while preserving the same idempotency key.

Duplicate or out-of-order event

Reuse one deterministic SDK event ID or S2S idempotency key for the logical event. Verify the configured sequence and do not generate a new identifier for a network retry.

Postback keeps retrying

Check the delivery monitor, signature input, response status, and latency. Return a 2xx response within the configured timeout, then manually retry only after fixing the receiver.