ASA渠道使用指南

一、集成SDK

注意：此文档是针对使用了渠道统计功能中的 ASA渠道报表统计功能而提供的补充性文档
SDK版本要求：SDK>=2.5.6，CocoaPods上对应版本：>=2.5.6，工具Xcode>=12.3

1.首次集成SDK的，先按照iOS集成指南或者后台【应用集成】->【iOS集成】文档集成完毕，使用ASA渠道时，初始化代码要做调整，参考以下文档

2.代码集成
1).引入头文件

Object-C

Swift

#import <AdServices/AAAttribution.h>

import AdServices

2).调用初始化，传入相关参数
注意：之前集成了Open-APP SDK的用户，需要将之前的初始化方法替换掉，否则会导致统计失败
请在用户同意《隐私政策》后再调用初始化方法

Object-C

Swift

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions{

    [self opInit];
/*//同时使用了广告渠道和ASA渠道统计的代码示例
    if (@available(iOS 14, *)) {
        //权限申请
        [ATTrackingManager requestTrackingAuthorizationWithCompletionHandler:^(ATTrackingManagerAuthorizationStatus status) {
            [self opInit];
        }];
    }else{
        [self opInit];
    }
*/
}
- (void)opInit{
    //ASA广告归因
    NSMutableDictionary *config = [[NSMutableDictionary alloc]init];
    if (@available(iOS 14.3, *)) {
        NSError *error;
        NSString *token = [AAAttribution attributionTokenWithError:&error];
        [config setValue:token forKey:OP_ASA_Token];
    }
    /*//第三方广告平台统计代码
    NSString *idfaStr = [[[ASIdentifierManager sharedManager] advertisingIdentifier] UUIDString];
    [config setValue:idfaStr forKey:OP_Idfa_Id];
    */
    [OpenInstallSDK initWithDelegate:self adsAttribution:config];
}

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {

    opInit();
/*//同时使用了广告渠道和ASA渠道统计的代码示例
    if #available(iOS 14.0, *) {
        //权限申请
        ATTrackingManager.requestTrackingAuthorization { (status) in
            opInit();
        }
    }else{
        opInit();
    }
*/
    func opInit(){
        //ASA广告归因
        var OpConfig:[String:Any] = [String:Any]();
        if #available(iOS 14.3, *) {
            do {
                let token = try AAAttribution.attributionToken();
                OpConfig.updateValue(token, forKey: OP_ASA_Token);
            } catch {}
        }
        /*//第三方广告平台统计代码
        let idfaStr = ASIdentifierManager.shared().advertisingIdentifier.uuidString
        OpConfig.updateValue(token, forKey: OP_Idfa_Id);
        */
        OpenInstallSDK.initWith(self, adsAttribution: OpConfig);
    }
    //其它代码...
    return true
}

3).获取ASA渠道编号
同H5获取方式一样，通过方法 getInstallParmsCompleted 获取channelCode对应的值即可。

二、获取ASA广告系列ID

登录ASA官方后台苹果ASA官方后台创建广告系列并获取ID

三、创建Open-APP开发者平台ASA渠道

1.注册并登录Open-APP开发者平台创建

2.填入获取到的ASA广告系列ID

此处可创建一个编号为1234567890的ASA渠道，用于上架前的测试，看文档后面第六点

四、App Store输入关键字搜索广告并下载安装激活应用

五、查看Open-APP开发者平台ASA渠道数据统计

Open-APP开发者平台渠道报表中对应的ASA渠道安装数据成功统计即为归因成功，将继续追踪统计用户后续事件行为

六、上架前验证集成情况

1.按照集成文档完成集成操作。

2.在Open-APP控制台的【广告统计】-【广告渠道管理】-【ASA渠道】中创建一个广告系列ID为1234567890的ASA渠道。

3.在【iOS集成】-【iOS调试日志】中配置测试设备的IP并保存，然后通过Xcode或其它工具将应用安装到测试设备运行打开。

4.在【广告统计】-【ASA渠道报表】中观察渠道编号为1234567890的ASA渠道，若统计到安装量表示ASA集成正确。

或者在【iOS集成】-【iOS调试日志】中观察到以下格式类似的日志也可以判断为调试成功。

