SDK集成

即日起，广告监测模块将不再作为火山引擎增长分析产品售卖时的默认自带模块，如您需要额外使用广告监测模块的相关功能，请咨询您的客户经理。

前置条件：

• 集成ALink前，应保证您的app已经按照Android SDk集成指南正确集成

• 支持本功能的SDK版本为6.6.2及后续版本。最新版SDK下载

注：之前的最新文档版本为6.5.0，也可以使用，6.6.2之后去掉了再营销活动才可以触发延迟唤醒的限制

1.1深度链接

这里，我们首先需要按照之前的配置的ALink链接对应配到App内部，然后做SDK初始化集成

1.1.1 配置URI Scheme

URI Scheme技术适用于所有平台（Android和iOS)。在web中这个唯一标识就是URI(Uniform Resource Identifier)，URI既可以看成是资源地址，也可以看成是资源的名称，在App中我们使用URI Scheme来像定位一个网页一样，定位一个应用甚至App中的某一个页面

• 获取URI Scheme链接：
  • ALink短链：点击ALink短链的获取链接，获取之前配置的URI Scheme，如下所示：

• 合作渠道再营销推广活动：鼠标hover在绿色的再营销上面，会出现URL Scheme的tips，copy之，如下图所示：

• 在AndroidManifest.xml中对<activity />标签增加<intent-filter />设置Scheme，配置示例如下：

<activity
    android:name=".CaseActivity"
    android:label="@string/app_name"
    android:theme="@style/AppTheme.NoActionBar">
    <intent-filter>
        <action android:name="android.intent.action.MAIN" />
        <category android:name="android.intent.category.LAUNCHER" />
    </intent-filter>
    <intent-filter>
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />
        <data
            android:host="yourhost"
            android:path="/path"
            android:port="8088"
            android:scheme="${填写你的URI Scheme}" />
    </intent-filter>
</activity>

上边配置文件中配置了两组，第一组是作为应用的默认启动Activity配置，第二组是通过URL Scheme方式启动，其本身也是隐式启动的一种，不同在于添加了属性，定义了其接受URL Scheme协议格式为scheme://yourhost:port/path
注：上述的Activity可以按照接入方自己的实际情况来配置，一般来说，将其配置在主页的activity上，然后通过ALink回调带回来的参数进行自定义页面路由，下面会详细介绍

1.1.2 配置App Links

根据App Links的官方定义，简单来说，App Links是一种特殊的DeepLink（与URL Scheme调起App的实现方式不同），它可以让你的应用和你的网站URL进行绑定，这样当你在点击你网站链接的时候（非浏览器中）就能调起你的App，而不是出现选择界面, 也不会出现类似URL Scheme的重复问题

• 按照之前的配置的ALink链接， 查看是否能正常下载assetlinks.json文件

在浏览器中输入https://{domain}/.well-known/assetlinks.json, 查看是否能正常下载assetlinks.json文件
其中，domain是ALink的域名，如：jd.volctracer.com
assetlinks.json文件示例如下：

[
    {
        "relation": [
            "delegate_permission/common.handle_all_urls"
        ],
        "target": {
            "namespace": "android_app",
            "package_name": "{package name}",
            "sha256_cert_fingerprints": [
                "{your sha256_cert_fingerprints}"
            ]
        }
    }
]

• 在manifest中开启autoVerify，并配置App Links协议

<activity
    android:name=".CaseActivity"
    android:label="@string/app_name"
    android:theme="@style/AppTheme.NoActionBar">
    <intent-filter android:autoVerify="true">
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />
        <data
            android:host="${你的ALink域名}"
            android:pathPrefix="/a"
            android:scheme="https" />
    </intent-filter>
</activity>

这里也可以同时支持URL Scheme和Apps Links，也就是多host绑定

<activity
    android:name=".CaseActivity"
    android:label="@string/app_name"
    android:theme="@style/AppTheme.NoActionBar">
    <intent-filter android:autoVerify="true">
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />
        <data
            android:host="${你的ALink域名}"
            android:pathPrefix="/a"
            android:scheme="https" />
    </intent-filter>
    <intent-filter>
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />
        <data
            android:scheme="${你的URI Scheme}" />
    </intent-filter>
