> ## Documentation Index
> Fetch the complete documentation index at: https://docs.appeeky.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Attribution

> How Appeeky Analytics gives each install a source, and which source wins when several apply

Every install gets exactly one source. The SDK collects what it needs once, on the first launch, and the server turns it into a source. Revenue from that install is then credited to that source, its campaign and, for Apple Search Ads, its keyword.

***

## Sources

| Source | Value in the API | How it is detected |
| - | - | - |
| Apple Search Ads | `apple_search_ads` | The AdServices attribution token from the device, exchanged with Apple for the campaign, ad group and keyword. Needs the native module on iOS (or `getAdServicesToken`). |
| Smart link | `smart_link` | Android: the Play install referrer names the link. iOS: the link opened the installed app on its first launch. See [Smart Links](https://docs.appeeky.com/docs/analytics-smart-links.md). |
| Campaign link | `campaign_link` | The URL the app was first opened with carries `aky_c=<campaign>` or `utm_*` parameters. Read automatically through `Linking.getInitialURL()`. |
| Google Play referrer | `play_referrer` | The Play Install Referrer carries `utm_*` campaign parameters. Needs the native module on Android (or `getInstallReferrer`). |
| Organic | `organic` | Everything else: store search, browse, and installs with no campaign. |

In breakdowns, sales that are not linked to any install show on an empty source row ("Unattributed"). See [Revenue](https://docs.appeeky.com/docs/analytics-revenue.md#unattributed-sales).

***

## Precedence

When more than one signal is present, the first match wins:

1. **Apple Search Ads**, when Apple confirms the install came from an ad.
2. **Google Play referrer**: a smart link if the referrer names one, otherwise a Play referrer campaign if it has campaign parameters.
3. **The URL the app was first opened with**: a smart link if it carries the link's parameters, otherwise a campaign link if it has `aky_c` or `utm_*` parameters.
4. **Organic.**

A Play referrer for a normal store install (`utm_source=google-play&utm_medium=organic`, or no campaign and no source) counts as organic, not as a Play referrer campaign.

***

## Apple Search Ads

On iOS, the native module reads the AdServices attribution token on the first launch. No IDFA and no App Tracking Transparency prompt are involved.

**1. On the device**

By default (`resolveAdServicesOnDevice: true`) the SDK sends the token to Apple's AdServices API itself and reads the campaign, ad group and keyword ids. Apple can take a few seconds to have the record ready, so the SDK tries up to three times, a few seconds apart.

**2. On the server**

The SDK sends the token together with whatever Apple answered. If Apple had not answered yet, the server exchanges the token itself, right away and then on a schedule, for up to 24 hours after the install. Apple's tokens expire after 24 hours; after that the install stays with the source it already has.

When the server resolves the token later, Apple Search Ads replaces any other source the install had.

Apple Search Ads installs carry the campaign id, ad group id and keyword id. Only these installs have a value for the **keyword** dimension. The campaign of an Apple Search Ads install is its Apple campaign id, which is what [ROAS](https://docs.appeeky.com/docs/analytics-roas.md) joins on.

***

## Campaign Links

Any link that opens your app can carry a campaign. On the first launch, the SDK reads the opening URL and keeps these parameters:

| Parameter | Meaning |
| - | - |
| `aky_c` | Campaign name (short form) |
| `utm_source`, `utm_medium`, `utm_campaign`, `utm_term`, `utm_content` | Standard campaign parameters |

The campaign of the install is `aky_c`, else `utm_campaign`, else `utm_source`.

```
myapp://onboarding?aky_c=spring-launch
https://example.com/open?utm_source=newsletter&utm_campaign=october
```

> [!NOTE]
>
> A campaign link only counts when it opens the app on its **first** launch. A link that opens the app later does not change the install's source.

***

## Google Play Referrer

On Android, the native module reads the Play Install Referrer on the first launch. If the Play Store URL you shared had a `referrer` with `utm_*` parameters, the install gets source `play_referrer` with `utm_campaign` (or `utm_source`) as its campaign.

```
https://play.google.com/store/apps/details?id=com.example.app&referrer=utm_source%3Dnewsletter%26utm_campaign%3Doctober
```

[Smart links](https://docs.appeeky.com/docs/analytics-smart-links.md) build this referrer for you.

***

## Without the Native Module

In Expo Go, or in a plain React Native app without Expo Modules, the SDK cannot read the AdServices token or the Play referrer. Campaign links still work. You can pass both values yourself:

```ts theme={"theme":{"light":"github-light","dark":"github-dark"}}
Appeeky.init({
  key: "apk_pub_...",
  getAdServicesToken: Platform.OS === "ios" ? () => AdServices.getAttributionToken() : undefined,
  getInstallReferrer: Platform.OS === "android" ? getPlayInstallReferrer : undefined,
});
```

Each callback has 3 seconds to answer.

***

## Limits

* Attribution is collected **once**, on the first launch of an install. It is not updated by later opens.
* Paid campaigns on other ad networks are not attributed per install. Their results arrive as aggregated [SKAdNetwork postbacks](https://docs.appeeky.com/docs/analytics-skadnetwork.md).
* iOS has no deferred deep link from smart links. See [Smart Links](https://docs.appeeky.com/docs/analytics-smart-links.md#ios).

***

## Related Docs

* [Smart Links](https://docs.appeeky.com/docs/analytics-smart-links.md)
* [SKAdNetwork](https://docs.appeeky.com/docs/analytics-skadnetwork.md)
* [ROAS](https://docs.appeeky.com/docs/analytics-roas.md)
* [Metrics](https://docs.appeeky.com/docs/analytics-metrics.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.