深度链接

1. 深度链接功能介绍
1.1 链接目标 — 跳转到哪儿？
1.2 链接触发点 — 从哪儿发起跳转？

2. 功能接入
2.1 预先配置的深度链接
2.2 动态深度链接
2.3 处理链接到游戏中的深度链接

1. 深度链接功能介绍

KTplay的深度链接功能，主要用于实现社区、游戏、网站等不同功能模块之间的快速跳转。

1.1 链接目标 — 跳转到哪儿？

链接目标是指所有可以跳转到的位置，主要包括：

• KTplay社区 (KTRL)
  
  KTplay可跳转位置，即社区子页面如话题列表，收件箱，专题等。
  
  KTplay已定义好所有可跳转页面，创建链接时直接选择即可。
  
  触发链接时，SDK直接打开对应的社区页面。

• 游戏 (GRL)
  
  游戏可跳转位置，即游戏的不同场景如主菜单，商店，设置等。
  
  你需要事先定义好所有位置名称，命名规则可自己定义，如game.menu代表游戏主菜单，game.store代表游戏商店。
  
  触发链接时，SDK将位置名称回调给游戏，游戏需要根据位置名称(如game.store)跳转到相应的位置。

• 网站 (URL)
  
  位置即具体的网址。
  
  触发链接时，SDK会打开对应的网页(使用外部浏览器)

除了链接位置的名称，你还可以通过附加参数，跳转到更具体的位置，或展示更细节的内容。

• KTplay社区
  
  根据不同的页面提供不同的参数选择，如发布话题页面支持设置话题分类，预置标题，预置内容。

• 游戏
  
  参数可附加在你的命名规则中，如你的游戏商店共有8个商品，可以使用game.store.3代表第3个商品。

1.2 链接触发点 — 从哪儿发起跳转？

链接触发点即发起链接的位置，可理解为链接入口或载体。

• KTplay社区
  
  KTplay目前支持在通知和话题中附带深度链接

• 游戏
  
  游戏的链接触发点，可以是一个具体的按钮，也可以是游戏的某类事件如关卡结束。

2. 功能接入

你可以通过两种方法使用深度链接： 预先配置的深度链接 和 动态深度链接 。

2.1 预先配置的深度链接

深度链接需要在KTplay后台预先定义，KTplay后台会为每个深度链接生成唯一ID， 接入SDK时依据ID打开对应的链接内容。
好处是接入完成后，深度链接的内容可以根据需要在后台作调整，不需要更新游戏。

第1步 设计深度链接触发点

接入具体功能之前，你需要根据具体需求设计好深度链接触发点(在哪些地方放置深度链接)。

第2步 创建深度链接并导出配置

SDK通过深度链接ID来标识一个具体的链接，在游戏上线之前，你需要在开发者后台创建好所有使用到的深度链接，并导出链接ID供代码接入使用。

• 打开应用设置-深度链接，创建新的深度链接。
• 导出深度链接配置，配置包括包含链接ID、名称、描述和类型。

第3步 添加打开深度链接代码

在每个深度链接入口添加代码，打开对应的深度链接。

Android

String deeplinkId = "KTRL.1472120161";
KTPlay.openDeepLink(deeplinkId);

iOS

NSString* deeplinkId = @"KTRL.1472120161";
[KTPlay openDeepLink: deeplinkId];

Cocos2d-X

String deeplinkId = "KTRL.1472120161";
KTPlayC::openDeepLink(deeplinkId);

Unity

string deeplinkId = "KTRL.1472120161";
KTPlay.OpenDeepLink(deeplinkId);

2.2 动态深度链接

有些链接内容无法预先定义，只有在运行时才能获得（比如一场战斗的回放ID），使用动态深度链接可解决此类问题。
动态深度链接不需要在后台预先定义，接入时根据需要实时组织链接内容。

使用下面的格式来定义动态链接内容。
scheme://path?parametersString

• scheme . 链接协议，用来标识链接的类型，目前支持：
  • ktplay : 链接到KTplay资源，比如打开社区某个页面，KTplay所有可链接资源可 参考这里
  • game : 链接到游戏，用户触发链接时，SDK会将“//”之后的所有内容回调给游戏
  • 其他 : 以上所列scheme之外的内容，都会被认为是网站链接，用户触发链接时，SDK会调起打开网站流程。
• path : 目标资源路径
• parametersString : 参数。格式要求与标准URL中的参数相同，参数的名字与值之间用=分隔，不同参数之间使用&分隔，部分参数的值需要做URLEncode ( 参考这里 )。如果参数的值本身又是一个包含多个的对象

