苹果 Apple Search Ads 全新归因方案

☞点击下载：ASA 上线开发者必看

一、概要

苹果于 2021 年 1 月发布了一个全新的 Apple Search Ads 归因方案。此方案不依赖 IDFA，不受用户隐私政策的约束，在 iOS 14.3 及更高版本的设备上 100% 可归因。

以下是该方案的要点和广告主应对措施：

• 此归因方案仅适用 Apple Search Ads 广告；仅支持 iOS 14.3 及更高版本；14.3 之前的版本，需使用 iAd Framework
• 此方案将极大提高 ASA 广告安装的激活率(1)，安装到激活的差距逐渐(2)降至极低
• 此方案涉及前后端的系统开发，需自己归因的开发者应尽早制定计划、安排实施
• 使用 MMP 服务的开发者，与您的服务提供商沟通(3)，了解其SDK对此方案的支持进度
• 无论开发者自己实施还是采用 MMP，均需要发布新的app版本
• 针对 iOS 14 及更高版本的设备，LAT 的概念已失效，受众的年龄和性别定向不再排除限制跟踪的用户

注1 排除多渠道投放、特殊异常等原因

注2 预计2021年3月，iOS 14.3及更高版本的覆盖率将超过50%

注3 截至目前，AppsFlyer SDK V6.1.3 、Adjust SDK V4.25.0 及更高版本已提供支持。

二、实施说明

The Apple Ads Attribution API is a solution that combines the AdServices framework on client devices and a RESTful API for server-side communication with Apple’s attribution server. The API retrieves attribution data from app downloads and redownloads from Apple Search Ads campaigns. Measure attribution data using specific Apple Search Ads campaign metadata against the performance of Apple Search Ads campaigns.

Some developers use a server-side integration with Mobile Measurement Providers (MMPs) for enhanced reporting. Developers also have the option to hand off attribution data to a MMP or manage their attribution data themselves. The following diagram illustrates using the AdServices framework in combination with a RESTful endpoint to retrieve attribution data.

这个归因方案，包含两部分：客户端的 AdServices 框架，和从苹果Search Ads归因服务器获取归因数据的 RESTful API。

下图说明了结合使用 AdServices 框架和 RESTful API 来完成归因。

• In step 1, the AdServices framework makes a call to request a token.
• In step 2, the AdServices framework generates a token. For more detail, see attributionTokenWithError:.
• In step 3, an MMP or developer uses the token in a RESTful API request to retrieve an attribution record from Apple’s attribution server. For more detail, see Attribution Payload.
• In step 4, the attribution record that is returned has key value pairs that correspond to your campaigns in the Apple Search Ads Campaign Management API. For more detail, see Attribution Payload Descriptions.

• 第 1 步，AdServices 框架发起调用请求生成token；
• 第 2 步，AdServices 框架生成 token。
• 第 3 步，MMP 或开发人员使用 token 发起 RESTful API 请求，苹果的归因服务器返回归因数据。
• 第 4 步，返回的归因数据为字段格式的键值对，这些键值对数据与 Apple Search Ads 广告系列管理API中的广告系列相对应。

1、Request Token 获取 token

+ (NSString *)attributionTokenWithError:(NSError * _Nullable *)error;

The token that the framework returns is a string and has a 24-hour TTL.

AdServices 框架返回的 token 为字符串类型，并且只有 24 小时有效期。

AAAttributionErrorCode 归因错误枚举值

xxxxxxxxxx
typedef enum AAAttributionErrorCode : NSInteger {
  AAAttributionErrorCodeNetworkError = 1,
  AAAttributionErrorCodeInternalError = 2,
  AAAttributionErrorCodePlatformNotSupported = 3
} AAAttributionErrorCode;

AAAttributionErrorCodeInternalError

A token was not provided because an internal error occurred.

没有返回 token，发生了内部错误。

AAAttributionErrorCodeNetworkError

A token was not provided because a network is not available.

没有返回 token，网络不可用。

AAAttributionErrorCodePlatformNotSupported

A token was not provided because the OS platform is unsupported.

没有返回 token，操作系统平台不支持。

2、Request attribution 获取归因数据

You can provide the token to a MMP or app developers can use the token to make a POST API call within the 24-hour TTL window to fetch attribution records. Use a single token in the request body:

您可以将 token 提供给 MMP，或者使用该 token 在 24 小时内进行 POST API 调用，以获取归因数据。在请求正文中带上 token：

​x
POST https://api-adservices.apple.com/api/v1/
​
yourtokenyourtokenyourtokenyourtokenyourtokenyourtokenyourtokenyourtokenyourtokenyourtokenyourtokenyourtoken

Response Codes 返回状态码

3、代码示例

1）获取token（Objective-C）

