Capture afos_click_id on your site or app

On a website: read it on the landing page

We add afos_click_id to your campaign landing URL and keep the parameters already on it:

https://www.tidewater.example/play?ref=summer&afos_click_id=<click id>

Read it when the page loads and hand it to your own server, which keeps it with the visitor until they sign up:

const clickId = new URLSearchParams(location.search).get("afos_click_id");
if (clickId) {
  fetch("/api/afos-click", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ clickId }),
  });
}

Keep it in a first-party cookie or your session, then attach it to the account on your server when the visitor signs up. Your API key never goes in browser code.

In an Android app: read the install referrer

The Play Store drops query parameters at install, so we also put afos_click_id=<click id> in the Play Store link’s referrer, after any referrer you set yourself. On first launch, read the referrer once with Google’s Play Install Referrer library, parse it like a query string and send the value to your server.

In an iOS app: match the install from your server

When a new user first opens your app, your server calls:

curl -X POST "https://affiliateos.xyz/v1/advertiser/match-install" \
  -H "Authorization: Bearer $AFOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "appId": "<your appId>",
    "platform": "ios",
    "ip": "<the device public IP your server saw>"
  }'

We look for the most recent unclaimed tap on your campaign from that IP address in the last 24 hours, made on the same kind of device or one we couldn’t identify, and answer with one of these:

{ "clickId": "<click id>", "clickedAt": "<when they tapped>" }
{ "clickId": null }

Store a returned clickId as the user’s afos_click_id. Each tap matches one install at most. Call it once per new user, soon after the first open. A null usually means the install didn’t come from us, so don’t retry it in a loop. This works for Android apps too.

With an attribution tool: read it from the install data

Use your tool’s links as your product’s App Store URL and Google Play URL. The afos_click_id we add rides along, and you read it on your server from the tool’s install data. Details: Forward events from AppsFlyer or Adjust.

Store it on the user

Save the click ID on your user record, or on an install record until the user signs up. Keep the first one: don’t overwrite it with a later click unless you’ve decided to credit the last one.

Check it worked

A test event doesn’t check this step, so your first live events do. Open Event logs on the campaign: approved means the click ID matched a tap. missing_attribution means the event came without one, or with a value we never issued.

What to send with the click ID is in Send events server to server (S2S).