iOS端Deeplink集成文档

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

注意：

  • 如您需要热云为您提供iOS端再营销或Deeplink归因产品和服务，请详细阅读本文档；
  • 初始化接口为SDK必接接口（最新SDK下载）
  • 如果接入deeplink事件监测，请务必在application:didFinishLaunchingWithOptions函数中调用初始化方法，以确保deeplink事件调用时相应参数已经准备就绪；
  • 支持本功能的SDK版本为1.5.1及后续版本。

URL Scheme部分

URL Scheme是一个可以让App相互之间可以跳转的协议，iOS的APP可以注册自己的URL Scheme，URL Scheme是为方便App之间互相调用而设计的。我们可以通过系统的OpenURL来打开该App，并可以传递一些参数。如果您设置的URL Scheme与别的APP的URL Scheme冲突时，您的App不一定会被调起。因为在App安装的时候，系统里面已经注册了您的URL Scheme。
一般情况下，是会调用先安装的app。但是iOS的系统App的URL Scheme肯定是最高的。所以我们定义URL Scheme的时候，尽量避开系统App已经定义过的URL Scheme。

如何配置URL Scheme

  1. 在Xcode中，打开应用信息 plist 文件；
  2. 右键选择Add Row，添加 URL types；
  3. 点击展开URL types 和item 0 ，右键选择Add Row，添加URL Schemes，图中URL Scheme为reyunDemo

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

  1. 登录热云后台，进入【推广活动管理】-【新建推广活动】；
  2. 选择一个常规【推广活动渠道】-开启【创建再营销推广活动】-填写【深度链接自定义URL Scheme】，此处填写的URL Scheme地址，scheme必须与您在xcode中配置的schemes一致，除此之外，您还可以在scheme后追加路径和参数，用于打开某个具体页面或实现业务功能；
  3. 配置完其他必填选项后，点击【立即创建】

Universal Link部分

Universal Link（通用链接）可以允许iOS 9+的用户通过点击Universal Link无缝重定向到一个App，而不需要通过Safari打开跳转。

Universal Link的实现原理
在安装某个app的时候，iOS系统会检查APP 包体内是否有associated domain相关配置，如果发现有associated domain字段，会读取applinks的地址，比如yourcompany.link.tracking.com，然后系统会去该域名根目录或.well-known下寻找一个名为apple-app-site-association的文件，如果有，那么下载到本地，然后解析这个文件。根据path建立与appid的映射关系，保存在系统的数据库中。如果有访问https://yourcompany.link.tracking.com/path/的链接，系统会根据映射关系找到的appid，启动该app，实现Universal link。

Universal Link的优势

  1. 使用HTTP/HTTPS标准协议，相对URL Scheme而言更加的安全，因为其他应用无法声明通用链接；
  2. Universal Link既适用于您的网站，也适用于您的App，未安装App时，点击链接会在Safari中打开；
  3. 用户体验更佳，调起App时无弹窗提醒，可以不通过Safari打开跳转；

Universal Link的局限性

  1. 仅支持iOS 9+设备，iOS 9以下的设备，会直接跳转到Safari打开网页，即使当前设备中已经安装有App；
  2. 目前部分App已经禁用Universal Link直接调起App，例如微信，这里涉及到白名单的机制，除过嫡系App，其余App均不可在微信中被直接吊起；

热云后台配置Universal link

  1. 登录热云后台，进入【配置】-【应用配置】-【DeepLink配置】；
  2. 填写子域，AppID prefix和BundleID，点击保存，五分钟生效；
  3. 进入【推广活动管理】-【新建推广活动】-选择一个常规【推广活动渠道】-开启【创建再营销推广活动】-填写【深度链接自定义URL Scheme】-开启【启用Universal Link 支持深度链接】-填写【Path】
  4. 完成其余活动配置后，点击保存，五分钟生效；
  5. 进入您的xcode项目中，在Capablities中开启Associated domains，在Domains中填写applinks:yourcompany.link.trackingio.com，yourcompany（子域）必须和热云【Deeplink参数配置】中【子域】填写的内容一致；



SDK上报invoke事件

  • 方法接口：

+(void)setEvent:(NSString *)eventName;

  • 上报时机：由URL Scheme或Universal Link直接调起App后上报invoke事件
  • 参数说明：
参数类型是否必填长度说明
eventNameNSString是最长32位自定义事件名称，必须为invoke
  • 示例代码：

[Tracking setEvent:@"invoke"];

  • 使用方法示例：各个系统函数使用情况对应图中绿框内文字，invoke为deeplink直接调起app上报的专属事件，请确保是由deeplink调起后上报。

延迟Deeplink部分

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

如何通过热云实现延迟Deeplink

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

+ (void)setDeferredDeeplinkCalllbackDelegate:(id<DeferredDeeplinkCalllback>) delegate ;

  • 参数说明：
参数类型是否必填长度说明
delegateid是延迟深度链接回调代理对象
  • 协议:
@protocol DeferredDeeplinkCalllback <NSObject>
@optional
- (void)onDeferredDeeplinkCalllback:(NSDictionary *)params;
@end
  • 协议说明：
    请在调用init函数（初始化）前传入非空的已经实现DeferredDeeplinkCalllback协议。onDeferredDeeplinkCalllback:函数的对象用来接收归因成功后，服务器透传的用户填写在trackingio后台的deeplink相关参数，如果成功回调，该字典会包含两个键值对，如果不成功，则返回空字典：
{
“dp_url”:”xxx”,
“dp_path”:”xxx”
}

Deeplink与延迟Deeplink的测试步骤

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

  1. 准备工作：将测试设备的IDFA加入设备白名单，进入后台【设备白名单】-【添加设备】即可，添加后十五分钟生效；

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

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

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

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

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

    （截图为URL Scheme设置为wechat://open时的测试结果）