概述
Apple Search Ads Attribution API 可以让 iOS 开发者能够追踪和归因来自于 Search Ads 系列的应用下载。借助于 Search Ads Attribution API，开发者可以准确的衡量新用户的价值及其广告活动的有效性。
主要优点
- 轻松衡量搜索广告系列的效果。
- 随时为您的应用启用归因功能，并开始跟踪来自现有搜索广告系列中的应用下载。
- 可以获取点击广告并在30天内下载应用的广告相关信息。例如：广告系列名称和ID，广告组名称和ID，关键词以及点击和下载日期。
- 由于数据作为NSDictionary对象返回，因此将整个数据对象传递给服务器，即使搜索广告返回的数据结构发生更改，你的应用也不用进行更新。
安装启用
要为您的应用启用搜索广告归因功能，请按以下步骤操作：
- iAd framework：在Xcode工程将iAd framework添加到您的应用程序中。
- iAd 相关头文件：在包含您的归因代码的文件中导入iAd 相关头文件。
- Search Ads归因：在您的应用中，检查搜索广告归因。
- 错误处理：处理错误并在需要时重新检查。
- “Phone Home”：“Phone home”并将下载的数据发送到您的服务器。
要求
要为您的应用启用搜索广告归因功能，请按以下步骤操作：
- 此功能适用于所有支持搜索广告的店面（？）；
- 对于运行iOS 10.0 或更高版本的用户，应用程序下载数据至少在过去 12 个月内可用；
- 要跟踪归因，必须使用适当的头文件编译应用程序（适用于 iOS 10.0 或更高版本的 Xcode 中）。
不支持场景
搜索广告归因不支持场景如下：
- 通过 iTunes App Bundle 下载的应用程序；
- App 下载来源于其他设备登录的 itunes 账号的自动下载；
- App 下载来源于 iOS 家庭共享。
iAd framework
iAd框架与Xcode捆绑在一起。按照以下步骤将iAd框架添加到应用程序的Xcode项目文件中：
- 定位到target view，然后选择General。
- 向下滚动到“链接框架和库”部分，然后单击加号（+）图标。
- 在下拉菜单中，搜索iAd。
- 选择iAd.framework并单击“Add”按钮。
iAd 头文件
将iAd头文件导入您的应用，通常导入到包含您的归因代码的文件中。此头文件取决于您在Xcode中编译应用程序的iOS版本。搜索广告归因需要iOS 10.0或更高版本。
Search Ads attribution
在您的应用中，检查一次搜索广告的归因，例如首次打开或注册完成时。将数据存储在本地，这样您就不需要再次调用。
1 | `#import /*! * @method requestAttributionDetailsWithBlock: * * @param completionHandler * A block which will be called with details related to the attribution status of the app. * The attributionDetails dictionary will contain click and download dates * as well as other specific campaign related information provided by Search Ads. If the attributionDetails * dictionary is nil, an NSError is passed with an ADClientError enum. * * The handler will be called on an arbitrary queue. * * @discussion * Provides a way for an app to determine when an ad was shown to the user * which resulted in the user’s download of the app. */ - (void)requestAttributionDetailsWithBlock:(void (^)(NSDictionary *attributionDetails, NSError *error)) completionHandler NS_AVAILABLE_IOS(9_0);` |
错误处理
如果需要，处理您收到的任何错误并重新轮询数据。使用ADClientErrorDomain捕获返回的错误。
| 错误 | 描述 |
|---|---|
| ADClientErrorUnknown | 请等待几秒钟再试一次。成功检索归因数据后，您无需再次轮询数据;您检索到的值不会改变。 |
ADClientErrorLimitAdTracking |
表示用户已在其iOS设备上启用了限制广告跟踪功能。没有关于此用户的广告点击和转化的数据。 |
ADClientErrorMissingData |
下载的应用程序在执行归因检查时收到的数据不完整 |
ADClientErrorCorruptResponse |
从归因服务器接收到的数据已损坏 |
“Phone Home”
将下载的数据发送到您的服务器。当您的应用程序获取到NSDictionary对象时（在下面的示例中此对象为attributionDetails），您可以使用您想要的任何用户注册数据并使用您选择的任何方法将数据上传到您的服务器。
1 | `/*! * @const ADClientErrorDomain * * @discussion * Error domain for NSErrors passed to the completionHandler as a * result of calling: * * • -[[ADClient SharedClient] requestAttributionDetailsWithBlock] * */ extern NSString * const ADClientErrorDomain; /*! * @enum ADClientError * * @const ADClientErrorUnknown * General errors that aren’t covered by one of the more specific error reasons. * This is generally related to connectivity issues. * * @const ADClientErrorLimitAdTracking * The device has Limit Ad Tracking enabled. It will not be possible to receive * attribution details for app purchases made on this device. * * @discussion * Error codes for NSErrors passed to the completionHandler block * when calling the requestAttributionDetailsWithBlock method. */ typedef NS_ENUM(NSInteger, ADClientError) { ADClientErrorUnknown = 0, ADClientErrorLimitAdTracking = 1, }; // Call the iOS10 attribution API [[ADClient sharedClient] requestAttributionDetailsWithBlock: ^(NSDictionary *attributionDetails, NSError *error) { if(!error) { // Send the attributionDetails dictionary to your server for further processing. return; } if(error.code == ADClientErrorLimitAdTracking) { // The device has limit ad tracking enabled. It will not be possible to retrieve attribution details. return; } // For any other errors, you may schedule a time to call the API again, // later in this session or the next time the app is launched. }];` |
返回值
此表显示Search Ads Attribution API返回的数据字典里的键及其数据类型。
| Dictionary | Key Type | Comments |
|---|---|---|
| iad-attribution | Boolean | True/False，如果用户下载APP前30日内点击了Search Ads广告为True |
| iad-click-date | Date/time string | 用户点击广告的日期和时间 |
| iad-conversion-date | Date/time string | 用户点击广告后下载APP的日期和时间 |
| iad-purchase-date | Date/time string | 用户首次下载APP的日期和时间。当iad-conversion-type = “Redownload”时，其表示原购买日期。这个字段与广告不一定有必然联系。 |
| iad-conversion-type | String | 表明是否首次下载。”Redownload”说明用户在本设备下载/卸载过，或者用同一账户在其他设备下载过。iad-conversion-date指明了是点击广告后的最新一次下载。 |
| iad-keyword-matchtype | String | 三种关键词匹配方式之一：Broad、Exact 或者 Search Match。 |
| iad-org-name | String | Campaign所属的账户organization名称 |
| iad-campaign-id | Integer | Campaign的ID |
| iad-campaign-name | String | Campaign的名称 |
| iad-adgroup-id | Integer | Ad Group的ID |
| iad-adgroup-name | String | Ad Group的名称 |
| iad-keyword | String | 触发广告展示的关键词 |
| iad-creativeset-id | Integer | 创意的ID |
| iad-creativeset-name | String | 创意的名称 |
返回数据示例
此示例代码为在调用requestAttributionDetailsWithBlock时返回的数据结构。
1 | `{ “Version3.1” = { “iad-attribution” = true; “iad-org-name” = “Light Right”; “iad-campaign-id” = 15292426; “iad-campaign-name” = “Light Bright Launch”; “iad-purchase-date”= “2016-10-14T17:18:07Z” “iad-conversion-date” = “2016-10-14T17:18:07Z”; “iad-conversion-type” = “Download”; “iad-click-date” = “2016-10-14T17:17:00Z”; “iad-adgroup-id” = 15307675; “iad-adgroup-name” = “LightRight Launch Group”; “iad-keyword” = “light right”; “iad-keyword-matchtype” = “Broad”; “iad-creativeset-id” = “456093”; “iad-creativeset-name” = “Nature Images”; } }` |
获取归因数据标准
当用户点按“搜索广告”展示并在点击后30天内下载或重新下载相应的归因启用应用时，系统会提供归因数据。
附加标准：
- 以上所有操作必须在同一设备上进行；
- 点击必须来自搜索广告展示；
- 广告点击后30天内发生的下载或重新下载操作均来自 App Store 列表或搜索广告展示。
限制广告跟踪
已启用“限制广告跟踪”（LAT On）的用户的转化次数将显示在“搜索广告”报告中，但不会用于“搜索广告”归因。
应用程序下载 VS 应用程序打开
搜索广告会在用户下载应用时计算，而搜索广告归因API仅在应用打开时计算。
点击“延迟”
点击搜索广告展示的大多数用户会立即下载该应用。当应用程序立即打开并调用搜索广告归因 API 时，由于某些延迟，我们的系统可能尚未处理相应的广告点击。我们建议您在检索归因数据之前设置几秒钟的延迟。
活动详情
如果不是广告系列数据的所有者，想获取有关广告系列中使用的定价或定位等更多信息，请联系广告系列所有者。归因数据中的广告系列 ID 和名称可以帮助您确定哪些广告系列用于宣传您的应用。