跳到主要内容
版本:v4

内嵌动态开发指南

本文介绍如何在游戏中接入 TapTap 内嵌动态功能,使用内嵌动态功能需依赖 TapTap 登录

权限说明

集成前准备

  1. 参考 准备工作 创建应用、开启内嵌动态应用配置;
  2. 内嵌动态依赖于 TapTap 登录模块,开发者接入前应先接入 TapTap 登录 相关依赖。

SDK 获取

完成 SDK 获取,然后在此基础上可以通过 下载 获得 TapSDK,添加 TapMoment 模块:

接入外部依赖

SDK 内部使用了部分第三方库,开发者接入时需先确保 SDK 外部依赖库已正常接入,具体设置如下:

  1. SDK 使用的 JSON 解析库为 Newtonsoft-json,如果当前工程已接入该依赖库,则不需额外处理,否则需在 Packages/manifest.json 添加如下依赖:
"com.unity.nuget.newtonsoft-json":"3.2.1"
  1. SDK 使用 com.google.external-dependency-manager 管理 Android、iOS 依赖,如果当前工程已接入该依赖库,则不需额外处理,否则需在 Packages/manifest.json 添加如下依赖:
{
"dependencies": {
"com.google.external-dependency-manager": "1.2.179"
},
"scopedRegistries": [
{
"name": "package.openupm.com",
"url": "https://package.openupm.com",
"scopes": [
"com.google.external-dependency-manager"
]
}
]
}

添加 SDK 依赖

SDK 支持 Unity Package Manager 及本地文件导入两种集成方式,开发者根据需求选择其中一种即可,推荐使用远程依赖。

远程依赖

SDK 支持通过 NPMJS 及 GitHub 两种方式,开发者选择其中一种即可。

1. NPMJS 接入

在项目的 Packages/manifest.json 文件中添加以下依赖:

"dependencies":{
undefined
"com.taptap.sdk.core":"4.5.0",
"com.taptap.sdk.login":"4.5.0",
"com.taptap.sdk.moment":"4.5.0",
}

但需要注意的是,需在 Packages/manifest.jsondependencies 同级下声明 scopedRegistries

"scopedRegistries":[
{
"name": "NPMJS",
"url": "https://registry.npmjs.org/",
"scopes": ["com.taptap"]
}
]
2. GitHub 接入

在项目的 Packages/manifest.json 文件中添加以下依赖:

"dependencies":{
"com.taptap.sdk.core":"https://github.com/taptap/TapSDKCore-Unity.git#4.5.0",
"com.taptap.sdk.login":"https://github.com/taptap/TapSDKLogin-Unity.git#4.5.0",
"com.taptap.sdk.moment":"https://github.com/taptap/TapSDKMoment-Unity.git#4.5.0",
}

在 Unity 顶部菜单中选择 Window > Package Manager 可查看已经安装在项目中的包。

本地文件导入

  1. 下载页 下载下列模块对应 unitypackage 文件,并在 Unity 项目中依次通过 Assets > Import Packages > Custom Packages 进行导入,包括:

    • TapTapSDK_Core.unitypackage TapTapSDK 核心模块,必选
    • TapTapSDK_Login.unitypackage TapTapSDK 登录模块,必选
    • TapTapSDK_Moment.unitypackage TapTapSDK 内嵌动态模块,必选
  2. 如果当前项目已集成 Newtonsoft.Json 依赖,则忽略该步骤,否则在 NuGet.org Newtonsoft.Json 页面中通过点击右侧 「Download package」 下载库文件,并将下载的文件后缀从.nupkg 修改为 .zip,同时解压该文件并复制内部的 Newtonsoft.Json.dll 文件拷贝到工程 AssetsPlugins 目录下,另外为了避免导出 IL2CPP 平台时删除必要数据,需在 Assets 目录下创建 link.xml 文件(如果已有该文件,则添加如下内容),其内容如下:

<linker>
<assembly fullname="System.Core">
<type fullname="System.Linq.Expressions.Interpreter.LightLambda" preserve="all" />
</assembly>
</linker>

iOS 配置

Assets/Plugins/iOS/Resource 目录下创建 TDS-Info.plist 文件 (如果已创建,只需添加内容即可),配置相关权限并替换授权文案

提示

复制使用以下内容时,请删除空行以及注释,以免出现 XML 解析时报错,ApplicationException: expected a key node

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<!--使用内嵌动态服务,需要相册、相机、麦克风-->
<key>NSPhotoLibraryUsageDescription</key>
<string>说明为何应用需要此项权限</string>
<key>NSCameraUsageDescription</key>
<string>说明为何应用需要此项权限</string>
<key>NSMicrophoneUsageDescription</key>
<string>说明为何应用需要此项权限</string>
</dict>
</plist>

SDK 初始化

TapTapSdkOptions 详细参数见 入门指南#快速开始

using TapSDK.Core;

// 核心配置 详细参数见 [TapTapSDK]
TapTapSdkOptions coreOptions = new TapTapSdkOptions();
// TapSDK 初始化
TapTapSDK.Init(coreOptions);

设置回调

设置回调以获取动态的状态变化。

using TapSDK.Moment;

TapTapMoment.SetCallback((code, msg) =>
{
// 根据 code 处理动态事件
});

// 移除 callback
TapTapMoment.SetCallback(null);

回调方法中 code 表示事件类型,现支持的回调类型如下:

