安卓接入文档

开发环境配置

工程环境配置

  • 开发环境: Android Studio 已安装且最新版本下开发;
  • 系统版本: minSdkVersion 设置>=17 ( 即Android 4.2版本 或者 更高);
  • target版本: targetSdkVersion=28(SDK目前没有做更高版本的适配);
  • apk版本: versioncode versionname必须设置;
  • 参数准备:SDK需要通过预设参数与各个渠道进行校验。为了保证功能正常,请提前准备好相关参数,参考下文配置项进行配置。

申请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 

录屏开始回调,回调接口
  • onPrepareResult(result,error) 启动录屏时的结果回调:
    • result:布尔型,是否启动成功
    • error: int型,错误码
  • onResult(unionReplayResult)  录屏终止后的结果回调
    • unionReplayResult :UnionReplayResult 类型,录制结果
接口返回值
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");
诚邀您对本文档易读易用性进行评价
好用
不好用