</activity>

1.1.3 SDK集成

上面，我们App的深度链接已经配置完成，这里，我们需要初始化集成ALink相关的方法，目的：

• 让深度链接回调生效

  • 获取深度链接的回调内容，进一步处理用户行为，比如：你可以为用户提供个性化的内容，或者将他们带到App内的指定activity页面

  • 实现onALinkData接口，获取链接数据内容

初始化时，通过实现IALinkListener来获取深度链接唤起后的ALink相关数据，代码如下：

AppLog.setALinkListener(new IALinkListener() {
    @Override
    public void onALinkData(@Nullable Map<String, String> map, @Nullable Exception e) {
        JSONObject obj = new JSONObject(map);
        Intent intent = new Intent(context, TracerActivity.class);
        intent.putExtra("deeplink", obj.toString());
        intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK);
        context.startActivity(intent);
    }
 
});

 // 最后初始化结束
 AppLog.init(context, config);  // 初始化Applog SDK

onALinkData入参map具体数据内容参考下面的章节：onALinkData接口返回数据

• 触发深度链接

在配置App Links或者URI Scheme的Activity中触发深度链接(一般在首页activity即可)，示例代码如下：

//配置App Links或者URI Scheme的Activity
public class CaseActivity extends AppCompatActivity {
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        
        // 触发深度链接
        Uri appLinkData = getIntent().getData();
        AppLog.activateALink(appLinkData);
    } 
}

1.2延迟深度链接

1.2.1 前置：确保深度链接集成部分已经完成

1.2.2 启用延迟深度链接

在SDK初始化时，启用延迟深度链接，config.enableDeferredALink();

1.2.3 SDK集成onAttributionData方法

初始化时，通过在IALinkListener中增加onAttributionData方法来获取每一次安装用户的归因数据。通过这个方式，你可以为安装用户提供个性化的内容，或者将他们带到App内的指定activity页面
增加后的代码如下所示：

AppLog.setALinkListener(new IALinkListener() {
    @Override
    public void onALinkData(@Nullable Map<String, String> map, @Nullable Exception e) {
    JSONObject obj = new JSONObject(map);
    Intent intent = new Intent(context, TracerActivity.class);
    intent.putExtra("deeplink", obj.toString());
    intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK);
    context.startActivity(intent);
    }

    @Override
    public void onAttributionData(@Nullable Map<String, String> map, @Nullable Exception e) {
    JSONObject obj = new JSONObject(map);
    Intent intent = new Intent(context, TracerActivity.class);
    intent.putExtra("attribution", obj.toString());
    intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK);
    context.startActivity(intent);
    }
});

1.2.4 开启剪切板

如果需要配合H5开启剪切板，则在初始化的时候开启即可，代码：AppLog.setClipboardEnabled(true);
注：只有在app安装并第一次打开时才会读取剪切板

前置条件：

• 集成ALink前，应保证您的app已经按照iOS SDk集成指南正确集成

• 支持本功能的SDK版本为6.5.0及后续版本。最新版SDK下载

2.1深度链接

2.1.1 配置URI Scheme

URI Scheme是一个可以让App相互之间可以跳转的协议，适用于所有平台（Android和iOS)。开发者首先注册应用的URI Scheme。当用户点击该Scheme的URI时，系统会打开相应应用并回调OpenURL方法。在该方法中，开发者可根据URI的参数做相应的页面路由。注意，需要避免设置的URL Scheme与别的APP以及的URI Scheme冲突。

• 将URL Scheme添加到你的项目中，示例如下：

• 如果是iOS13及以上，重写UISceneDelegate的回调方法，代码如下：
  • Object-C

#import <RangersAppLog/BDAutoTrackSchemeHandler.h>

- (void)scene:(UIScene *)scene openURLContexts:(NSSet<UIOpenURLContext *> *)URLContexts {
    for (UIOpenURLContext *context in URLContexts) {
        NSURL *URL = context.URL;
        if ([[BDAutoTrackSchemeHandler sharedHandler] handleURL:URL appID:@"appid" scene:scene]) {
            continue;
        }

        /// ……
    }
}

