安卓接入文档
开发环境配置
工程环境配置
- 开发环境: Android Studio 已安装且最新版本下开发;
- 系统版本: minSdkVersion 设置>=17 ( 即Android 4.2版本 或者 更高);
- target版本: targetSdkVersion=28(SDK目前没有做更高版本的适配);
- apk版本: versioncode versionname必须设置;
- 参数准备:SDK需要通过预设参数与各个渠道进行校验。为了保证功能正常,请提前准备好相关参数,参考下文配置项进行配置。
申请Appid
- 注册账号:https://game.open.douyin.com/platform/product_list
- 提供资质信息,通过资质审核
- 创建/认领游戏,生成APPID
开放平台运营支持@费东旭 feidongxu@bytedance.com
联调对接技术支持@田智 tianzhi.jszc@bytedance.com
下载demo工程&SDK
若CP选择以Unity接入aar的方式接入,可参考开放平台-Unity接入aar包方式说明
除此之外我们还是优先推荐以远程依赖的方式进行接入
gradle 配置
- 仓库配置
buildscript {
repositories {
// 头条JFrog Maven仓库,远程依赖的方式需要导入
maven {
url 'https://artifact.bytedance.com/repository/ttgamesdk/'
}
...
mavenCentral()
google()
...
}
dependencies {
...
classpath 'com.android.tools.build:gradle:3.3.2' //打包必须依赖的gradle版本
...
}
}
allprojects {
repositories {
mavenCentral()
google()
maven {
url 'https://artifact.bytedance.com/repository/ttgamesdk/'
}
}
}
- 依赖配置
android {
...
compileSdkVersion 28
defaultConfig {
targetSdkVersion 28
multiDexEnabled true
//埋点数据实时验证功能,如果不需要可以填其他值,比如应用包名,详见以下文档:https://datarangers.com.cn/help/doc?lid=2230&did=45237
manifestPlaceholders.put("APPLOG_SCHEME", "union_game")
}
packagingOptions {
pickFirst 'okhttp3/internal/publicsuffix/publicsuffixes.gz'
pickFirst '**/libc++_shared.so'
pickFirst '**/libweibosdkcore.so'
}
}
dependencies {
...
implementation 'com.android.support:multidex:1.0.3' //需要支持multidex
// 必选接入
implementation 'com.bytedance.ttgame:gbsdk_common_host:${version}'
implementation 'com.bytedance.ttgame:gbsdk_common_plugin:${version}'
implementation 'com.bytedance.ttgame:gbsdk_optional_applog:${version}'
// 可选功能模块
implementation 'com.bytedance.ttgame:gbsdk_optional_anchor:${version}' // 抖音锚点
implementation 'com.bytedance.ttgame:gbsdk_optional_aweme:${version}' // 抖音
implementation 'com.bytedance.ttgame:gbsdk_optional_screenrecord:${version}' // 录屏
implementation 'com.bytedance.ttgame:gbsdk_optional_player_plugin:${version}' // 播放器
implementation 'com.bytedance.ttgame:gbsdk_optional_share_plugin:${version}' // 分享模块
implementation 'com.bytedance.ttgame:gbsdk_optional_videoeditor_plugin:${version}' // 编辑模块
}
备注:默认推荐以插件的方式接入,需要使用非插件方式,请在对接群反馈
Tips:上述版本使用了android support依赖库,如果游戏使用了androidx相关依赖库,且希望以插件形式接入,则需要改用下面的依赖:(版本号:2.0.3.1)
dependencies {
...
implementation 'com.android.support:multidex:1.0.3' //需要支持multidex
// 必选接入
implementation 'com.bytedance.ttgame:gbsdk_common_host:${version}'
implementation 'com.bytedance.ttgame:gbsdk_common_plugin_androidx:${version}'
implementation 'com.bytedance.ttgame:gbsdk_optional_applog:${version}'
// 可选功能模块
implementation 'com.bytedance.ttgame:gbsdk_optional_anchor:${version}' // 抖音锚点
implementation 'com.bytedance.ttgame:gbsdk_optional_aweme:${version}' // 抖音
implementation 'com.bytedance.ttgame:gbsdk_optional_screenrecord:${version}' // 录屏
implementation 'com.bytedance.ttgame:gbsdk_optional_player_plugin_androidx:${version}' // 播放器
implementation 'com.bytedance.ttgame:gbsdk_optional_share_plugin_androidx:${version}' // 分享模块
implementation 'com.bytedance.ttgame:gbsdk_optional_videoeditor_plugin_androidx:${version}' // 编辑模块
}
如果使用了androidx相关依赖库,需要在gradle.properties
添加下面的语句:(注:android不需要添加)
android.useAndroidX=true
android.enableJetifier=true
参数配置
- 需要在src/main/assets目录下添加config.json文件(参考demo),config.json里需要配置特定的参数:
{
"app_id": "180127",
"screen_orientation": "sensorLandscape",
"client_key": {
"douyin_key": "awtfacftffq79enj"
}
}
- 参数说明
参数名 | 字段类型 | 是否必填 | 字段说明 |
app_id | String | 必填 | 每个游戏在开放平台申请的appid,唯一标识 |
screen_orientation | String | 必填 | 屏幕方向,sensorPortrait为竖屏,sensorLandscape为横屏 |
client_key | String | 否 | 不同第三方平台所需要的clientKey |
douyin_key | String | 否 | 抖音key参数,需要在抖音开放平台申请,可用于抖音分享和授权 |
SDK初始化
功能介绍
SDK所有的功能必须要在初始化之后才能正常使用。
功能接入
游戏Application的继承GBApplication,如下:
public class XXApplication extends GBApplication {
//...
}
如果不能继承GBApplication,则需要在Application的attachBaseContext和onCreate函数中实现以下方法
@Override
protected void attachBaseContext(Context base) {
super.attachBaseContext(base);
GBCommonSDK.attachBaseContext(base);
}
@Override
public void onCreate() {
super.onCreate();
GBCommonSDK.onCreate(this);
}
初始化接口
接口说明
GBCommonSDK.init(activity, initCallback)
在MainActivity的onCreate()方法里,调用该接口进行SDK初始化。
参数以及回调结果说明
变量名 | 字段类型 | 字段说明 |
activity | Activity | |
initCallback | InitCallback | 初始化回调 onSuccess:成功 onFailed:失败 |
code | int | 错误码 |
msg | String | 错误信息 |
代码示例
调用示例如下:
GBCommonSDK.init(activity, new InitCallback() {
@Override
public void onSuccess() {
Toast.makeText(activity, "初始化成功", Toast.LENGTH_SHORT).show();
}
@Override
public void onFailed(int code, String msg) {
Toast.makeText(activity, "初始化失败: " + code + ", " + msg, Toast.LENGTH_SHORT).show();
}
});
注:
1.由于网络问题引起的初始化失败,可以暂不做处理,下次会在有网络时自动重试。
2.多线程的情况下,需要在主线程上init。
设置游戏画面Activity接口
接口说明
GBCommonSDK.setGameActivity(activity)
在游戏Activity的onCreate方法里面,必须调用以下方法,否则录屏初始化会失败:
/**
* 设置实际运行游戏画面的Activity,请务必配置正确,否则可能影响录屏悬浮球等功能的使用
* @param activity 实际运行游戏画面的Activity
*/
GBCommonSDK.setGameActivity(activity);
错误码
错误码 | 错误说明 | 处理方式 |
ERROR_INIT = -3 | 初始化异常 |
抖音分享+锚点
功能介绍
通过该功能,可以将游戏录制视频分享到抖音平台上。
功能接入
引入“抖音分享”+“锚点”可选功能模块。需要在抖音开放平台申请client_key,配置在config.json中。其中“锚点”功能,需将client_key绑定游戏ID,参考文档操作:抖音分享绑定游戏锚点指南
implementation 'com.bytedance.ttgame:gbsdk_optional_aweme:${version}' // 抖音
implementation 'com.bytedance.ttgame:gbsdk_optional_share_plugin:${version}' // 分享模块
implementation 'com.bytedance.ttgame:gbsdk_optional_anchor:${version}' // 抖音锚点
分享接口
接口声明
GBCommonSDK.getService(IShareService.class).share(activity, shareModel)
该接口可分享视频到抖音平台
参数及回调接口说明
变量名 | 字段类型 | 字段说明 |
activity | Activity | |
shareModel | TTShareModel | 分享模型 |
接口返回值 | int | 0 : 代表接口可用 1: 代表接口不可用 针对接口不可用场景,cp需要自行适配 |
TTShareModel 参数说明
变量名 | 字段类型 | 字段说明 |
mShareType | TTShareItemType | 分享渠道,如:抖音、抖音好友 |
mShareContentType | TTShareContentType | 分享内容类型,如:视频分享、图片分享、链接分享 |
mVideoUrl | String | 视频本地路径 |
mImageUrl | String | 图片本地链接 |
mTitle | String | 标题 |
mLinkUrl | String | 链接路径 |
mHashTagList | ArrayList<String> | 分享话题,适用于抖音分享 |
mMicroAppInfo | TTDYMicroAppInfo | 小程序,适用于抖音分享 |
mState | String | 可传入shareId 或者自定义值 |
shareToPublish | Boolean | 是否跳过编辑页,直接分享,适用于抖音分享 |
mEventCallBack | TTShareEventCallback | 分享结果回调 TTShareResult |
TTShareResult
变量名 | 字段类型 | 字段说明 |
errorCode | int | 错误码 |
subErrorCode | int | 二级错误码 |
errorMsg | String | 错误信息 |
代码示例
// 抖音视频分享
TTShareModel shareModel = new TTShareModel.Builder()
.setVideoUrl(videoPath)
.setShareType(TTShareItemType.DY)
.setShareContentType(TTShareContentType.VIDEO)
.setEventCallBack(
new TTShareEventCallback.BaseEmptyShareEventCallBack() {
@Override
public void onShareResultEvent(TTShareResult ttShareResult) {
Toast.makeText(activity,ttShareResult.toString(),Toast.LENGTH_LONG).show();
}
}).build();
GBCommonSDK.getService(IShareService.class).share(activity, shareModel);
// 抖音(抖音好友)图片分享
TTShareModel model = new TTShareModel.Builder()
.setImageUrl(url)
.setShareType(shareItemType) // 分享类型,抖音或者抖音好友
.setShareContentType(TTShareContentType.IMAGE)
.setEventCallBack(new TTShareEventCallback() {
@Override
public void onShareResultEvent(TTShareResult result) {
handleShareResult(activity, result);
}
})
.build();
GBCommonSDK.getService(IShareService.class).share(activity, model);
// 抖音好友链接分享
TTShareModel model = new TTShareModel.Builder()
.setTitle(title)
.setLinkUrl(link)
.setImageUrl(imageUrl)
.setShareType(TTShareItemType.DY_IM)
.setShareContentType(TTShareContentType.H5)
.setEventCallBack(new TTShareEventCallback() {
@Override
public void onShareResultEvent(TTShareResult result) {
handleShareResult(activity, result);
}
})
.build();
GBCommonSDK.getService(IShareService.class).share(activity, model);
错误码
errorCode:
错误码 | 错误说明 | 错误码适用范围 | 处理方式 |
0 | 正常 | 抖音分享 | |
-1 | 未知错误 | 抖音分享 | |
-2 | 用户手动取消 | 抖音分享 | |
-3 | 发送失败 | 抖音分享 | |
-4 | 第三方为获取分享权限或获取权限失败 | 抖音分享 | |
-5 | 文件解析错误 | 抖音分享 | |
-6 | 抖音未安装 | 抖音分享、抖音好友分享 | |
20000 | 分享成功 | 抖音好友分享 | |
20001 | 未知错误 | 抖音好友分享 | |
20003 | 无分享权限(检测一下你的包名和client key是否对应,或有无申请该权限) | 抖音好友分享 | |
20004 | 用户手动取消登录 | 抖音好友分享 | |
20005 | 用户未授权使用相册 | 抖音好友分享 | |
20006 | 网络问题 | 抖音好友分享 | |
20008 | 图片个数不符合要求或分享图片路径不符合要求 | 抖音好友分享 | |
20013 | 用户手动取消发布 | 抖音好友分享 | |
20017 | 无效url | 抖音好友分享 |
subErrorCode(仅适用于抖音分享):
错误码 | 错误说明 | 处理方式 |
20002 | 无效请求参数 | |
20003 | 授权失败/无权限 或者应用包名与官网填写不对应 | |
20004 | 用户手动取消登录 | |
20005 | 用户未授权使用相册 | |
20006 | 请求授权时网络出错 | |
20007 | 视频不支持 | |
20008 | 分享图文不支持 | |
200010 | 解析媒体资源失败,包含图片,视频 或者正在发布另一次分享 | |
200011 | 视频尺寸或比例不支持 | |
200012 | 视频格式不支持(要求mp4) | |
200013 | 用户手动取消发布 | |
200015 | 用户存为草稿 | |
22001 | 不支持的分辨率 android 独有 |
录屏功能(Android5.0及以上)
功能介绍
录屏功能接入后,用户可在“录屏设置”界面打开“自由录屏”,首页出现悬浮球,点击即可完成游戏录屏,录制结果在“我的视频”可查看。录屏主要分为系统录屏和内录,区别在于:1、内录只会录制游戏的本身内容,不会录制状态栏、浮球等游戏外内容;2、内录才能录制游戏音频。(建议cp优先接入内录)。
1.0.1.0版本新增自动录屏功能。录屏设置界面提供自动录屏开关。SDK内部提供开始录屏、结束录屏、展示保存弹窗、隐藏保存弹窗、保存、视频查看等接口,支持cp可以自定义自动录屏开始、结束、保存、查看等场景。默认策略:开启自动录屏后,cp需要在游戏开始时插入“开始录屏”,在游戏结束时,插入“结束录制”接口,最后可在游戏结算页展示保存弹窗,根据用户选择是否保存视频。
功能接入
需要引入“录屏”,“播放器”模块,为了录制后可以编辑视频,分享抖音等,建议同时引入“抖音”、“分享”、“锚点,编辑”可选功能模块。
implementation 'com.bytedance.ttgame:gbsdk_optional_screenrecord: ${version}' // 录屏
implementation 'com.bytedance.ttgame:gbsdk_optional_player_plugin: ${version}' // 播放器
implementation 'com.bytedance.ttgame:gbsdk_optional_aweme:${version}' // 抖音
implementation 'com.bytedance.ttgame:gbsdk_optional_share_plugin:${version}' // 分享模块
implementation 'com.bytedance.ttgame:gbsdk_optional_anchor:${version}' // 抖音锚点
implementation 'com.bytedance.ttgame:gbsdk_optional_videoeditor_plugin:${version}' // 编辑模块
内录仅适用于unity游戏,接入内录需要游戏接入以下插件,内录当前只支持OpenGLES渲染方式
不支持在 Docs 外粘贴 block
录屏初始化接口
接口声明
GBCommonSDK.getService(IScreenRecordService.class).initScreenRecord(unionVideoEngineType, unionAudioEngineType)
在游戏Activity的onCreate方法里面调用该方法。
参数及回调接口说明
变量名 | 字段类型 | 字段说明 |
unionVideoEngineType | UnionVideoEngineType | 视频类型: DEFAULT: 系统录屏 UNITY:内录 |
unionAudioEngineType | UnionAudioEngineType | 音频类型: DEFAULT: 无声音 UNITY:unity 原生 |
接口返回值 | int | 0 : 代表接口可用 1: 代表接口不可用 针对接口不可用场景,cp需要自行适配 |
代码示例
//初始化系统录屏和内录二选一,具体看CP接入哪种录屏模式
// 初始化系统录屏
GBCommonSDK.getService(IScreenRecordService.class)
.initScreenRecord(UnionVideoEngineType.DEFAULT, UnionAudioEngineType.DEFAULT);
// 初始化内录
GBCommonSDK.getService(IScreenRecordService.class)
.initScreenRecord(UnionVideoEngineType.UNITY, UnionAudioEngineType.UNITY);
打开录屏设置接口
接口声明
GBCommonSDK.getService(IScreenRecordService.class).openSRSettingPage(activity)
通过该接口打开录屏设置页面
参数及回调接口说明
变量名 | 字段类型 | 字段说明 |
activity | Activity | |
接口返回值 | int | 0 : 代表接口可用 1: 代表接口不可用 针对接口不可用场景,cp需要自行适配 |
代码示例
GBCommonSDK.getService(IScreenRecordService.class).openSRSettingPage(activity)
开始录制接口
接口声明
GBCommonSDK.getService(IScreenRecordService.class).startRecord(unionReplayCallback)
通过该接口开始自动录制
参数及回调接口说明
变量名 | 字段类型 | 字段说明 |
unionReplayCallback | UnionReplayCallback | 录屏开始回调,回调接口
|
接口返回值 | int | 0 : 代表接口可用 1: 代表接口不可用 针对接口不可用场景,cp需要自行适配 |
UnionReplayResult 参数说明:
变量名 | 字段类型 | 字段说明 |
success | int | 是否成功 0 成功 非0失败 |
error | int | 错误码 |
errorMsg | String | 错误码信息 |
videoPath | String | 视频文件路径 |
错误码信息:
错误码 | 错误说明 | 处理方式 |
0 | 成功 | |
1 | 录制过程中,用户离开了游戏界面 | |
2 | 录制错误,大概率系统原因 | |
3 | 自动录屏开关未打开 | 录屏设置页,打开录屏 |
4 | 用户拒绝录屏权限 | |
5 | 已经在录制 | |
6 | 设备不支持录制功能 | |
7 | 设备空间不足 | |
8 | 录制超过1小时,当前只满足最长一小时录制,超过一小时会自动结束录制 | |
999 | 其他错误 |
代码示例
GBCommonSDK.getService(IScreenRecordService.class).startRecord(new UnionReplayCallback() {
@Override
public void onPrepareResult(Boolean result, int error) {
Toast.makeText(ScreenRecordActivity.this,"error:"+error,Toast.LENGTH_LONG).show();
}
@Override
public void onResult(UnionReplayResult result) {
Toast.makeText(ScreenRecordActivity.this,"result:"+result.toString(),Toast.LENGTH_LONG).show();
}
});
结束录制接口
接口声明
GBCommonSDK.getService(IScreenRecordService.class).stopRecord()
通过该接口结束录制
参数及回调接口说明
变量名 | 字段类型 | 字段说明 |
接口返回值 | int | 0 : 代表接口可用 1: 代表接口不可用 针对接口不可用场景,cp需要自行适配 |
代码示例
GBCommonSDK.getService(IScreenRecordService.class).stopRecord()
展示保存录制浮窗接口
接口声明
GBCommonSDK.getService(IScreenRecordService.class).showSaveWindow(activity,marginBottom,marginEnd)
通过该接口展示保存视频弹窗
参数及回调接口说明
变量名 | 字段类型 | 字段说明 |
activity | Activity | |
marginBottom | int | 根据该参数,可自定义调节窗体位置,默认 0 |
marginEnd | int | 根据该参数,可自定义调节窗体位置,默认 0 |
接口返回值 | int | 0 : 代表接口可用 1: 代表接口不可用 针对接口不可用场景,cp需要自行适配 |
代码示例
GBCommonSDK.getService(IScreenRecordService.class).showSaveWindow(activity, 0, 0);
隐藏保存浮窗接口
接口声明
GBCommonSDK.getService(IScreenRecordService.class).hideSaveWindow()
通过该接口隐藏保存弹窗
参数及回调接口说明
变量名 | 字段类型 | 字段说明 |
接口返回值 | int | 0 : 代表接口可用 1: 代表接口不可用 针对接口不可用场景,cp需要自行适配 |
代码示例
GBCommonSDK.getService(IScreenRecordService.class).hideSaveWindow()
保存自动录屏结果接口
接口声明
GBCommonSDK.getService(IScreenRecordService.class).saveRecordResult(activity,saveCallback)
通过该接口,可以自定义自动录屏的保存逻辑
参数及回调接口说明
变量名 | 字段类型 | 字段说明 |
activity | Activity | |
saveCallback | UnionSaveCallback | 保存结果回调 errorCode:0 成功,1 失败,2 正在录制中 |
接口返回值 | int | 0 : 代表接口可用 1: 代表接口不可用 针对接口不可用场景,cp需要自行适配 |
代码示例
GBCommonSDK.getService(IScreenRecordService.class).saveRecordResult(this, new UnionSaveCallback() {
@Override
public void saveResult(int code, String s) {
//code为错误码,s为错误message
Toast.makeText(ScreenRecordActivity.this, "errorCode:" + code + " " + s, Toast.LENGTH_LONG).show();
}
});
查看录制视频接口
接口声明
GBCommonSDK.getService(IScreenRecordService.class).openVideosPage(activity)
通过该接口可以直接打开视频页
参数及回调接口说明
变量名 | 字段类型 | 字段说明 |
activity | Activity | |
接口返回值 | int | 0 : 代表接口可用 1: 代表接口不可用 针对接口不可用场景,cp需要自行适配 |
代码示例
GBCommonSDK.getService(IScreenRecordService.class).openVideosPage(activity)
视频编辑接口
接口声明
GBCommonSDK.getService(IVideoEditorService.class).startVideoEditor(context,videoPath,savePath,enterForm)
通过该接口可以直接打开编辑页面,需要进入“视频编辑”模块
参数及回调接口说明
变量名 | 字段类型 | 字段说明 |
context | Context | 上下文 |
videoPath | String | 需要编辑的视频路径 |
savePath | String | 编辑后保存路径 |
enterForm | String | 进入来源,用于埋点,可以任意写,默认为进入时所在的Activity名称 |
代码示例
GBCommonSDK.getService(IVideoEditorService.class).startVideoEditor(this, path, this.getExternalFilesDir(Environment.DIRECTORY_DCIM) + "/g_screen_records_editor", "VideoEditorActivity");