示例（打开与游戏ID为952780的用户聊天窗口）
ktplay://chat/message?game_user_id=952780

2.2.1 功能接入

第1步. 设计深度链接触发点

根据需求设计深度链接触发点(在哪些地方放置深度链接入口)。

第2步. 生成深度链接内容

附加深度链接所需参数，生成最终的链接内容。

第3步. 打开深度链接

游戏代码中需要打开深度链接的地方，调用openDeeplink方法。

Android

String deeplinkSchema = "ktplay://chat/message?game_user_id=952780";
KTPlay.openDeepLink(deeplinkSchema);

iOS

NSString* deeplinkSchema = @"ktplay://chat/message?game_user_id=952780";
[KTPlay openDeepLink: deeplinkSchema];

Cocos2d-X

String deeplinkSchema = "ktplay://chat/message?game_user_id=952780";
KTPlayC::openDeepLink(deeplinkSchema);

Unity

string deeplinkSchema = "ktplay://chat/message?game_user_id=952780";
KTPlay.OpenDeepLink(deeplinkSchema);

2.2.2 示例 - 使用深度链接发布话题

本示例要实现下列功能:

• 游戏有战斗回放功能；
• 玩家结束战斗时，可选择分享战斗回放到社区；
• 其他玩家查看该话题时，可以选择查看战斗回放，打开对应的战斗回放；

第1步. 确定要链接的页面

要实现发话题功能，需要打开KTplay社区的发话题页面，查看 KTplay可链接资源 可确定对应的路径为 topic/creation

ktplay://topic/creation

第2步. 追加基础参数

假设发话题时预置标题和文本内容

title=分享战斗
text=我完成了一场战斗

根据参数要求，title和text的值需要做URL Encode：

title=%e5%88%86%e4%ba%ab%e6%88%98%e6%96%97
text=%e6%88%91%e5%ae%8c%e6%88%90%e4%ba%86%e4%b8%80%e5%9c%ba%e6%88%98%e6%96%97

将参数追加到链接内容中:

ktplay://topic/creation?title=%e5%88%86%e4%ba%ab%e6%88%98%e6%96%97&text=%e6%88%91%e5%ae%8c%e6%88%90%e4%ba%86%e4%b8%80%e5%9c%ba%e6%88%98%e6%96%97

第3步. 追加action参数

发布话题支持action参数，action参数包含一个深度链接，以及该链接显示在话题中的样式配置。一旦话题包含action，用户查看该话题时会显示一个链接入口(目前为一个可点击的按钮)，点击后触发对应的深度链接。
此示例中，我们需要设置一个链接回游戏的深度链接，从话题中链接回游戏的战斗回放界面。

game://replay?reply_id=xxx

action对象包含:

deeplink=game://replay?replay_id=1234
title=查看回放
icon=replay

根据参数要求，deeplink和title的值需要做URL Encode:

deeplink=game%3a%2f%2freplay%3freplay_id%3d1234
title=%e6%9f%a5%e7%9c%8b%e5%9b%9e%e6%94%be
icon=replay

使用URL参数的形式拼接action的内容:

deeplink=game%3a%2f%2freplay%3freplay_id%3d1234&title=%e6%9f%a5%e7%9c%8b%e5%9b%9e%e6%94%be&icon=replay

对拼接好的内容再做一次URL Encode:

deeplink%3dgame%253a%252f%252freplay%253freplay_id%253d1234%26title%3d%25e6%259f%25a5%25e7%259c%258b%25e5%259b%259e%25e6%2594%25be%26icon%3dreplay

将最终的action值追加到deeplink参数中:

ktplay://topic/creation?title=%e5%88%86%e4%ba%ab%e6%88%98%e6%96%97&text=%e6%88%91%e5%ae%8c%e6%88%90%e4%ba%86%e4%b8%80%e5%9c%ba%e6%88%98%e6%96%97&action=deeplink%3dgame%253a%252f%252freplay%253freplay_id%253d1234%26title%3d%25e6%259f%25a5%25e7%259c%258b%25e5%259b%259e%25e6%2594%25be%26icon%3dreplay

第4步. 打开Deeplink

在需要发布话题的地方调用打开上面生成的Deeplink即可，代码示例 参考这里

第5步. 游戏中处理Deeplink回调

当用户在话题中点击查看战斗回放时，SDK会将发话题时附带的链接内容回调给游戏，游戏解析出replay_id并打开对应的战斗回放。

replay?replay_id=1234
游戏接收深度链接回调的方法 参考这里

2.2.3 KTplay可链接资源

注意事项:

• 未明确标明“可选”的参数，均为必须提供。
• 如果使用网游账号登录的方式，需要传入user_id的地方可用game_user_id替代（传入游戏的账号ID），game_user_id需要做URL Encode。
• 如果单个参数的值中包含多个属性(如发话题时的action)，需要将不同属性根据URL参数格式拼接，再对拼接结果做一次URL Encode，具体可 参考样例

资源	路径	参数
首页	homepage
精华话题	topics/recommended
全部话题	topics/category	category_id (可选)
视频话题	topics/videos
关注人的话题	topics/following
话题搜索	topics/search
话题搜索结果	topics/search/result	keyword (需要做URL Encode)
话题详情	topic	topic_id
创建话题	topic/creation	category_id (可选) title (可选，需要做URL Encode) text（可选，需要做URL Encode） image_path: 图片文件地址(可选). video_path: 视频文件地址(可选). action: 深度链接结构(可选，action包含的参数定义 参考这里 )
举报话题	topic/report	topic_id
待审核话题	topic/video/reviewing
创建回复	reply/creation	topic_id text（可选，需要做URL Encode） image_path: 图片文件地址(可选).
举报回复	reply/report	reply_id
影响力排行-总榜	influencers/ranking
影响力排行-今日榜	influencers/ranking/today
专题列表	collections
专题详情	collection	collection_id
消息页	messagepage
收件箱	inbox/message
聊天会话	chat/message	user_id或game_user_id
陌生人聊天消息	chat/message/stranger
聊天黑名单	chat/user/blocked
用户搜索	user/search
用户搜索结果	user/search/result	keyword(需要做URL Encode)
用户个人资料	user/profile	user_id或game_user_id
用户的回复	user/replies	user_id或game_user_id
用户收到的赞	user/likes/received	user_id或game_user_id
用户的关注列表	user/following	user_id或game_user_id
用户的粉丝列表	user/followers	user_id或game_user_id
用户收藏话题	user/favorite	user_id或game_user_id
举报用户	user/report	user_id或game_user_id
我的个人资料	me/profile
我的话题	me/topics
我的回复	me/replies
我的通知	me/notifications
我收到的赞	me/likes/received
我的关注列表	me/following
我的粉丝列表	me/followers
我的草稿	me/drafts
设置昵称	me/nickname/setting
设置头像	me/avatar/setting
账号绑定	me/account/binding
我的收藏	me/favorite
设置个人背景图	me/background_image/setting
设置个人签名	me/bio/setting
设置页	settings
KTPlay用户条款	ktplay/terms
关于影响力	influence/about
最近查看话题	topics/recently_viewed
最近查看用户	users/recently_viewed
登录 & 注册	authentication
登录	authentication/login
注册	authentication/register
忘记密码	authentication/password/reset
修改密码	authentication/password/setting
关于Web社区	web/about
排行榜列表	leaderboards
排行榜详情	leaderboard	leaderboard_id

发话题中action参数定义

参数	描述	必须提供	必须做URL Encode
deeplink	深度链接内容	是	是
title	深度链接描述	是	是
icon	深度链接图标样式。 目前提供replay,store,link三种样式可选择。 默认为link。	否	否

2.3 处理链接到游戏中的深度链接

如果深度链接类型为链接到游戏中（某个界面），则需要游戏配合实现具体的链接功能。当链接被触发时，SDK会将链接内容回调给游戏，游戏收到回调后，需解析链接内容并实现后续的链接流程。

Android

KTPlay.setOnDeepLinkListener(new OnDeepLinkListener() {
            @Override
            public void onDeepLink(String deepLink) {
            //下面这行是伪代码，接入时游戏需要替换成自己的处理逻辑(比如跳转到游戏内商店)
            Game.handleDeepLink(deepLink)
            }
        });

iOS

  [KTPlay setDeepLinkBlock:^(NSString *linkSchemas) {
    //下面这行是伪代码，接入时游戏需要替换成自己的处理逻辑(比如跳转到游戏内商店)
    [Game handleDeepLink:linkScheme]
  }];

Cocos2d-X

void deepLinkCallback (const char *linkSchemas){
    //下面这行是伪代码，接入时游戏需要替换成自己的处理逻辑(比如跳转到游戏内商店)
    Game::handleDeepLink(linkScheme)
}

KTPlayC::setDeepLinkCallback(deepLinkCallback );

Unity

KTPlay.SetDeepLinkDelegate ((string linkScheme) => {
    //下面这行是伪代码，接入时游戏需要替换成自己的处理逻辑(比如跳转到游戏内商店)
    handleDeepLink(linkScheme);  
});