• Swift

import RangersAppLog

func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey : Any] = [:]) -> Bool {  
    if(BDAutoTrackSchemeHandler.shared().handle(url, appID: "appid", scene: nil)) {
       return true
    }      
    return false
}

• 如果是iOS13以下，则重写UIApplicationDelegate的回调方法，代码如下：

#import <RangersAppLog/BDAutoTrackSchemeHandler.h>

- (BOOL)application:(UIApplication *)app openURL:(NSURL *)url options:(NSDictionary<UIApplicationOpenURLOptionsKey, id> *)options {
    if ([[BDAutoTrackSchemeHandler sharedHandler] handleURL:url appID:@"appid" scene:nil]) {
        return YES;
    }
    // 把ALink url传给SDK
    if ([BDAutoTrack continueALinkActivityWithURL:url]) {
        return YES;
    }
    /// ……
    return NO;
}

2.1.2 配置Universal Links

Universal Link（通用链接）可以允许iOS 9+的用户通过点击Universal Link无缝重定向到另一个App

• 按照之前的配置的ALink链接， 查看是否能正常下载apple-app-site-association文件

在浏览器中输入https://{domain}/.well-known/apple-app-site-association, 查看是否能正常下载assetlinks.json文件
其中，domain是ALink的域名，如：jd.volctracer.com
apple-app-site-association文件示例如下：

{
    "applinks":{
        "apps":[

        ],
        "details":[
            {
                "appID":"${Team ID}.${Bundle ID}",
                "paths":[
                    "/a/*"
                ]
            }
        ]
    }
}

• 项目工程中配置Universal LInks

进入您的xcode项目中，在Capablities中开启Associated domains，在Domains中填写applinks:``yourapp.volctracer.com，yourapp（子域）必须和【ALink模板】中【子域】填写的内容一致；

• 处理UniversalLink 回调

- (BOOL)application:(UIApplication *)application continueUserActivity:(NSUserActivity *)userActivity restorationHandler:(void (^)(NSArray<id<UIUserActivityRestoring>> * _Nullable))restorationHandler {

    if ([userActivity.activityType isEqualToString:NSUserActivityTypeBrowsingWeb]) {
    
        // 把ALink url传给SDK
        if ([BDAutoTrack continueALinkActivityWithURL:userActivity.webpageURL]) {
            return YES;
        }
        return NO;
    }
    return YES;

}

2.1.3 SDK集成

上面，我们App的深度链接已经配置完成，这里，我们需要初始化集成ALink相关的方法，目的：

• 让深度链接回调生效

• 获取深度链接的回调内容，进一步处理用户行为，比如：你可以为用户提供个性化的内容，或者将他们带到App内的指定页面

• App启动完成的时候，初始化配置SDK, 并注册返回路由信息的代理，如下所示：

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
           
    /* 6.x 版本 初始化开始 */
    BDAutoTrackConfig*config = [BDAutoTrackConfig configWithAppID:@"appid" launchOptions:launchOptions]; //您申请APPID,如不清楚请联系专属客户成功经理
    /* 5.x 版本 初始化开始 
    BDAutoTrackConfig*config =[BDAutoTrackConfig configWithAppID:@"appid"]; //您申请APPID,如不清楚请联系专属客户成功经理*/
    config.serviceVendor = BDAutoTrackServiceVendorCN; //数据上报

    config.appName = @"your appName";  // 与您申请APPID时的app_name一致
    config.channel = @"App Store"; // iOS一般默认App Store
    
    config.abEnable = YES; //开启ab测试，默认为YES
    config.showDebugLog = NO; // 是否在控制台输出日志，仅调试使用，需要同时设置logger。release版本请设置为 NO
    //config.logger = ^(NSString * _Nullable log) {NSLog(@"%@",log);}; //如果 showDebugLog设置为 YES 请打开这里的注释
    config.logNeedEncrypt = YES; // 是否加密日志，默认加密。release版本请设置为 YES
    config.autoTrackEnabled = YES; //是否开启全埋点采集用于圈选功能
    
    [BDAutoTrack startTrackWithConfig:config];
    /* 初始化结束 */  
    
    // 注册接收ALink路由信息的代理, 在这里以AppDelegate对象举例。代理对象需要实现BDAutoTrackALinkRouting协议
    [BDAutoTrack setALinkRoutingDelegate:self];
    
    return YES
}

