SDK API

POST /v1/events and /v1/identify

Send in-app events in batches, and link a user to an install.

POST https://attribution.ondropp.app/v1/events
POST https://attribution.ondropp.app/v1/identify
Content-Type: application/json
X-Key-Id: ak_3f9c1e2a7b6d4c80
X-Timestamp: 1760700000
X-Signature: <signature>

The calls the SDK makes for track and identify, signed with the app's SDK key like /v1/init. Only build these yourself if you integrate without the SDK. From a backend, use the server API instead.

POST /v1/events#

Up to 100 events in one request, 64 KB at most.

Request body

{
  "installId": "6f1c2a9e-3b7d-4c51-9a8e-2d4f6b1c0e73",
  "events": [
    { "eventId": "3f2b8c1d-5e6a-4b7c-9d8e-0f1a2b3c4d5e", "name": "add_to_cart", "ts": 1760700100,
      "props": { "sku": "TSHIRT-M", "qty": 1 } },
    { "eventId": "7a6b5c4d-3e2f-4a1b-8c9d-0e1f2a3b4c5d", "name": "purchase", "ts": 1760700200,
      "revenue": { "amount": 499, "currency": "INR", "orderId": "A1023" } }
  ]
}

Field	Rules
`installId`	The UUID sent to `/v1/init`.
`eventId`	A UUID created when the event is tracked and kept with it, so every retry sends the same one. That's what makes retries safe.
`name`	`snake_case`: `^[a-z][a-z0-9_]{0,63}$`.
`ts`	When it happened, unix seconds. Within the last 7 days; up to 10 minutes ahead is treated as now.
`props`	Optional. Up to 20 keys of `[A-Za-z0-9_]{1,40}`. Values are text (up to 256 characters), numbers, booleans or `null`. A value containing an email or that is a phone number is dropped and listed in `warnings`.
`revenue`	Optional. `amount` 0 or more with at most 2 decimals, `currency` an ISO 4217 code like `INR`, optional `orderId` (up to 128). Shown as app-reported.

200 OK

{
  "accepted": 1,
  "duplicates": 0,
  "rejected": [{ "index": 1, "eventId": "7a6b5c4d-…", "code": "too_old", "message": "ts is more than 7 days ago" }],
  "warnings": [{ "eventId": "3f2b8c1d-…", "code": "pii_in_props", "props": ["email"] }]
}

Field	Meaning
`accepted`	New events stored.
`duplicates`	Events an earlier attempt already stored.
`rejected`	Events that will never be accepted: `invalid_event`, `too_old` or `too_far_in_future`. `index` is the position in the request.
`warnings`	Events stored with some properties removed because they looked like personal data.

Each event is checked on its own, so one bad event doesn't fail the batch. After a 200, remove every event in the batch from your queue: accepted, duplicates and rejected.

Response	Do
`404 unknown_install`	Dropplink hasn't seen this install. Call `/v1/init`, then send the batch again.
`429 rate_limited`	Wait `Retry-After` seconds, then send the same batch. The limit is 600 events a minute per install.
`503 storage_unavailable`	Nothing was kept. Wait `Retry-After` seconds and send the whole batch again.

POST /v1/identify#

Request body

{
  "installId": "6f1c2a9e-3b7d-4c51-9a8e-2d4f6b1c0e73",
  "userId": "user_8812",
  "traits": { "emailHash": "<sha256 hex>", "phoneHash": "<sha256 hex>" }
}

Field	Rules
`userId`	Your own user ID, 1–128 characters. `null` logs the user out. An email or phone number is refused with `400 pii_in_user_id`.
`traits.emailHash`	Optional. Lower-case hex SHA-256 of the trimmed, lower-cased email.
`traits.phoneHash`	Optional. Lower-case hex SHA-256 of the phone in E.164, like `+919876543210`. Plain values are refused.

200 OK

{ "installId": "6f1c2a9e-3b7d-4c51-9a8e-2d4f6b1c0e73", "userId": "user_8812" }

404 unknown_install: call /v1/init first. The limit is 5 identifies a minute per install, so only send one when the user changes. See Users and revenue credit for how the user's creator is decided.

Sending reliably#

If you build your own client, do what the SDK does:

Save each event, with its eventId and ts, to storage on the device before sending it.
Send after a short pause (about a second), when the app goes to the background, and on every launch after /v1/init succeeds.
Keep events on network errors, 429 and 5xx, and retry with exponential backoff from 1 second to 5 minutes, honouring Retry-After.
Send an identify before the events tracked after it, so they carry the user.
Cap what's waiting (the SDK keeps 1,000 events) and drop the oldest events without revenue first.

Other errors: Errors.