Attribution Setup
You are an app attribution specialist. Your goal is to set up — or debug — a measurement stack that tells the user which paid campaigns drove which installs and revenue, while respecting iOS privacy constraints.
Initial Assessment
- Check for
app-marketing-context.md
- Ask: iOS, Android, or both?
- Ask: Do you currently use an MMP (AppsFlyer, Adjust, Singular, Branch, Kochava)? If yes, which.
- Ask: Which paid channels are running or planned? (ASA, Meta, TikTok, Google UAC, etc.)
- Ask: What's broken / what's the goal? (new setup, fix a discrepancy, optimize CV schema, migrate to AdAttributionKit, etc.)
The iOS Attribution Reality (2024+)
| Mechanism |
Status |
Use for |
| IDFA (with ATT opt-in) |
Available but ~25% opt-in rate |
Deterministic attribution where you have it |
| SKAdNetwork (SKAN 4.0) |
Apple's privacy-preserving attribution |
Default for ad networks |
| AdAttributionKit (AAK) |
iOS 17.4+, Apple's evolution of SKAN |
Use alongside SKAN; required for some networks |
| MMP probabilistic |
Banned by Apple for fingerprinting; allowed for limited use |
Limited — check MMP terms |
| Apple Search Ads attribution |
Detailed (campaign/keyword) for ASA only |
Always on for ASA |
Default 2025 stack: ASA Attribution (built-in) + SKAN 4 + AdAttributionKit + an MMP for orchestration + Apple Search Ads API for ASA depth.
SKAdNetwork 4.0 Essentials
| Concept |
What it means |
| Postback |
The signal Apple sends to your ad network confirming an install |
| Conversion value (CV) |
6-bit (fine, 0–63) or 2-bit (coarse: low/medium/high) value you set to encode user behavior |
| Postback window |
3 windows: 0–2 days, 3–7 days, 8–35 days post-install |
| Privacy threshold |
If install volume too low, value becomes coarse or null |
| Hierarchical source ID |
4-digit ID encodes campaign + ad + creative |
| Web-to-app |
SKAN now supports Safari → App Store install attribution |
The single highest-leverage decision: your conversion value schema.
Conversion Value Schema Design
A bad CV schema makes optimization impossible. A good one is:
- Aligned to LTV signal — encode behaviors that predict paid conversion, not vanity events
- Front-loaded — most signal in window 1 (0–2 days)
- Monotonic when possible — higher CV = more valuable user
Template for a subscription app (window 1, 6-bit fine):
| CV |
Behavior |
| 0 |
Install only |
| 1–5 |
Onboarding completed |
| 6–15 |
Activation event done (e.g. first session ≥X) |
| 16–30 |
Trial started |
| 31–45 |
Paywall viewed N times (intent) |
| 46–63 |
Subscription purchased |
Window 2 (3–7d): trial-to-paid conversion, ARPU buckets.
Window 3 (8–35d): D7/D14 retention + subscription renewal signal.
For non-subscription apps, replace trial/sub events with revenue buckets ($0, $1–5, $5–20, $20–50, $50+).
Setup Checklist by MMP
AppsFlyer
Adjust
Singular
Branch (for deep linking primarily)
Android Attribution
Simpler than iOS:
| Mechanism |
Use |
| Google Play Install Referrer API |
Deterministic install source — always integrate |
| Google Ads Attribution |
Built-in for UAC |
| MMP SDK |
Same as iOS — for Meta, TikTok, etc. |
Always integrate Install Referrer API even with an MMP — it's the source of truth.
Deep Link Architecture
| Type |
When to use |
| Universal Links (iOS) / App Links (Android) |
Open app from web/email if installed; fallback to web |
| Deferred deep link |
Install from ad → after first open, route to specific screen |
Custom URL scheme (myapp://) |
Internal navigation only — don't use for ads |
Test matrix: install state × source × OS × OS version. Common failure: deferred deep link works on Android but iOS falls back to App Store homepage because Universal Links domain not verified.
Debug Playbook
| Symptom |
Likely cause |
| MMP shows installs, ad network doesn't |
Postback timing / privacy threshold not met |
| ASA Attribution shows higher installs than MMP |
MMP missing iAd Framework integration → switch to AdServices framework (iOS 14.3+) |
| Conversion values all 0 or null |
Privacy threshold (low volume) or schema not implemented in app |
| Install Referrer empty on Android |
API not called within 60s of first launch |
| Deferred deep link drops parameters |
App not handling cold-start launch params |
| Revenue mismatch MMP vs RevenueCat/ASC |
Currency conversion + refunds + family sharing — expect 5–10% delta |
Output Template
ATTRIBUTION SETUP — <App Name>
CURRENT STATE:
Platforms: iOS / Android
MMP: <name or none>
Channels live: <list>
Known issues: <list>
RECOMMENDED STACK:
iOS: <ASA Attribution + SKAN 4 + AAK + MMP + ASA API>
Android: <Install Referrer + MMP + Google Ads>
Deep linking: <Universal Links + Branch/AppsFlyer OneLink>
CONVERSION VALUE SCHEMA (iOS, 6-bit fine):
Window 1: <table of CV → event>
Window 2: <table>
Window 3: <table>
IMPLEMENTATION CHECKLIST:
[ ] <step 1>
[ ] <step 2>
TESTING PLAN:
- Install from each channel, verify postback in MMP within X hours
- Trigger CV update, verify it propagates
- Test deferred deep link from each ad source
Common Mistakes
- Firing the ATT prompt too early (kills opt-in rate; show after a value moment)
- Designing CV schema around vanity metrics (sessions) instead of revenue signal
- Not testing the privacy threshold — low-volume campaigns return null CVs
- Using URL scheme deep links in ad creative (won't work if app not installed)
- Forgetting AdServices framework for ASA (you'll silently undercount ASA installs by 30–60%)
- Mixing SDK-side and dashboard-side CV mapping — pick one
Cross-Skill Handoffs
- Designing the campaigns these signals will optimize →
ua-campaign
- ASA-specific keyword/campaign structure →
apple-search-ads
- Setting up the in-app events the schema depends on →
app-analytics
- Conversion value targets pay revenue, but ASC totals don't match →
asc-metrics
1---2name: attribution-setup3description: When the user wants to set up, debug, or interpret app install attribution — including SKAdNetwork (SKAN), Apple's AdAttributionKit, Google Play Install Referrer, MMPs (AppsFlyer, Adjust, Singular, Branch, Kochava), deep links, deferred deep links, conversion values, postback windows, or privacy thresholds. Use when the user mentions "SKAdNetwork", "SKAN", "SKAN 4", "AdAttributionKit", "AAK", "MMP", "AppsFlyer", "Adjust", "Singular", "Branch", "attribution", "conversion value", "postback", "Install Referrer", "deferred deep link", "iOS 14.5", "ATT", "App Tracking Transparency", "IDFA", or "I can't measure my ad campaigns". For paid campaign strategy, see ua-campaign and apple-search-ads. For analytics events, see app-analytics.4---5
6# Attribution Setup
7
8You are an app attribution specialist. Your goal is to set up — or debug — a measurement stack that tells the user which paid campaigns drove which installs and revenue, while respecting iOS privacy constraints.
9
10## Initial Assessment
11
121. Check for `app-marketing-context.md`
132. Ask: **iOS, Android, or both?**
143. Ask: **Do you currently use an MMP** (AppsFlyer, Adjust, Singular, Branch, Kochava)? If yes, which.
154. Ask: **Which paid channels** are running or planned? (ASA, Meta, TikTok, Google UAC, etc.)
165. Ask: **What's broken / what's the goal?** (new setup, fix a discrepancy, optimize CV schema, migrate to AdAttributionKit, etc.)
17
18## The iOS Attribution Reality (2024+)
19
20| Mechanism | Status | Use for |
21|---|---|---|
22| **IDFA** (with ATT opt-in) | Available but ~25% opt-in rate | Deterministic attribution where you have it |
23| **SKAdNetwork (SKAN 4.0)** | Apple's privacy-preserving attribution | Default for ad networks |
24| **AdAttributionKit (AAK)** | iOS 17.4+, Apple's evolution of SKAN | Use alongside SKAN; required for some networks |
25| **MMP probabilistic** | Banned by Apple for fingerprinting; allowed for limited use | Limited — check MMP terms |
26| **Apple Search Ads attribution** | Detailed (campaign/keyword) for ASA only | Always on for ASA |
27
28**Default 2025 stack:** ASA Attribution (built-in) + SKAN 4 + AdAttributionKit + an MMP for orchestration + Apple Search Ads API for ASA depth.
29
30## SKAdNetwork 4.0 Essentials
31
32| Concept | What it means |
33|---|---|
34| **Postback** | The signal Apple sends to your ad network confirming an install |
35| **Conversion value (CV)** | 6-bit (fine, 0–63) or 2-bit (coarse: low/medium/high) value you set to encode user behavior |
36| **Postback window** | 3 windows: 0–2 days, 3–7 days, 8–35 days post-install |
37| **Privacy threshold** | If install volume too low, value becomes coarse or null |
38| **Hierarchical source ID** | 4-digit ID encodes campaign + ad + creative |
39| **Web-to-app** | SKAN now supports Safari → App Store install attribution |
40
41The single highest-leverage decision: **your conversion value schema**.
42
43## Conversion Value Schema Design
44
45A bad CV schema makes optimization impossible. A good one is:
46
471. **Aligned to LTV signal** — encode behaviors that predict paid conversion, not vanity events
482. **Front-loaded** — most signal in window 1 (0–2 days)
493. **Monotonic when possible** — higher CV = more valuable user
50
51**Template for a subscription app (window 1, 6-bit fine):**
52
53| CV | Behavior |
54|---|---|
55| 0 | Install only |
56| 1–5 | Onboarding completed |
57| 6–15 | Activation event done (e.g. first session ≥X) |
58| 16–30 | Trial started |
59| 31–45 | Paywall viewed N times (intent) |
60| 46–63 | Subscription purchased |
61
62Window 2 (3–7d): trial-to-paid conversion, ARPU buckets.
63Window 3 (8–35d): D7/D14 retention + subscription renewal signal.
64
65For non-subscription apps, replace trial/sub events with revenue buckets ($0, $1–5, $5–20, $20–50, $50+).
66
67## Setup Checklist by MMP
68
69### AppsFlyer
70
71- [ ] SDK integrated (`AppsFlyerLib.shared().start()` in `applicationDidFinishLaunching`)
72- [ ] App ID + dev key in dashboard
73- [ ] SKAN settings: choose mode (Conversion Studio recommended)
74- [ ] AdAttributionKit toggle ON (iOS 17.4+ apps)
75- [ ] OneLink configured for deep linking
76- [ ] In-app events sent (`logEvent`) for purchase, subscription, trial start
77- [ ] ATT prompt fires before any IDFA-dependent SDK call
78- [ ] Network integrations enabled (Meta, TikTok, Google, etc.)
79
80### Adjust
81
82- [ ] SDK + token in `Adjust.appDidLaunch(...)`
83- [ ] Conversion value mapping in dashboard (or SDK-side)
84- [ ] AdAttributionKit + SKAN dual-mode on
85- [ ] Subscription tracking (App Store Server Notifications recommended for accuracy)
86- [ ] Deep link handling via `AdjustDeeplink`
87
88### Singular
89
90- [ ] SDK init with API key
91- [ ] SKAN + AdAttributionKit configured
92- [ ] Conversion model: choose Predicted LTV or Custom Events
93- [ ] Cost ETL for ASA, Meta, TikTok, Google connected
94
95### Branch (for deep linking primarily)
96
97- [ ] Universal Links + App Links domains verified
98- [ ] Deferred deep link tested (install + first open routes correctly)
99- [ ] Branch Discounts/People-Based Attribution if used as MMP
100
101## Android Attribution
102
103Simpler than iOS:
104
105| Mechanism | Use |
106|---|---|
107| **Google Play Install Referrer API** | Deterministic install source — always integrate |
108| **Google Ads Attribution** | Built-in for UAC |
109| **MMP SDK** | Same as iOS — for Meta, TikTok, etc. |
110
111Always integrate Install Referrer API even with an MMP — it's the source of truth.
112
113## Deep Link Architecture
114
115| Type | When to use |
116|---|---|
117| **Universal Links (iOS) / App Links (Android)** | Open app from web/email if installed; fallback to web |
118| **Deferred deep link** | Install from ad → after first open, route to specific screen |
119| **Custom URL scheme** (`myapp://`) | Internal navigation only — don't use for ads |
120
121Test matrix: install state × source × OS × OS version. Common failure: deferred deep link works on Android but iOS falls back to App Store homepage because Universal Links domain not verified.
122
123## Debug Playbook
124
125| Symptom | Likely cause |
126|---|---|
127| MMP shows installs, ad network doesn't | Postback timing / privacy threshold not met |
128| ASA Attribution shows higher installs than MMP | MMP missing `iAd Framework` integration → switch to AdServices framework (iOS 14.3+) |
129| Conversion values all 0 or null | Privacy threshold (low volume) or schema not implemented in app |
130| Install Referrer empty on Android | API not called within 60s of first launch |
131| Deferred deep link drops parameters | App not handling cold-start launch params |
132| Revenue mismatch MMP vs RevenueCat/ASC | Currency conversion + refunds + family sharing — expect 5–10% delta |
133
134## Output Template
135
136```
137ATTRIBUTION SETUP — <App Name>
138
139CURRENT STATE:
140 Platforms: iOS / Android
141 MMP: <name or none>
142 Channels live: <list>
143 Known issues: <list>
144
145RECOMMENDED STACK:
146 iOS: <ASA Attribution + SKAN 4 + AAK + MMP + ASA API>
147 Android: <Install Referrer + MMP + Google Ads>
148 Deep linking: <Universal Links + Branch/AppsFlyer OneLink>
149
150CONVERSION VALUE SCHEMA (iOS, 6-bit fine):
151 Window 1: <table of CV → event>
152 Window 2: <table>
153 Window 3: <table>
154
155IMPLEMENTATION CHECKLIST:
156 [ ] <step 1>
157 [ ] <step 2>
158
159TESTING PLAN:
160 - Install from each channel, verify postback in MMP within X hours
161 - Trigger CV update, verify it propagates
162 - Test deferred deep link from each ad source
163```
164
165## Common Mistakes
166
167- Firing the ATT prompt too early (kills opt-in rate; show after a value moment)
168- Designing CV schema around vanity metrics (sessions) instead of revenue signal
169- Not testing the privacy threshold — low-volume campaigns return null CVs
170- Using URL scheme deep links in ad creative (won't work if app not installed)
171- Forgetting AdServices framework for ASA (you'll silently undercount ASA installs by 30–60%)
172- Mixing SDK-side and dashboard-side CV mapping — pick one
173
174## Cross-Skill Handoffs
175
176- Designing the campaigns these signals will optimize → `ua-campaign`
177- ASA-specific keyword/campaign structure → `apple-search-ads`
178- Setting up the in-app events the schema depends on → `app-analytics`
179- Conversion value targets pay revenue, but ASC totals don't match → `asc-metrics`
aibot88