• 在AppDelegate 中通过实现 onALinkData来获取App唤醒后带来的链接配置数据，如下所示：

// see BDAutoTrackALinkRouting.h

/// Deep link callback 根据回调返回的路由信息路由页面
/// 发生于应用已安装情况下，用户点击ALink时
/// @param routingInfo 路由信息
- (void)onALinkData:(nullable NSDictionary *)routingInfo error:(nullable NSError *)error {
    if (!error && routingInfo) {
       // 路由或打印日志
    }
}

onALinkData入参routingInfo具体数据内容参考下面的章节：onALinkData接口返回数据

2.2 延迟深度链接

2.2.1 前置：确保深度链接集成部分已经完成

2.2.2 启用延迟深度链接

在iOS650版本及之前默认是启用的，为了对齐Android，在iOS660版本之后需要配置开启，代码：config.enableDeferredALink = YES;
如果在iOS650及之前使用了ALink，在升级到新版本后一定要开启

2.2.3 实现onAttributionData方法

在AppDelegate中通过实现onAttributionData 来获取每一次安装用户的归因数据，继而进行下一步行为，如：为安装的用户提供个性化的内容，或者将他们带到App内的指定页面

// see BDAutoTrackALinkRouting.h

/// Deferred deep link callback 根据回调返回的路由信息路由页面
/// 发生于应用首启时（包括卸载重装）
/// @param routingInfo 路由信息
- (void)onAttributionData:(nullable NSDictionary *)routingInfo error:(nullable NSError *)error {
    if (!error && routingInfo) {
       // 路由或打印日志
    }
}

onAttributionData入参routingInfo具体数据内容参考下面的章节：onAttributionData接口返回数据

2.2.4 开启剪切板

如果需要配合H5开启剪切板，则实现BDAutoTrackAlinkRouting的shouldALinkSDKAccessPasteBoard方法，返回true即可开启剪切板读取（只有在App安装第一次打开的时候才会读取）：

BDAutoTrackAlinkRouting
@implementation AppDelegate
...
- (bool)shouldALinkSDKAccessPasteBoard {
    return true;
}
@end

3.1 onALinkData接口返回数据

样例数据展示：

{
    "name":"alink0001",
    "utm_campaign":"TR_Im9Qrbqo",
    "utm_source":"CH_KCViqxjI",
    "utm_medium":"",
    "utm_content":"",
    "utm_term":"",
    "tr_shareuser":"111",
    "tr_admaster":"222",
    "tr_param1":"333",
    "tr_param2":"444",
    "tr_param3":"555",
    "tr_param4":"666",
    "tr_dp":"tracer:\/\/?tr_token=Im9Qrbqo",
    "is_retargeting":"true",
    "reengagement_window": "950400",
    "reengagement_time": "1624952216",
    "deeplink_value":"product_89003"
}

3.2 onAttributionData接口返回数据

样例数据展示：

{
    "name":"alink0001",
    "utm_campaign":"TR_Im9Qrbqo",
    "utm_source":"CH_KCViqxjI",
    "utm_medium":"",
    "utm_content":"",
    "utm_term":"",
    "tr_shareuser":"111",
    "tr_admaster":"222",
    "tr_param1":"333",
    "tr_param2":"444",
    "tr_param3":"555",
    "tr_param4":"666",
    "is_retargeting":"true",
    "reengagement_window":"950400",
    "tr_dp":"tracer://?tr_token=Im9Qrbqo",
    "deeplink_value":"product_89003",
    "tr_site_id":"",
    "tr_site_name":"",
    "account_id":"",
    "account_name":"",
    "campaign_id":"",
    "campaign_name":"",
    "ad_id":"",
    "ad_name":"",
    "creative_id":"",
    "creative_name":"",
    "tr_install_type":"reattribution",
    "touch_type":"click",
    "touch_timestamp":"1624951854",
    "activation_type":"promotion",
    "activation_timestamp": "1624952064",
    "is_first_launch": "true"
}