回调回调值说明
CALLBACK_CODE_PUBLISH_SUCCESS10000动态发布成功
CALLBACK_CODE_PUBLISH_FAIL10100动态发布失败
CALLBACK_CODE_PUBLISH_CANCEL10200关闭动态发布页面
CALLBACK_CODE_GET_NOTICE_SUCCESS20000获取新消息成功
CALLBACK_CODE_GET_NOTICE_FAIL20100获取新消息失败
CALLBACK_CODE_MOMENT_APPEAR30000动态页面打开
CALLBACK_CODE_MOMENT_DISAPPEAR30100动态页面关闭
CALLBACK_CODE_CLOSE_CANCEL50000取消关闭所有动态界面(弹框点击取消按钮)
CALLBACK_CODE_CLOSE_CONFIRM50100确认关闭所有动态界面(弹框点击确认按钮)
CALLBACK_CODE_LOGIN_SUCCESS60000动态页面内登录成功
CALLBACK_CODE_SCENE_EVENT70000场景化入口回调

获取新消息

定时调用获取消息通知的接口,有新信息时可以在 TapTap 动态入口显示小红点,提醒玩家查看新动态。

using TapSDK.Moment;

TapTapMoment.FetchNotification();

获取消息通知的结果会在本文刚开始设置的回调中返回,codeCALLBACK_CODE_GET_NOTICE_SUCCESS20000)表示获取成功,CALLBACK_CODE_GET_NOTICE_FAIL20100)表示获取失败。 获取成功时,msg 为新消息数量,0 表示没有新消息。

提示

为了方便玩家查看好友动态、游戏公告等,我们建议将 TapTap 动态入口放在显眼的位置,每分钟调用 1 次获取消息通知的接口。

获取消息通知时,如果没有新消息(msg0),那么游戏需要清除界面上的小红点。 同样,打开 TapTap 动态页面后,游戏也需要清除界面上的小红点。

显示动态页面

在游戏中显示 TapTap 动态页面,玩家可以查看及发布动态。

using TapSDK.Moment;

TapTapMoment.open();
备注

打开动态页面时,请先屏蔽游戏自身的声音,以免干扰动态内的视频声音。

如需要动态能支持横竖屏随设备自动旋转,需要游戏自身能支持横竖屏。

如前所述,打开动态页面后别忘了清除动态页面入口处的小红点。

动态页面的背景图可以配置,步骤如下图所示。 背景图需要人工审核后才能生效,请预留充足的时间。

场景化入口

开发者可以结合游戏场景绘制入口,玩家打开入口跳转到指定的页面。使用前需要在开发者中心后台完成场景化入口配置

using TapSDK.Moment;

// sceneId 为在开发者中心后台创建场景化入口后生成的「入口 ID」
TapTapMoment.OpenScene(sceneId);

场景化入口回调格式说明

SDK 回调结构

字段名值类型required说明
sceneId字符串场景化入口 ID
eventType字符串枚举的事件类型,如 VIEW,FORWARD,VOTE 等
eventPayload字符串根据类型自定义的 JSON 字符串
timestamp整数unix 时间戳,ms

事件类型

eventTypeeventPayload (未序列化)说明
READY{}场景化页面已打开
REPOST{}转发,仅帖子本身
VOTE{ isCancel: boolean }点赞(含是否取消),仅帖子本身
FOLLOW{ isCancel: boolean }关注(含是否取消),仅帖子本身
COMMENT{}评论,仅帖子本身

关闭动态页面

玩家可以在动态页面主动退出,但在特定场景下,游戏可能需要主动关闭动态页面。

比如,玩家排位等待结束,准备进入对局时提示玩家关闭动态页面,玩家确认后关闭,此时调用如下接口:

using TapSDK.Moment;

TapTapMoment.CloseWithTitle("提示", "匹配成功,进入游戏");

接口中第一个参数为确认弹窗中的标题,第二个参数为确认弹窗中的内容。

用户的选择会通过回调返回:

  • CALLBACK_CODE_CLOSE_CANCEL(50000),表示玩家点了「取消」,选择不关闭动态页面。
  • CALLBACK_CODE_CLOSE_CONFIRM(50100),表示玩家点了「确认」,选择关闭动态页面。

如果需要直接关闭动态窗口,不弹出二次确认框,调用如下接口:

using TapSDK.Moment;

TapTapMoment.Close();

一键发布

信息

这是可选功能,请根据项目需求决定是否在游戏中加入这一功能。

我们推荐游戏让玩家直接在动态页面发布新动态。 不过,SDK 也提供了发布图文动态的 API,以支持「一键发动态」等需求。 图文动态包括单张或多张图片及相应的文字内容。

using TapSDK.Moment;

PublishMetaData publishMetaData = new PublishMetaData(content: "动态文字内容", imagePaths: new List<string> { "file://..." });
TapTapMoment.Publish(publishMetaData)
信息

玩家在动态页面可以发布图文动态和视频动态。 「一键发布」只支持发布图文动态。

国际化

内嵌动态支持设置语言:

TapTapSDK.UpdateLanguage(TapTapLanguageType.Auto);

支持如下语言:

namespace TapSDK.Core
{
public enum TapTapLanguageType
{
Auto = 0,// 自动
zh_Hans,// 简体中文
en,// 英文
zh_Hant,// 繁体中文
ja,// 日文
ko,// 韩文
th,// 泰文
id,// 印度尼西亚语
de,// 德语
es,// 西班牙语
fr,// 法语
pt,// 葡萄牙语
ru,// 俄罗斯语
tr,// 土耳其语
vi// 越南语
}
}

「自动」会尝试根据系统语言设置语言,如果系统语言不在上述支持的语言之中,那么会根据 SDK 初始化时配置的区域设置语言。 区域为中国大陆时会设置为简体中文,否则会设置为英文。