Android端Deeplink集成文档

本文档包含了：
1.URL Scheme和App Links的介绍以及实现原理；
2.在您项目中应如何配置，以实现URL Scheme和App Links调起App，并通过SDK上报invoke事件；
3.延迟Deeplink的介绍以及如何集成热云SDK实现延迟Deeplink；
4.如何进行Deeplink以及延迟Deeplink测试联调；

注意：

• 如您需要热云为您提供Android端再营销或Deeplink归因产品和服务，请详细阅读本文档；
• 初始化接口为SDK必接接口（最新SDK下载）
• 支持本功能的SDK版本为1.5.9及后续版本。

URL Scheme部分

Android中的scheme是一种页面内跳转协议，是一种非常好的实现机制，通过定义自己的scheme协议，可以非常方便跳转app中的各个页面。iOS和Android两端的URL Scheme原理基本一致，只是由于底层操作系统不同，实现方法不同。

如何配置URL Scheme

1. 在AndroidManifest.xml中对<activity />标签增加<intent-filter />设置Scheme

<activity android:label="SDKDemo" android:name="com.reyun.test.MainActivity">
    <intent-filter>
        <action android:name="android.intent.action.MAIN" />
        <category android:name="android.intent.category.LAUNCHER" />
    </intent-filter>
    <!--想要成功调调起APP，必须添加intent过滤器-->
    <intent-filter>
        <!--下面这几行必须设置-->
        <action android:name="android.intent.action.VIEW" />
        <!--表示该页面可以被隐式调用，必加该项-->
        <category android:name="android.intent.category.DEFAULT" />
        <!--应用可以通过浏览器的连接启动，必加该项-->
        <category android:name="android.intent.category.BROWSABLE" /
        <!--URL Scheme协议部分，这里填写的scheme必须与热云后台填写的scheme一致-->
        <data
            android:host="yourhost"
            android:path="/urlschemepath"
            android:port="8088"
            android:scheme="reyuntest" />
    </intent-filter>
</activity>

上边配置文件中配置了两组，第一组是作为应用的默认启动Activity配置，第二组是通过URL Scheme方式启动，其本身也是隐式启动的一种，不同在于添加了属性，定义了其接受URL Scheme协议格式为`reyuntest://yourhost:8088/urlschemepath`
#
组成URI的这些属性在中都是可选的，但是存在如下制约关系：
1.如果没有指定scheme，那么host参数会被忽略
2.如果没有指定host，那么port参数会被忽略
3.如果scheme和host都没有指定，path参数会被忽略

当intent对象中的URI中的参数与intent-filter中的标签指定的URI格式进行对比，只对比intent-filter的标签指定的部分，例如：
1.如果intent-filter中只指定了scheme，那么所有带有该sheme的URI都能匹配到该intent-filter。
2.如果intent-filter中只指定了scheme和authority（authority包括host和port两部分）而没有指定path，那么所有具有相同scheme和authority的URI都能匹配到该intent-filter，而不用考虑path为何值。
3.如果intent-filter中同时指定了scheme、authority和path，那么只有具有相同scheme、authority和path的URI才能匹配到该intent-filter。

2. 如何调用，如何校验URL Scheme是否有效

// url scheme
String url = "reyuntest://yourhost:8088/urlschemepath?id=1234";
Uri uri = Uri.parse(url);
Intent intent = new Intent(Intent.ACTION_VIEW, uri);
intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK);
intent.setComponent(null);
intent.setSelector(null);
if (checkUrlScheme(intent)) {
    try {
        startActivity(intent);
    } catch (ActivityNotFoundException e) {
        e.printStackTrace();
    }
}// 检查url scheme 是否有效
boolean checkUrlScheme(Intent intent) {
    PackageManager packageManager = getPackageManager();
    List<ResolveInfo> activities = packageManager.queryIntentActivities(intent, 0);
    return !activities.isEmpty();
}

3. 获取Scheme跳转的参数

private void handlerIntent() {
    Intent intent = getIntent();
    if (null == intent) {
        System.out.println("intent == null");
        return;
    }
    Uri uri = intent.getData();
    if (null == uri) {
        System.out.println("uri == null");
        return;
    }
    // 完整的URL信息
    String url = uri.toString();
    System.out.println("URL = " + url);
    // Scheme
    String scheme = uri.getScheme();
    System.out.println("Scheme = " + scheme);
    // Host
    String host = uri.getHost();
    System.out.println("Host = " + host);
    // port
    int port = uri.getPort();
    System.out.println("Port = " + port);
    // path
    String path = uri.getPath();
    System.out.println("Path = " + path);
    // query
    String query = uri.getQuery();
    System.out.println("Query = " + query);
}

热云后台配置URL Scheme

