AdAttributionKit

Privacy-preserving ad attribution for iOS 17.4+. AdAttributionKit enables ad networks and advertisers to measure app installs and re-engagements across the App Store and alternative marketplaces without disclosing user-level identity.

Three distinct roles participate in attribution:

• Ad Network: Signs ad impressions with JWS and receives cryptographically validated postbacks.
• Publisher App: Hosts and renders ads using UIEventAttributionView or StoreKit overlays.
• Advertised App: Registers conversions, updates conversion values, and receives copy postbacks.

Contents

• Privacy Model & Attribution Arbitration
• Publisher App Configuration
• Advertiser App Setup
• Impressions & StoreKit Overlays
• Conversion Values & Postbacks
• Common Mistakes
• Review Checklist
• References

Privacy Model & Attribution Arbitration

• Crowd Anonymity Tiers (0-3): The system restricts postback granularity based on crowd volume. Low crowd tiers return coarse conversions and shorter source IDs; Tier 3 returns full 4-digit source IDs and fine values.
• Delayed Postbacks: Postbacks are queued and dispatched randomly (24-48h for the first conversion window; 24-144h for second/third windows).
• Interoperability & Arbitration: AdAttributionKit and SKAdNetwork impressions are evaluated together. Exactly one impression wins: click-through beats view-through; within the same interaction type, the most recent impression wins.

Publisher App Configuration

Declare supported ad networks in Info.plist with lowercase identifiers:

<key>AdNetworkIdentifiers</key>
<array>
    <string>example123.adattributionkit</string>
    <string>partner456.skadnetwork</string>
</array>

For custom click-through ads, overlay a UIEventAttributionView directly above the tappable surface:

import UIKit

let attributionView = UIEventAttributionView()
attributionView.frame = adContainer.bounds
attributionView.isUserInteractionEnabled = true
adContainer.addSubview(attributionView)

Advertiser App Setup

Opt in to receive copies of winning conversion and re-engagement postbacks at your HTTPS endpoint:

<key>AdAttributionKit</key>
<dict>
    <key>AttributionCopyEndpoint</key>
    <string>https://example.com</string>
    <key>OptInForReengagementPostbackCopies</key>
    <true/>
</dict>

The system sends postbacks to https://example.com/.well-known/appattribution/report-attribution/.

Impressions & StoreKit Overlays

Register signed JWS impressions provided by the ad network:

import AdAttributionKit
import StoreKit

// Check device availability
guard AppImpression.isSupported else { return }

let impression = try await AppImpression(compactJWS: signedJWS)

// Option A: Custom view-through or click-through
try await impression.handleView()
try await impression.handleTap() // Must be called within 15 minutes of creation

// Option B: StoreKit overlay automatic tracking
let config = SKOverlay.AppConfiguration(appIdentifier: "123456789", position: .bottom)
config.appImpression = impression

Conversion Values & Postbacks

Update conversion values on launch and key milestone completions:

// Initial window start
try await Postback.updateConversionValue(0, lockPostback: false)

// Milestone update with coarse tier and early lock
try await Postback.updateConversionValue(
    42,
    coarseConversionValue: .high,
    lockPostback: true // Finalizes window early to accelerate postback receipt
)

Common Mistakes

• Uppercase AdNetworkIdentifiers: Ad network IDs in Info.plist must be strictly lowercase.
• Missing UIEventAttributionView: Custom click-through ads without an overlying UIEventAttributionView fail attribution registration.
• Delayed initial conversion call: Failing to call Postback.updateConversionValue on initial launch prevents the conversion window from starting.
• Missing 15-minute click window: impression.handleTap() must be invoked within 15 minutes of AppImpression initialization.
• Treating eligibility and conversion windows as identical: Attribution eligibility windows (interaction to install) are separate from postback conversion windows (install to measurement).

Review Checklist

• All ad network identifiers in Info.plist are lowercase
• UIEventAttributionView covers the interactive ad area without touch interception
• AttributionCopyEndpoint configured with valid HTTPS and .well-known route
• Initial conversion value registered promptly on app first launch
• High-value actions lock postback early when subsequent conversions are not expected
• Cryptographic JWS signatures verified before counting conversions server-side

References

• Postback verification, server handling, testing, and SKAdNetwork migration: references/adattributionkit-patterns.md
• Apple: AdAttributionKit
• Apple: Presenting ads in your app
• Apple: Receiving ad attributions and postbacks
• Apple: Verifying a postback
• Apple: SKAdNetwork interoperability