drewster99/ncc-open-apple-search-ads-install-attribution
Install attribution for apps downloaded through Apple Search Ads (Apple Ads), using Apple's
Requirements
- iOS 17+ or macOS 14+
- Swift 6.1+
Installation
dependencies: [
.package(url: "https://github.com/drewster99/NCC-Open-Apple-Search-Ads-Install-Attribution.git", from: "1.2.0"),
],
targets: [
.target(name: "MyApp", dependencies: [
.product(name: "NCCOpenAppleSearchAdsInstallAttribution", package: "NCC-Open-Apple-Search-Ads-Install-Attribution"),
]),
]Usage
Create one instance at app launch and keep it alive. Work starts as soon as it's created.
import SwiftUI
import NCCOpenAppleSearchAdsInstallAttribution
@main
struct MyApp: App {
@StateObject private var adAttribution = NCCOpenAppleSearchAdsInstallAttribution(
{ payload in
// Every launch once a payload is known, including one loaded from a previous launch
Analytics.setUserProperty(payload.conversionType, forName: "ASAConversionType")
},
onNewAttributionPayloadReceived: { payload in
// Only when a payload arrives that differs from the saved one
Analytics.logEvent("asa_attribution_received", parameters: payload.asAnalyticsDictionary)
}
)
var body: some Scene {
WindowGroup { ContentView() }
}
}adAttribution.attributionPayload and adAttribution.error are @Published. error is set when the token or the attribution record can't be fetched, including AttributionPayloadFetchError.mockDataReceived when Apple returns its developer-mode test payload.
The payload
| Property | Notes | |---|---| | attribution | true for a tap within 30 days or a view within 24 hours before download | | orgId, campaignId, adGroupId | Correlate with the Apple Ads Campaign Management API | | keywordId | Absent for search match | | adId | Absent when no custom product page is associated | | conversionType | Download, Redownload or PreOrder | | claimType | .click (tap-through) or .impression (view-through) | | clickDate / impressionDate | Present for tap-through / view-through respectively | | countryOrRegion | The campaign's country or region | | supplyPlacement | Where the ad ran, e.g. .appStoreSearchResults, .appStoreTodayTab |
claimType and supplyPlacement keep values Apple adds later in rawValue rather than failing to decode.
asAnalyticsDictionary returns the payload as ASA-prefixed keys (ASAOrgId, ASACampaignID, ASAConversionType, ASAAdGroupID, ASACountryOrRegion, and when present ASAKeywordID, ASAAdID, ASAClickDate, ASAImpressionDate, ASAClaimType, ASASupplyPlacement).
Testing
With developer mode on, Apple's API returns a test payload whose identifiers are 1234567890. It is detected (isMockData), not saved, and reported through error.
License
Apache 2.0. See LICENSE.
Package Metadata
Repository: drewster99/ncc-open-apple-search-ads-install-attribution
Default branch: main
README: README.md