严格意义上，热云不参与您建立URL Scheme机制的过程，您需要按照上一步的方法配置，提供现成可用的URL Scheme按照如下步骤生成热云监测短链：

1. 登录热云后台，进入【推广活动管理】-【新建推广活动】；
2. 选择一个常规【推广活动渠道】-开启【创建再营销推广活动】-填写【深度链接自定义URL Scheme】，此处填写的URL Scheme地址，scheme，host，port，path，query等参数必须与您在您Android项目中填写的参数一致；
   注：一般来说，您在项目和热云后台中只保证scheme一致即可，其他参数均有可能随业务需求变化而变化。
3. 配置完其他必填选项后，点击【立即创建】
   

App Links部分

App Links的官方定义如下：

Android App Links are a special type of deep link that allow your website URLs to immediately open the
corresponding content in your Android app (without requiring the user to select the app).
To add Android App Links to your app, define intent filters that open your app content using HTTP URLs (as
described inCreate Deep Links to App Content), and verify that you own both your app and the website
URLs (as described in this guide). If the system successfully verifies that you own the URLs, the system
automatically routes those URL intents to your app.
简单来说，App Links是一种特殊的DeepLink（与URL Scheme调起App的实现方式不同），它可以让你的应用和你的网站URL进行绑定，这样当你在点击你网站链接的时候（非浏览器中）就能调起你的App，而不是出现选择界面，使用方法如下Create Deep Links to App Content，这种绑定不是在点击的时候才核对链接，下面会介绍在什么情况下核对这种绑定的。

与URL Scheme的区别

Android DeepLink的底层实现方式其实就是URL Scheme（iOS端也是如此），官方是这样介绍的：

Adeep linkis an intent filter that allows users to directly enter a specific activity in your Android app.
Clicking one of these links might open a disambiguation dialog, which allows the user to select one of
multiple apps (including yours) that can hande the given URL. For example, figure 1 shows the
disambiguation dialog after the user clicks a map link, asking whether to open the link in Maps or Chrome.
Deeplink是一个intent过滤器，他可以使用户直接进入某个Activity页面。但是有个不好的是当匹配到多个intent时就会弹一个让用户选择的框。官方给了下面一张图，而AppLinks就不会有这个弹框：

DeepLink（URL Scheme）和AppLinks的一些优劣势：

项目	DeepLink	AppLinks
Intent URL	自定义URL Scheme	必须是http/https标准协议
Intent action	任何action	必须是android.intent.action.VIEW
Intent category	任何category	必须是android.intent.category.BROWSABLE 和 android.intent.category.DEFAULT
链接校验机制	没有校验逻辑	必须有一个HTTPS的JSON校验文件
用户体验	可能会弹出一个选项框让用户选择从哪里打开这个链接	没有选择弹框，都将从您的App打开这个链接
系统兼容性	任何Android版本	Android 6及以上

热云后台配置App Links

1.首先，您需要在热云后台配置有关App Links的相关参数，其中包括热云为您App拉取assetlinks.json文件而分配的子域、Android package name（App包名）和SHA 256_cert_fingerprints（正式版的签名）。

sha256_cert_fingerprints的获取方法：找到您App的keystore，在命令行中输入keytool -list -v -keystore apk-key.keystore

2.保存配置后，在浏览器中输入https://domain.link.trackingio.com/.well-known/assetlinks.json查看是否能正常下载assetlinks.json文件。该文件会在android:autoVerify="true"的自动验证机制下，使得App第一次安装完成后通过这个地址自动下载assetlinks.json文件到本地，这一步热云已经自动封装在SDK中实现。
assetlinks.json文件格式如下：

[{
	"target": {
		"package_name": "com.reyun.DeepLink",
		"sha256_cert_fingerprints": ["ED:43:91:CA:57:25:D6:51:33:F8:94:3F:DA:51:F8:1D:36:A3:98:F8:B6:11:C3:63:1C:FC:66:0A:55:8A:1B:F4"],
		"namespace": "android_app"
	},
	"relation": ["delegate_permission/common.handle_all_urls"]
}]

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

<activity android:name="com.reyun.DeepLink">
<intent-filter>
<category android:name="android.intent.category.LAUNCHER" />
</intent-filter>
<!--下面这几行必须设置-->
<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" />
<!--配置AppLinks协议-->
<data android:scheme="https"
android:host="domain.link.trackingio.com"
android:pathPrefix="/ry" />
</intent-filter>
</activity>

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

<intent-filter>
  ...
  <data 
  android:scheme="https"
  android:host="domain.link.trackingio.com"
  android:pathPrefix="/ry" />
  <data
  android:host="yourhost"
  android:path="/urlschemepath"
  android:port="8088"
  android:scheme="reyuntest" />
</intent-filter>