日志内容：
iOS-SDK初始化matchType:none,channelCode:1234567890,bindData:{"attribution":true,"campaignId":"1234567890","orgId":"1234567890","adGroupId":"1234567890","keywordId":"12323222","conversionType":"Download","countryOrRegion":"US"},pbFailed:false,channelSticky:false,opid:xxxxxxxxxxxxx,model:iPhone 11,system:16.5,sdk:2.7.0

注意：测试渠道1234567890是苹果返回的测试数据，可能存在延迟，可以在集成代码时，设置debug模式(OP_ASA_isDev为YES)，并且在正式版本发布时删除debug相关代码(否则会影响参数还原) ，代码如下。

Object-C

Swift

- (void)opInit{
    //...
    if (@available(iOS 14.3, *)) {
    //...
        [config setValue:token forKey:OP_ASA_Token];
        #ifdef DEBUG
            [config setValue:@(YES) forKey:OP_ASA_isDev];//该配置请不要带入正式环境中
        #else
        #endif
    }
    //初始化sdk
    [OpenInstallSDK initWithDelegate:self adsAttribution:config];
}

func opInit(){
        //...
        if #available(iOS 14.3, *) {
            do {
                let token = try AAAttribution.attributionToken();
                OpConfig.updateValue(token, forKey: OP_ASA_Token);
            #if DEBUG
                OpConfig.updateValue(NSNumber(value: true), forKey: OP_ASA_isDev);//该配置请不要带入正式环境中
            #else
            #endif
            } catch {}
        }
        OpenInstallSDK.initWith(self, adsAttribution: OpConfig);
    }

七、ASA归因返回说明

字段	数据类型	描述
adGroupId	long	广告组的标识符。使用"广告组报告"按 adGroupId 及其在 Apple Ads Platform API 中对应的广告系列来关联你的归因响应。
adId	long	表示广告对象与广告组之间分配关系的标识符。此 ID 适用于运行 iOS 15.2 及更高版本的设备。使用"广告报告"在 Apple Ads Platform API 中按 adId 关联你的归因响应。
attribution	boolean	归因值。如果用户在下载你的 App 前 30 天内点击了 Apple Ads 展示，或在 24 小时内查看了该展示，则返回 true。如果 API 找不到匹配的归因记录，则归因值为 false。注意：带有年龄和性别定向条件的广告系列会返回 false。更多详情请参阅 claimType。
campaignId	long	广告系列的唯一标识符。使用 Apple Ads Platform API 中的"广告系列报告"按 campaignId 关联你的归因响应。
claimType	string	对于浏览型归因，claimType 的值为 Impression，表示用户在查看广告后 24 小时内看到了相应 Apple Ads 广告系列中的广告，但没有点击它。对于点击型归因，claimType 的值为 Click，表示用户点击了广告。注意：点击型归因窗口为 30 天，且点击型归因优先于浏览型归因。
clickDate	日期/时间字符串	用户点击相应广告系列中广告的日期和时间。此字段仅出现在归因响应负载中。
conversionType	string	转化类型。值为 Download、Redownload 或 PreOrder。PreOrder 值同时归因于点击和浏览。如果预购是在点击后 30 天内或浏览后 1 天内完成的，则点击型归因的回溯窗口为 90 天。浏览型归因的回溯窗口为 61 天。转化类型会出现在 Apple Ads Platform API 中的 AppsCampaignMetrics 中。
countryOrRegion	string	广告系列的国家或地区。更多详情请参阅 Apple Ads Platform API 中 AppsReportingRequest 的 groupBy 部分。
impressionDate	UTC 字符串	表示相应 Apple Ads 广告系列中广告浏览发生的日期和时间。impressionDate 属性出现在浏览型归因响应负载中。
keywordId	long	关键词的标识符。使用 Apple Ads Platform API 中的"关键词报告"按 keywordId 关联你的归因响应。注意，当你启用搜索匹配时，API 不会在归因响应中返回 keywordId。更多信息请参阅"广告组端点"。
orgId	long	拥有该广告系列的组织标识符。你的 orgId 与 Apple Ads Advanced 中的账户相同。可通过调用 Apple Ads Platform API 中的 Get User ACL 获取你的 orgId。
supplyPlacement	string	广告系列的广告展示位置。

来源：https://developer.apple.com/documentation/adservices/aaattribution/attributiontoken()