# Mobile and installs

Carrying a click through an install, and what iOS cannot do.

## What the gap is

A viewer taps a creator's link on a phone, lands in the store, installs your app, and signs up there. Between the tap and the signup the browser is gone: no cookie, no referrer header, no session. Attribution across that gap is a handshake your app has to take part in, and this page is that handshake.

The click already happened and already has an id. The whole job is carrying that id from the tap into your app, and then telling us which of your users it became.

## Android: the install referrer

If a campaign's destination is a Play Store URL, the redirect appends the click id to the store's own referrer parameter. Google preserves it through the install and hands it to your app on first launch. You do not have to ask for this and there is nothing to configure.

```bash
https://play.google.com/store/apps/details?id=com.yourapp&referrer=acr_cid%3D8fk2xq...
```

> Read it once, on first launch, and keep it until you have a user. The referrer is available before anybody has signed up, which is exactly the wrong moment to report it: the call that matters needs a user id, and that arrives later.

Your own referrer parameters survive. We add acr_cid to whatever is already in referrer rather than replacing it, so an existing utm_source is still there when you read it.

## Binding the click to a user

When your app has a user, at signup, or at first sign-in if the install was silent, send the click id and your own id for that user. That is the join, and everything they buy afterwards resolves through it.

```bash
curl -X POST "https://track.acrune.com/v1/identities" \
  -H "Authorization: Bearer $ACRUNE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"clickId":"8fk2xq...","externalUserId":"usr_4471"}'
```

> Never ship an API key in an app. Anything shipped to a device is public: it can be pulled out of the binary in minutes, and a write key that escapes can enrol creators and report conversions on your account. The app sends the click id to your own backend, and your backend makes this call.

Safe to call on every session. A repeat returns the binding that already exists rather than replacing it, because a later click must not silently reassign who brought the user in. Do not try to be clever about calling it once.

If the web handoff already gave you a click id, the user opened your site first and you carried it into the app yourself, use that one and do not report a second open.

## iOS, and what it cannot do

Apple discards install referrers. There is no equivalent of the Android hop and there will not be one, so the click id cannot survive an App Store install. That is a property of the platform rather than a gap in this API, and we would rather say so than invent a fingerprint match and call the result attribution.

Two honest routes, and which one you take is a product decision rather than an integration detail.

- A promo code. The creator says a word, the viewer types it at signup or at checkout, and the code resolves to that creator with no click ever having existed. This is the strongest mechanism that works on iOS with no bridge at all, and it is why codes matter more than they look.
- Ask them. A how-did-you-hear-about-us at signup, reported to POST /v1/identities/self-reported, records the claim at its own weak tier. It is the only thing that works when there was no code and no link, which on iOS is most of the time.
- A deferred deep link on first launch, if you already run one. If your link provider hands your app a payload on first open, put the click id in it and call /v1/identities with it exactly as Android does.

> What we will not do is match an install to a click by device characteristics. It is a guess with a confidence nobody can verify, and a creator paid on a guess is a creator who cannot be told why.

## Asking them, when nothing else can answer

When there was no tap and no code, the person is the only witness. A how-did-you-hear-about-us at signup, with your creators as the options, is the difference between crediting somebody and crediting nobody.

```bash
curl -X POST "https://track.acrune.com/v1/identities/self-reported" \
  -H "Authorization: Bearer $ACRUNE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"externalUserId":"usr_4471","handle":"apexlaps","platform":"tiktok"}'
```

Name the creator one of three ways and exactly one: handle with platform, your own creatorExternalId for them, or a code they remembered. A code sent here identifies a creator and is not redeemed, so no cap is spent and a disabled code still says who they meant.

> It never beats a real click. If that user is already bound by a tap, the binding stands and the response says supersededBy. A tap is evidence and a claim is not, so the weaker one cannot displace the stronger by arriving later, including a second self-report naming somebody else.

And it never pays on its own. A sale attributed this way settles at the self_reported tier, at 0.200 confidence, in review, so a person decides before money moves. That is deliberate: somebody may be guessing, may name the creator they like rather than the one they saw, and a creator can tell their audience which name to pick.

Safe to call on every signup. Repeats are idempotent on the user and the creator, so a form submitted twice produces one claim.

## And then the purchase

A conversion reported later resolves strongest claim first: a click id if you have one, then a promo code, then the binding made at signup. So the binding is what makes a purchase weeks after the install still land on the right creator.

```bash
curl -X POST "https://track.acrune.com/v1/conversions" \
  -H "Authorization: Bearer $ACRUNE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"externalId":"usr_4471","idempotencyKey":"sub_88412","grossMinor":4900,"currency":"USD"}'
```

externalId alone is the in-app purchase case: there is no checkout to carry a click id and no code was typed, and the binding is the only thing that knows whose user this is. That is the entire reason /v1/identities exists.