4.最后，您需要在热云后台生成一条包裹了AppLinks的热云监测链接。进入【推广活动管理】-【新建推广活动】-选择一个常规【推广活动渠道】-开启【创建再营销推广活动】-填写【深度链接自定义URL Scheme】-开启【启用App Links 支持深度链接】-填写【Path】

SDK上报invoke事件

• 方法接口：

setEvent(final String eventName);

• 上报时机：由URL Scheme或App Link直接调起App后上报invoke事件
• 参数说明：

参数	类型	是否必填	长度	说明
eventName	String	是	最长32位	自定义事件名称，必须为invoke

• 示例代码：

[Tracking setEvent:@"invoke"];

延迟Deeplink

延迟Deeplink定义
延迟Deeplink（Deferred Deeplink）并不是URL Scheme或App Links（或iOS Universal Links）之外的一种深度链接，而是一种实时将再营销广告归因结果返回给客户端调用的归因技术，延迟Deeplink技术解决了传统Deeplink在用户当前未安装App时，重新下载打开App后无法跳转到App指定页面（非首页）的问题。热云延迟Deeplink归因技术，能够在毫秒级内完成归因，并将用户点击广告素材对应的Deeplink返回给客户端，100%还原广告场景，满足用户个性化推荐需求，提升用户留存和付费意愿。

如何通过热云实现延迟Deeplink

1. 延迟Deeplink的前提是您已经在热云完成了所有有关Deeplink（URL Scheme或App Links）的配置；
2. 在此基础上，您需要在SDK中集成以下方法：

// 需要在初始化之前设置deep link回调接口
Tracking.setDeepLinkListener(new IDeepLinkListener() {
    /**
     * @param isSuccess 是否为deep link触发
     * @param dpUrl deep link配置的url，只有成功时返回，否则为null
     * @param dpPath deep link配置的path，只有成功时返回，否则为null
     * */
    @Override
    public void onComplete(boolean isSuccess, String dpUrl, String dpPath) {
        // 在这里调用自己的代码，注意，这里是工作线程，不是主线程！
        Log.i(MainActivityForTracking.class.getSimpleName(), "isSuccess：" + isSuccess+ ",dpUrl：" + dpUrl + ", dpPath：" + dpUrl);
    }
});

3. 当dpUrl和dpPath不为空时，您即可获取该值，在适合的时机打开相应页面；如果callback返回null，即代表此次install事件（初始化）归因的结果不是deeplink广告带来的。

Deeplink与延迟Deeplink的测试步骤

自此，URL Scheme、App Links和延迟Deeplink方法已经全部配置完成，在使用前，您需要按照以下几点进行测试，以保证能够正常工作：

1. 准备工作：将测试设备的设备id加入设备白名单，进入后台【设备管理】-【添加设备】即可，添加后十五分钟生效；
   注：android 10以下建议使用IMEI作为主要的android设备id，android 10以上使用oaid
   

2. 测试工具：我们为您提供了模拟用户点击广告的测试小工具，您可通过在Safari中打开测试工具，输入热云监测链接，检查是否可以调起App（或指定页面）；
   

3. 获取热云点击监测短链：登录热云后台，进入【推广活动管理】中复制您创建的再营销点击监测短链。
   注：链接中如有noredirect=true时，则表明该链接为非302模式短链，测试时须去掉；
   

4. 测试工具使用：将短链中IMEI宏参替换为测试设备IMEI后，输入短链至测试工具，点击【确定】检查短链，无误后点击【打开应用】；
   

5. 延迟Deeplink测试：确保点击【打开应用】时，设备中未安装测试App，此时将跳转至您在【新建活动】时填写的【应用下载地址】，若您的App未上架，请将测试App安装至设备（此处模拟线上App在App Store下载安装的步骤），打开后检查是否跳转到对应的App页面，如果有跳转到对应App页面，前往热云后台【再营销活动详情】查看指标【延迟调起新增设备数】是否+1；
   

6. URL Scheme与App links直接调起测试：确保点击【打开应用】前，设备中已安装测试App，此时将跳转至您在【新建活动】时填写的【深度链接自定义URL Scheme】（使用URL Scheme作为Deeplink时）或【Path】（使用App links作为Deeplink时）所对应的App页面。如果您是在卸载重装App的情况下测试时，此时指标【延迟调起新增设备数】+1，这是由于此次测试虽然是由Deeplink直接调起，但因该激活为全新激活，存在初始化事件（install）且初始化比直接调起事件（invoke）更早上报，后端归因将根据install归因再营销转化；如果您测试前已经打开过App，又通过热云短链直接调起App，此时调起类型为【直接调起设备数】+1，这是因为此次测试中没有上报初始化（install），只有invoke事件；
   
   （截图为URL Scheme设置为wechat://open时的测试结果）