内嵌动态开发指南
本文介绍如何在游戏中接入 TapTap 内嵌动态功能,使用内嵌动态功能需依赖 TapTap 登录。
权限说明
- Unity
- Android Java
- Android Kotlin
- iOS
该模块需要如下权限:
权限 | 使用目的 | 权限申请时机 |
---|---|---|
网络权限 | 用于访问网络数据 | 用户首次使用该功能时会申请权限 |
获取网络状态 | 用于检测当前网络连接是否有效 | 用户首次使用该功能时会申请权限 |
读写存储权限 | 用于发布或下载动态页面内图片、视频 | 下载或使用本地图片发布动态时申请 |
该模块将在应用中添加如下权限:
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"
tools:ignore="ScopedStorage" />
<uses-permission android:name="android.permission.READ_MEDIA_IMAGES"/>
<uses-permission android:name="android.permission.READ_MEDIA_VIDEO"/>
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
该模块需要如下权限:
权限 | 使用目的 | 权限申请时机 |
---|---|---|
网络权限 | 用于访问网络数据 | 用户首次使用该功能时会申请权限 |
获取网络状态 | 用于检测当前网络连接是否有效 | 用户首次使用该功能时会申请权限 |
读写存储权限 | 用于发布或下载动态页面内图片、视频 | 下载或使用本地图片发布动态时申请 |
该模块将在应用中添加如下权限:
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"
tools:ignore="ScopedStorage" />
<uses-permission android:name="android.permission.READ_MEDIA_IMAGES"/>
<uses-permission android:name="android.permission.READ_MEDIA_VIDEO"/>
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
使用内嵌动态服务需要相册、相机权限,所以开发者需在工程的 info.plist
配置相关权限并替换授权文案:
<!--使用内嵌动态服务,需要相册、相机、麦克风权限-->
<key>NSPhotoLibraryUsageDescription</key>
<string>说明为何应用需要此项权限</string>
<key>NSCameraUsageDescription</key>
<string>说明为何应用需要此项权限</string>
<key>NSMicrophoneUsageDescription</key>
<string>说明为何应用需要此项权限</string>
集成前准备
- 参考 准备工作 创建应用、开启内嵌动态应用配置;
- 内嵌动态依赖于 TapTap 登录模块,开发者接入前应先接入 TapTap 登录 相关依赖。
SDK 获取
完成 SDK 获取,然后在此基础上可以通过 下载 获得 TapSDK,添加 TapMoment
模块:
- Unity
- Android Java
- Android Kotlin
- iOS
接入外部依赖
SDK 内部使用了部分第三方库,开发者接入时需先确保 SDK 外部依赖库已正常接入,具体设置如下:
- SDK 使用的 JSON 解析库为
Newtonsoft-json
,如果当前工程已接入该依赖库,则不需额外处理,否则需在Packages/manifest.json
添加如下依赖:
"com.unity.nuget.newtonsoft-json":"3.2.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.json
中 dependencies
同级下声明 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 可查看已经安装在项目中的包。
本地文件导入
在 下载页 下载下列模块对应
unitypackage
文件,并在 Unity 项目中依次通过 Assets > Import Packages > Custom Packages 进行导入,包括:TapTapSDK_Core.unitypackage
TapTapSDK 核心模块,必选。TapTapSDK_Login.unitypackage
TapTapSDK 登录模块,必选。TapTapSDK_Moment.unitypackage
TapTapSDK 内嵌动态模块,必选。
如果当前项目已集成
Newtonsoft.Json
依赖,则忽略该步骤,否则在NuGet.org
Newtonsoft.Json 页面中通过点击右侧 「Download package」 下载库文件,并将下载的文件后缀从.nupkg
修改为.zip
,同时解压该文件并复制内部的Newtonsoft.Json.dll
文件拷贝到工程Assets
的Plugins
目录下,另外为了避免导出 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>
allprojects {
repositories {
google()
mavenCentral()
}
}
- app module 的 build.gradle 添加对应依赖:
内嵌动态模块依赖于 TapLogin
, 需额外添加 TapLogin
模块依赖。
dependencies {
implementation 'com.taptap.sdk:tap-core:4.5.0'
implementation 'com.taptap.sdk:tap-moment:4.5.0'
// 内嵌动态依赖登录模块
implementation 'com.taptap.sdk:tap-login:4.5.0'
}
allprojects {
repositories {
google()
mavenCentral()
}
}
- app module 的 build.gradle 添加对应依赖:
内嵌动态模块依赖于 TapLogin
, 需额外添加 TapLogin
模块依赖。
dependencies {
implementation 'com.taptap.sdk:tap-core:4.5.0'
implementation 'com.taptap.sdk:tap-login:4.5.0'
implementation 'com.taptap.sdk:tap-moment:4.5.0'
}
iOS 提供通过添加 cocoaPods 远程依赖和使用本地文件导入两种集成方式,推荐使用远程依赖方式。
远程依赖
- 在工程 Podfile 文件中对应模块下添加依赖:
pod 'TapTapMomentSDK', '~> 4.5.0'
- 执行
Pod install
下载对应依赖文件 - 将工程 Pods 目录下
TapTapMomentSDK/Frameworks/TapTapMomentResource.bundle
和TapTapLoginSDK/Frameworks/TapTapLoginResource.bundle
等资源文件导入工程中
本地文件依赖
动态模块依赖于初始化和 TapTap 登录模块,使用本地文件方式添加依赖时,需先参考 TapSDK 集成 和 TapTap 登录 添加对应本地文件依赖项。
- 在下载页下载如下文件:
TapTapMomentSDK.xcframework
动态依赖库TapTapMomentResource.bundle
动态资源文件
- 在工程中添加
framework
静态库,注意添加时选择 Embed 方式为 Do Not Embed,导入bundle
资源文件
SDK 初始化
- Unity
- Android Java
- Android Kotlin
- iOS
TapTapSdkOptions
详细参数见 入门指南#快速开始
using TapSDK.Core;
// 核心配置 详细参数见 [TapTapSDK]
TapTapSdkOptions coreOptions = new TapTapSdkOptions();
// TapSDK 初始化
TapTapSDK.Init(coreOptions);
TapTapSdkOptions
详细参数见 入门指南#快速开始
import com.taptap.sdk.core.TapTapRegion;
import com.taptap.sdk.core.TapTapSdk;
import com.taptap.sdk.core.TapTapSdkOptions;
/* 必选配置 */
// 开发者中心对应 Client ID
String clientId = "";
// 开发者中心对应 Client Token
String clientToken = "";
// 是否开启 log,建议 Debug 开启,Release 关闭,默认关闭 log
boolean enableLog = BuildConfig.DEBUG;
TapTapSdkOptions tapSdkOptions = new TapTapSdkOptions(
clientId, // 游戏 Client ID
clientToken, // 游戏 Client Token
TapTapRegion.CN // 游戏可玩区域: [TapTapRegion.CN]=国内 [TapTapRegion.GLOBAL]=海外
);
tapSdkOptions.setEnableLog(enableLog);
// 初始化 TapSDK
TapTapSdk.init(context, tapSdkOptions);
TapTapSdkOptions
详细参数见 入门指南#快速开始
import com.taptap.sdk.core.TapTapSdk
import com.taptap.sdk.core.TapTapSdkOptions
import com.taptap.sdk.core.TapTapRegion
import com.taptap.sdk.core.TapTapLanguage
TapTapSdk.init(
context = context,
sdkOptions = TapTapSdkOptions(
clientId = clientId,
clientToken = clientToken,
region = TapTapRegion.CN,
preferredLanguage = TapTapLanguage.ZH_HANS,
enableLog = false
)
)
import TapTapCoreSDK
let options = TapTapSdkOptions()
options.clientId = "your_client_id" // 必须,开发者中心对应 Client ID
options.clientToken = "your_client_token" // 必须,开发者中心对应 Client Token
options.region = .CN // .CN:中国大陆,.overseas:其他国家或地区
options.enableLog = enableLog.selectedSegmentIndex == 0 // 是否开启 log,建议 Debug 开启,Release 关闭,默认关闭 log
options.preferredLanguage = TapLanguageType.auto // 语言设置,默认跟随系统,当系统语言不支持时,国内为中文,海外为英文
// 初始化 SDK
TapTapSDK.initWith(options)
设置回调
设置回调以获取动态的状态变化。
- Unity
- Android Java
- Android Kotlin
- iOS
using TapSDK.Moment;
TapTapMoment.SetCallback((code, msg) =>
{
// 根据 code 处理动态事件
});
// 移除 callback
TapTapMoment.SetCallback(null);
import com.taptap.sdk.moment.TapTapMoment;
TapTapMoment.setCallback(new TapTapMoment.TapTapMomentCallback() {
@Override
public void onCallback(int code, @Nullable String msg) {
// 根据 code 处理事件
}
});
TapTapMoment.setCallback(null);
import com.taptap.sdk.moment.TapTapMoment
TapTapMoment.setCallback(
callback = object : TapTapMoment.TapTapMomentCallback {
override fun onCallback(code: Int, msg: String?) {
// 根据 code 处理事件
}
}
)
// 移除 callback
TapTapMoment.setCallback(null);
import TapTapMomentSDK
// 实现 TapTapMomentDelegate 协议
extension GameMainScene:TapTapMomentDelegate{
func onMomentCallback(withCode code: Int, msg: String) {
// 根据 code 处理动态事件
}
}
// 注册回调
TapTapMoment.setDelegate(self)
回调方法中 code 表示事件类型,现支持的回调类型如下:
回调 | 回调值 | 说明 |
---|---|---|
CALLBACK_CODE_PUBLISH_SUCCESS | 10000 | 动态发布成功 |
CALLBACK_CODE_PUBLISH_FAIL | 10100 | 动态发布失败 |
CALLBACK_CODE_PUBLISH_CANCEL | 10200 | 关闭动态发布页面 |
CALLBACK_CODE_GET_NOTICE_SUCCESS | 20000 | 获取新消息成功 |
CALLBACK_CODE_GET_NOTICE_FAIL | 20100 | 获取新消息失败 |
CALLBACK_CODE_MOMENT_APPEAR | 30000 | 动态页面打开 |
CALLBACK_CODE_MOMENT_DISAPPEAR | 30100 | 动态页面关闭 |
CALLBACK_CODE_CLOSE_CANCEL | 50000 | 取消关闭所有动态界面(弹框点击取消按钮) |
CALLBACK_CODE_CLOSE_CONFIRM | 50100 | 确认关闭所有动态界面(弹框点击确认按钮) |
CALLBACK_CODE_LOGIN_SUCCESS | 60000 | 动态页面内登录成功 |
CALLBACK_CODE_SCENE_EVENT | 70000 | 场景化入口回调 |
获取新消息
定时调用获取消息通知的接口,有新信息时可以在 TapTap 动态入口显示小红点,提醒玩家查看新动态。
- Unity
- Android Java
- Android Kotlin
- iOS
using TapSDK.Moment;
TapTapMoment.FetchNotification();
import com.taptap.sdk.moment.TapTapMoment;
TapTapMoment.fetchNotification();
import com.taptap.sdk.moment.TapTapMoment
TapTapMoment.fetchNotification()
import TapTapMomentSDK
TapTapMoment.fetchNotification()
获取消息通知的结果会在本文刚开始设置的回调中返回,code
为 CALLBACK_CODE_GET_NOTICE_SUCCESS
(20000
)表示获取成功,CALLBACK_CODE_GET_NOTICE_FAIL
(20100
)表示获取失败。
获取成功时,msg
为新消息数量,0
表示没有新消息。
为了方便玩家查看好友动态、游戏公告等,我们建议将 TapTap 动态入口放在显眼的位置,每分钟调用 1 次获取消息通知的接口。
获取消息通知时,如果没有新消息(msg
为 0
),那么游戏需要清除界面上的小红点。
同样,打开 TapTap 动态页面后,游戏也需要清除界面上的小红点。
显示动态页面
在游戏中显示 TapTap 动态页面,玩家可以查看及发布动态。
- Unity
- Android Java
- Android Kotlin
- iOS
using TapSDK.Moment;
TapTapMoment.open();
import com.taptap.sdk.moment.TapTapMoment;
TapTapMoment.open();
import com.taptap.sdk.moment.TapTapMoment
TapTapMoment.open()
import TapTapMomentSDK
TapTapMoment.open()
打开动态页面时,请先屏蔽游戏自身的声音,以免干扰动态内的视频声音。
如需要动态能支持横竖屏随设备自动旋转,需要游戏自身能支持横竖屏。
如前所述,打开动态页面后别忘了清除动态页面入口处的小红点。
动态页面的背景图可以配置,步骤如下图所示。 背景图需要人工审核后才能生效,请预留充足的时间。
场景化入口
开发者可以结合游戏场景绘制入口,玩家打开入口跳转到指定的页面。使用前需要在开发者中心后台完成场景化入口配置。
- Unity
- Android Java
- Android Kotlin
- iOS
using TapSDK.Moment;
// sceneId 为在开发者中心后台创建场景化入口后生成的「入口 ID」
TapTapMoment.OpenScene(sceneId);
import com.taptap.sdk.moment.TapTapMoment;
// sceneId 为在开发者中心后台创建场景化入口后生成的「入口 ID」
TapTapMoment.openScene(sceneId);
import com.taptap.sdk.moment.TapTapMoment
TapTapMoment.openScene(sceneId = sceneId)
import TapTapMomentSDK
// sceneId 为在开发者中心后台创建场景化入口后生成的「入口 ID」
TapTapMoment.openScene(sceneId)
场景化入口回调格式说明
SDK 回调结构
字段名 | 值类型 | required | 说明 |
---|---|---|---|
sceneId | 字符串 | 是 | 场景化入口 ID |
eventType | 字符串 | 是 | 枚举的事件类型,如 VIEW,FORWARD,VOTE 等 |
eventPayload | 字符串 | 是 | 根据类型自定义的 JSON 字符串 |
timestamp | 整数 | 是 | unix 时间戳,ms |
事件类型
eventType | eventPayload (未序列化) | 说明 |
---|---|---|
READY | {} | 场景化页面已打开 |
REPOST | {} | 转发,仅帖子本身 |
VOTE | { isCancel: boolean } | 点赞(含是否取消),仅帖子本身 |
FOLLOW | { isCancel: boolean } | 关注(含是否取消),仅帖子本身 |
COMMENT | {} | 评论,仅帖子本身 |
关闭动态页面
玩家可以在动态页面主动退出,但在特定场景下,游戏可能需要主动关闭动态页面。
比如,玩家排位等待结束,准备进入对局时提示玩家关闭动态页面,玩家确认后关闭,此时调用如下接口:
- Unity
- Android Java
- Android Kotlin
- iOS
using TapSDK.Moment;
TapTapMoment.CloseWithTitle("提示", "匹配成功,进入游戏");
import com.taptap.sdk.moment.TapTapMoment;
TapTapMoment.closeWithTitle("提示", "匹配成功,进入游戏");
import com.taptap.sdk.moment.TapTapMoment
TapTapMoment.closeWithTitle("提示", "匹配成功,进入游戏");
import TapTapMomentSDK
TapTapMoment.close(withTitle: "标题", content: "匹配成功,是否离开动态?", showConfirm: true)
接口中第一个参数为确认弹窗中的标题,第二个参数为确认弹窗中的内容。
用户的选择会通过回调返回:
CALLBACK_CODE_CLOSE_CANCEL
(50000),表示玩家点了「取消」,选择不关闭动态页面。CALLBACK_CODE_CLOSE_CONFIRM
(50100),表示玩家点了「确认」,选择关闭动态页面。
如果需要直接关闭动态窗口,不弹出二次确认框,调用如下接口:
- Unity
- Android Java
- Android Kotlin
- iOS
using TapSDK.Moment;
TapTapMoment.Close();
import com.taptap.sdk.moment.TapTapMoment;
TapTapMoment.close();
import com.taptap.sdk.moment.TapTapMoment
TapTapMoment.close()
import TapTapMomentSDK
TapTapMoment.close()
一键发布
这是可选功能,请根据项目需求决定是否在游戏中加入这一功能。
我们推荐游戏让玩家直接在动态页面发布新动态。 不过,SDK 也提供了发布图文动态的 API,以支持「一键发动态」等需求。 图文动态包括单张或多张图片及相应的文字内容。
- Unity
- Android Java
- Android Kotlin
- iOS
using TapSDK.Moment;
PublishMetaData publishMetaData = new PublishMetaData(content: "动态文字内容", imagePaths: new List<string> { "file://..." });
TapTapMoment.Publish(publishMetaData)
import com.taptap.sdk.moment.TapTapMoment;
import com.taptap.sdk.moment.model.PublishMetaData;
List<String> imagePaths = new ArrayList<>();
imagePaths.add("图片路径1");
imagePaths.add("图片路径2");
PublishMetaData publishMetaData = new PublishMetaData(
"动态文字内容",
new ArrayList<String>(),
imagePaths
);
TapTapMoment.publish(publishMetaData);
import com.taptap.sdk.moment.TapTapMoment
TapTapMoment.publish(
publishMetaData = PublishMetaData(
content = "content",
imagePaths = listOf(
"路径1",
"路径2",
"路径3"
)
)
)
import TapTapMomentSDK
// 初始化要发布的图文数据
let postData = TapTapMomentImageData()
// 设置发布的文字内容
postData.content = "动态文字内容"
// 设置发布的图片地址
let imagePath = "/var/mobile/**.png"
postData.images = [imagePath]
// 发布图文动态
TapTapMoment.publish(postData)
玩家在动态页面可以发布图文动态和视频动态。 「一键发布」只支持发布图文动态。
国际化
内嵌动态支持设置语言:
- Unity
- Android Java
- Android Kotlin
- iOS
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// 越南语
}
}
import com.taptap.sdk.core.TapTapLanguage;
import com.taptap.sdk.core.TapTapSdk;
TapTapSdk.setPreferredLanguage(TapTapLanguage.AUTO);
支持如下语言:
/**
* 自动
*/
AUTO("auto"),
/**
* 简体中文
*/
ZH_HANS("zh_CN"),
/**
* 英语(美国)
*/
EN("en_US"),
/**
* 繁体中文
*/
ZH_HANT("zh_TW"),
/**
* 日文
*/
JA("ja_JP"),
/**
* 韩文
*/
KO("ko_KR"),
/**
* 泰语
*/
TH("th_TH"),
/**
* 印尼语
*/
ID("id_ID"),
/**
* 德语
*/
DE("de"),
/**
* 西班牙语
*/
ES("es_ES"),
/**
* 法语
*/
FR("fr"),
/**
* 葡萄牙语
*/
PT("pt_PT"),
/**
* 俄语
*/
RU("ru"),
/**
* 土耳其语
*/
TR("tr"),
/**
* 越南语
*/
VI("vi_VN");
TapTapSdk.setPreferredLanguage(TapTapLanguage.AUTO)
支持如下语言:
/**
* 自动
*/
AUTO("auto"),
/**
* 简体中文
*/
ZH_HANS("zh_CN"),
/**
* 英语(美国)
*/
EN("en_US"),
/**
* 繁体中文
*/
ZH_HANT("zh_TW"),
/**
* 日文
*/
JA("ja_JP"),
/**
* 韩文
*/
KO("ko_KR"),
/**
* 泰语
*/
TH("th_TH"),
/**
* 印尼语
*/
ID("id_ID"),
/**
* 德语
*/
DE("de"),
/**
* 西班牙语
*/
ES("es_ES"),
/**
* 法语
*/
FR("fr"),
/**
* 葡萄牙语
*/
PT("pt_PT"),
/**
* 俄语
*/
RU("ru"),
/**
* 土耳其语
*/
TR("tr"),
/**
* 越南语
*/
VI("vi_VN");
TapTapSDK.update(TapLanguageType.auto)
支持如下语言:
typedef NS_ENUM (NSInteger, TapLanguageType) {
TapLanguageType_Auto = 0,// 自动
TapLanguageType_zh_Hans,// 简体中文
TapLanguageType_en,// 英文
TapLanguageType_zh_Hant,// 繁体中文
TapLanguageType_ja,// 日文
TapLanguageType_ko,// 韩文
TapLanguageType_th,// 泰文
TapLanguageType_id,// 印度尼西亚语
TapLanguageType_de,// 德语
TapLanguageType_es,// 西班牙语
TapLanguageType_fr,// 法语
TapLanguageType_pt,// 葡萄牙语
TapLanguageType_ru,// 俄罗斯语
TapLanguageType_tr,// 土耳其语
TapLanguageType_vi,// 越南语
};
「自动」会尝试根据系统语言设置语言,如果系统语言不在上述支持的语言之中,那么会根据 SDK 初始化时配置的区域设置语言。 区域为中国大陆时会设置为简体中文,否则会设置为英文。