xxxxxxxxxx
#import <AdServices/AdServices.h>
​
- (void) methodToGetToken {
    if (@available(iOS 14.3, *)) {
        NSError *error;
        NSString *token = [AAAttribution attributionTokenWithError:&error];
        if (token != nil) {
          // 发送POST请求归因数据
        }
    } else {
        // Fallback on earlier versions
    }
}

2）获取归因数据（Objective-C）

xxxxxxxxxx
- (void) attributionWithToken:(NSString *)token {
    NSURLSessionConfiguration *configuration = [NSURLSessionConfiguration defaultSessionConfiguration];
    NSURLSession *session = [NSURLSession sessionWithConfiguration:configuration delegate:self delegateQueue:nil];
    NSURL *url = [NSURL URLWithString:@"https://api-adservices.apple.com/api/v1/"];
    NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:url
                                                           cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                       timeoutInterval:60.0];
    [request addValue:@"application/json" forHTTPHeaderField:@"Content-Type"];
    [request setHTTPMethod:@"POST"];
    NSData* postData = [token dataUsingEncoding:NSUTF8StringEncoding];
    [request setHTTPBody:postData];
    NSURLSessionDataTask *postDataTask = [session dataTaskWithRequest:request completionHandler:^(NSData *data, NSURLResponse *response, NSError *error) {
        NSError *resError;
        NSMutableDictionary *resDic = [NSJSONSerialization JSONObjectWithData:data options:kNilOptions error:&resError];
    }];
    [postDataTask resume];
}

3）获取归因数据（cURL）

xxxxxxxxxx
curl -vvv https://api-adservices.apple.com/api/v1/ \
-H 'Content-Type:application/json'\
-d 'yourtokenyourtokenyourtokenyourtoken'

4）返回归因数据包示例

xxxxxxxxxx
{
  "orgId":1234567890,
  "campaignId":1234567890,
  "conversionType":"Download",
  "clickDate":"2021-01-11T06:41Z",
  "adGroupId":1234567890,
  "countryOrRegion":"US",
  "keywordId":12323222,
  "creativeSetId":1234567890,
  "attribution":true
}

4、Attribution Payload 归因信息

The API returns two types of attribution records: a standard response and a detailed response. The iOS 14 device level setting Allow Apps to Request to Track (AAtRtT) and details that are available from the attribution payload determine the type of response that the attribution server returns. The AAtRtT setting allows users to opt in or out of allowing apps to request user consent to access app-related data that can be used for both attribution and tracking the user or the device. The following table shows the combination of tracking interactions and expected attribution payload response.

API 返回两种类型的归因数据：标准数据包和详细数据包。 iOS 14 设备级别的设置以及单个 app 的跟踪同意状态，决定了归因数据的类型。下表显示了 6 种组合。

The attribution record is a data dictionary with key value pairs that correspond to your Apple Search Ads campaigns and app downloads on Apple News and Stocks, made from devices running iOS 14 and above.

归因记录是一个包含键值对的数据字典，这些数据与来自 Apple Search Ads（包括 App Store、Apple News 以及 Stocks）的设备（由运行 iOS 14 及更高版本的设备）安装行为相对应。

Detailed Payload（详细数据包）

xxxxxxxxxx
// Detailed Payload（详细数据包）
{
  "attribution": true,
  "orgId": 55555,
  "campaignId": 12345678,
  "conversionType": "Download",
  "clickDate": "2020-10-01T17:17Z",
  "adGroupId": 12345678,
  "countryOrRegion": "US",
  "keywordId": 12345678,
  "creativeSetId": 12345678
}

Standard Payload（标准数据包）

xxxxxxxxxx
{
  "attribution": true,
  "orgId": 55555,
  "campaignId": 12345678,
  "conversionType": "Download",
  "adGroupId": 12345678,
  "countryOrRegion": "US",
  "keywordId": 12345678,
  "creativeSetId": 12345678
}

归因数据包字段说明

三、归因数据的存储和使用

此部分内容仅考虑ASA单一渠道的广告归因，供开发者参考

1、归因数据示意和说明

结构和字段说明如下图所示，详细情况需参考官方API文档。

上图中的 convertionType，官方文档有两处不一致。当前API实际测试，取值为 Download 和 Redownload。

已实施过iAd归因方案的开发者，需注意新旧方案的兼容性，下图为两个方案的数据字段的对比：

2、存储示例

假设我们使用一个关系型数据库表来存储的激活设备明细，如下示意

attribution 1表示true，conversion_type 的值为 d 表示Download, r 表示Redownload

3、使用示例

按关键词粒度统计每日激活设备数

输出结果

四、参考资料

• AdServices Framework - Apple Developer Documentation
• iAd Framework - Apple Developer Documentation
• AppsFlyer SDK V6.1.3 + 已支持
• Adjust SDK V4.25.0 + 已支持