跳到主要内容

AndroidStudio接入文档

1、简介

本文档主要介绍在AndroidStudio中如何集成和使用SDK,根据⽂档操作即可⾼效的完成SDK的接⼊,该文档仅供研发接入参考。

2、SDK快速接入

AndroidStudio Demo工程,仅供研发接入参考

2.1 SDK配置要求

  • minSdkVersion ≥ 21(Android 5.0 或更高版本)
  • Java 8或更高版本
  • AndroidX 支持

2.2 SDK导入

  • 在项目级别的build.gradle配置文件中添加如下代码:
buildscript {
repositories {
//Firebase需要,如果不使用Firebase,则忽略下面配置
google()
}
dependencies {
classpath 'com.android.tools.build:gradle:3.6.4'
//Firebase需要,如果不需要,则忽略下面配置
classpath 'com.google.gms:google-services:4.3.10'
}
}

allprojects {
repositories {
//Firebase需要,如果不使用Firebase,则忽略下面配置
google()
//Appsflyer需要,如果不需要,则忽略下面配置
mavenCentral()
//TOPSdk 仓库地址
maven { url 'https://storage-sdk-gameplus.meetsocial.com/repository/TopSdk/' }
//Snapchat 登录需要,如果不需要接入Snapchat登录,则忽略下面配置
maven { url 'https://storage.googleapis.com/snap-kit-build/maven' }
//kakao 登录需要,如果不需要接入kakao登录,则忽略下面配置
maven { url 'https://devrepo.kakao.com/nexus/content/groups/public/' }
//华为渠道配置
maven { url 'https://developer.huawei.com/repo/' }
//onestore渠道配置
maven { url 'https://repo.onestore.co.kr/repository/onestore-sdk-public/' }
}
}

as-1

  • 在模块级别的build.gradle配置文件中添加如下代码:
//Firebase需要,如果不使用Firebase,则忽略下面配置
apply plugin: 'com.google.gms.google-services'

//模块依赖
dependencies {
//x.x.x.x为SDK当前接入版本,如 1.5.0.6
def topsdk_version = "x.x.x.x"
def groupId = "com.sino.topsdk"
implementation "$groupId:ui:$topsdk_version"
//游客登录(可选)
implementation "$groupId:guest:$topsdk_version"
//Email登录(可选)
implementation "$groupId:email:$topsdk_version"
//facebook登录(可选)
implementation "$groupId:facebook:$topsdk_version"
//google登录(可选)
implementation "$groupId:google:$topsdk_version"
//twitter登录(可选)
implementation "$groupId:twitter:$topsdk_version"
//snapchat登录(可选)
implementation "$groupId:snapchat:$topsdk_version"
//line登录(可选)
implementation "$groupId:line:$topsdk_version"
//naver登录(可选)
implementation "$groupId:naver:$topsdk_version"
//kakao登录(可选)
implementation "$groupId:kakao:$topsdk_version"
//appsflyer (可选)
implementation "$groupId:appsflyer:$topsdk_version"
//firebase (可选)
implementation "$groupId:firebase:$topsdk_version"
//adjust (可选)
implementation "$groupId:adjust:$topsdk_version"
//facebook data 数据统计 (可选)
implementation "$groupId:facebook-data:$topsdk_version"
//google play 商店内购(可选)
implementation "$groupId:google-iap:$topsdk_version"
//onestore 商店内购(可选)
implementation "$groupId:onestore-iap:$topsdk_version"
//huawei 商店内购(可选)
implementation "$groupId:huawei-iap:$topsdk_version"
//xiaomi 商店内购(可选)
implementation "$groupId:xiaomi-iap:$topsdk_version"
}

//第三方平台配置(游戏按照接入的第三方加入配置并且填上对应的值,如果游戏没有的可以去掉对应第三方配置)
defaultConfig {
//channel(渠道标识,如果上架google play商店 请使用'GOOGLE',上架onestore请使用'ONESTORE')
resValue('string', 'top_channel_id', 'GOOGLE')
//facebook(可选)
resValue('string', 'facebook_app_id', '您申请的facebook登录平台的App ID')
resValue('string', 'fb_login_protocol_scheme', '您申请的facebook登录平台的fb_login_protocol_scheme')
resValue('string', 'facebook_client_token', '您申请的facebook登录平台的App secret')
//facebook_permission_enable_email这个属性主要是兼容旧版的FB应用,如果您这边FB申请应用是旧版的,并且需要TopSDK回调有邮箱,需要加一行属性如下:(新版本的FB应用不能加这个属性,否则会FB登录失败)
resValue('bool', 'facebook_permission_enable_email', "true")
//google(可选)
resValue('string', 'google_client_id', '您申请的google登录平台的server_client_id')
//twitter(可选)
resValue('string', 'twitter_client_id', '您申请的twitter登录平台的twitter_client_id')
resValue('string', 'twitter_client_secret', '您申请的twitter登录平台的twitter_client_secret')
resValue('string', 'twitter_redirect_url', 'twitter登录后重定向的URL')
//snapchat(可选)
resValue('string', 'snapchat_client_id', '您申请snapchat的client_id')
//snapchat(redirect_url="scheme://host/path"拆分为以下配置)(可选)
addManifestPlaceholders([snapchat_scheme: "scheme", snapchat_host: "host", snapchat_path: "path"])
//line(可选)
resValue('string', 'line_channel_id', '您申请line的channel_id')
//kakao(可选)
resValue('string', 'kakao_app_id', '您申请kakao的app_id')
resValue('string', 'kakao_scheme', '您申请kakao的scheme')
//naver(可选)
resValue('string', 'naver_client_id', '您申请naver的client_id')
resValue('string', 'naver_client_secret', '您申请naver的client_secret')
resValue('string', 'naver_client_name', '您申请naver的client_name')
//Appsflyer(可选)
resValue('bool', 'appsflyer_enable_debug_log', "true")//true开启本地log,flase关闭本地log,默认为flase
resValue('string', 'af_dev_key', '您申请AppsFlyer的af_dev_key')
//Adjust(可选)
resValue('bool', 'adjust_enable_sandbox', "true")//true开启沙盒环境,flase关闭沙盒环境,默认为flase
resValue('string', 'adjust_app_token', '您申请adjust的app_token')
//facebook data 数据统计 (可选)
resValue('string', 'facebook_data_app_id', "您申请的facebook登录平台的facebook_app_id")
resValue('string', 'facebook_data_client_token', '您申请的facebook平台的客户端token')
}

渠道标识top_channel_id取值

top_channel_id渠道标识
Google Play 商店GOOGLE
onestore 商店ONESTORE
Huawei 商店HUAWEI
Xiaomi 商店XIAOMI

as-2

  • 将Huawei Android 配置文件添加到您的应用(如果使用了huawei商店内购)

    Huawei AppGalleryConnect > 我的项目 > 项目设置 > 应用下找到 agconnect-services.json 配置文件并下载,将其添加到应用级模块,目录:Module模块 > src > main > assets

  • 将 Firebase Android 配置文件添加到您的应用(如果添加了Firebase依赖)

    Firebase 控制台将下载的 google-services.json 配置文件移动到应用级模块目录中

    as-4

  • 将 Adjust Android 配置文件添加到您的应用(如果添加了Adjust依赖)

    将下载的 topsdk_adjust_event.json 配置文件,复制到游戏工程assets目录下

    topsdk_adjust_event.json 文件获取方式请联系sdk提供方

    as-5

  • 在项目的gradle.properties配置文件中添加如下代码(启用AndroidX):

android.useAndroidX=true
android.enableJetifier=true

as-3

3、SDK回调函数使用说明

3.1 登录回调函数

//登录回调注册(在调用登录接口前先进行注册)
gameSDKManager.registerLoginCallback(callback);
//callback 登录回调
TOPCallback<TOPUserInfo> callback = new TOPCallback<TOPUserInfo>() {
@Override
public void onSuccess(TOPUserInfo userInfo) {
//String uid = userInfo.getId();//用户id
//String userName = userInfo.getName();//用户名
//String token = userInfo.getToken();//用户token
}

@Override
public void onFailed(ErrorResults errorResults) {
//登录失败 ErrorResults 错误信息,"code":错误码,"error":错误信息
}
};
//登录回调反注册(在页面销毁时进行反注册)
gameSDKManager.unregisterLoginCallback();

3.2 登出回调函数

//登出回调注册(需要监听登出回调的地方)
gameSDKManager.registerLogoutCallback(callback);
//callback 登出回调
TOPCallback<Boolean> callback = new TOPCallback<Boolean>() {
@Override
public void onSuccess(Boolean success) {
//登出成功
//游戏方进行后续操作(需要退出到登录页)
//游戏方进行后续操作(需要退出到登录页)
//游戏方进行后续操作(需要退出到登录页)
}

@Override
public void onFailed(ErrorResults errorResults) {
//登出失败 ErrorResults 错误信息
//游戏方进行后续操作
}
};
//登出回调反注册(在页面销毁时进行反注册)
gameSDKManager.unregisterLogoutCallback();

3.3 绑定账号回调函数

//绑定回调注册(需要监听绑定回调的地方)
gameSDKManager.registerBindStatusCallback(bindStatusCallback);
//callback 绑定回调
BindStatusCallback bindStatusCallback = new BindStatusCallback() {
@Override
public void onSuccess(PlatformType platformType, TOPBindData bindData) {
//PlatformType:平台类型
//bindStatus 0:未绑定/解绑 1:已绑定/绑定
int bindStatus = bindData.getBindStatus();
//平台信息
String platform = bindData.getPlatform();
}

@Override
public void onFailed(PlatformType platformType, ErrorResults errorResults) {
//PlatformType:平台类型
//失败 ErrorResults 错误信息
}
//绑定回调反注册(在页面销毁时进行反注册)
gameSDKManager.unregisterBindStatusCallback();

3.4 用户中心返回关闭回调函数

//用户中心返回关闭回调注册(需要监听用户中心返回关闭回调的地方)
gameSDKManager.registerUserCenterCloseCallback(callback);
//callback 用户中心返回关闭回调
TOPCallback<Boolean> callback = new TOPCallback<Boolean>() {
@Override
public void onSuccess(Boolean success) {
//用户中心返回关闭
}

@Override
public void onFailed(ErrorResults errorResults) {
//这里不用处理,用户中心返回关闭回调不会失败
}
};
//用户中心返回关闭回调反注册(在页面销毁时进行反注册)
gameSDKManager.unregisterUserCenterCloseCallback();

4、SDK接口使用说明

4.1 SDK全局单例获取接口

TOPSdkManager gameSDKManager = TOPSdkManager.getInstance();

本SDK基于单例模式设计,必须使⽤该接⼝来获取SDK的唯⼀实例,才能正常使⽤SDK。后续接⼝都必须通过单例来调⽤。

4.2 初始化接口

TOPSdkManager.getInstance().init(Context context, appId, TOPCallback<Boolean> callback);

该接⼝⽤于进⾏SDK初始化操作,必须在调⽤SDK其他接⼝前尽早调⽤并确保在使用其他功能前已经初始化成功(最好在Application的onCreate方法中进行初始化操作)。

参数

key含义类型
context应用上下文。建议用getApplicationContext()Context
appId每款应用在平台的唯一标识,由平台分配String
callbackcallback为TOPCallback的实例。TOPCallback的回调方法有onSuccess、onFailed。回调onSuccess方法表明初始化成功,回调onFailed方法表明初始化失败TOPCallback

返回结果

(1)成功时执行onSuccess()方法,返回Boolean类型变量。

(2)失败时执行onFailed()方法,返回ErrorResults类型变量。

4.3 资源释放接口

gameSDKManager.onDestroy(Activity activity)

该接⼝⽤于在游戏关闭时进行资源释放(游戏主Activity的onDestroy方法中调用)

参数

key含义类型
activityActivity实例Activity

返回结果:无

4.4 登录接口

gameSDKManager.login(Activity activity);

该接⼝⽤于进⾏SDK登录操作。调用此接口务必要实现3.1的回调,用来接收登录回调监听。

参数

key含义类型
activityActivity实例Activity

返回结果:无

4.5 支付接口(该支付结果仅作为参考,真实结果请以服务器结果为准)

支付流程图:

top_pay_pic

gameSDKManager.pay(Activity activity, TOPPayParameters parameters, TOPRoleInfo roleInfo, TOPCallback<TOPPaymentData> callback);

该接⼝⽤于SDK支付功能。

参数

key含义类型
activityActivity实例Activity
parameters商品信息TOPPayParameters
roleInfo角色信息TOPRoleInfo
callbackcallback为TOPCallback的实例。TOPCallback的回调方法有onSuccess、onFailed。回调onSuccess方法标明客户端支付成功,回调onFailed方法表明客户端支付失败TOPCallback

TOPPayParameters实体类参数说明:

key含义类型
productId商品IdString
productName商品名称String
amount商品价格(保留两位小数)double
developerPayload透传参数(最多250字符)String

TOPRoleInfo实体类参数说明:

key含义类型
roleId角色IDString
roleName角色名称String
roleLevel角色等级String
serverId区服idString
serverName区服名称String
vipLevelvip等级String

返回结果

(1)成功时执行onSuccess()方法,返回TOPPaymentData类型变量,其中包含值为:

key含义类型
productId商品IDString
orderNo平台交易OrderNoString
payPlatformOrderNo三方支付平台交易OrderNoString

(2)失败时执行onFailed()方法,返回ErrorResults类型变量。

4.6 登出接口

gameSDKManager.logout(Activity activity);

该接⼝⽤于进⾏SDK登出操作。调用此接口务必要实现3.2的回调,用来接收登出回调监听。

参数

key含义类型
activityActivity实例Activity

返回结果:无

4.7 打开用户中心界面接口

gameSDKManager.enterUserCenter(Activity activity);

该接⼝⽤于唤起⽤户中⼼⻚⾯,⻚⾯会以全屏⽅式覆盖在当前界⾯上,可以实现绑定账号功能。调用此接口务必要实现3.2的回调,用来接收登出回调监听。

参数

key含义类型
activityActivity实例Activity

返回结果:无

4.8 获取用户信息接口

gameSDKManager.getUserInfo(TOPCallback<TOPUserInfo> callback);

该接⼝⽤于获取用户信息接口。

参数

key含义类型
callbackcallback为TOPCallback的实例。TOPCallback的回调方法有onSuccess、onFailed。回调onSuccess方法表明获取成功,回调onFailed方法表明获取失败TOPCallback

返回结果

(1)成功时执行onSuccess()方法,返回TOPUserInfo类型变量,其中包含值为:

key含义类型
id用户idString
name用户名String

(2)失败时执行onFailed()方法,返回ErrorResults类型变量。

4.9 获取账号绑定信息接口

gameSDKManager.getUserBindInfo(TOPCallback<List<String>> callback);

该接⼝⽤于获取账号绑定信息接口。

参数

key含义类型
callbackcallback为TOPCallback的实例。TOPCallback的回调方法有onSuccess、onFailed。回调onSuccess方法表明获取成功,回调onFailed方法表明获取失败TOPCallback

返回结果

(1)成功时执行onSuccess()方法,返回List类型变量。

(2)失败时执行onFailed()方法,返回ErrorResults类型变量。

4.10 绑定账号接口

gameSDKManager.bindPlatform(Activity activity, TOPPlatformType platformType);

该接⼝⽤于在登录成功后,用于绑定其他的三方账号。调用此接口务必要实现3.3的回调,用来接收绑定回调监听。

参数

key含义类型
activityActivity实例Activity
platformType需要绑定的三方平台,如TOPPlatformType.GOOGLE、TOPPlatformType.FACEBOOK等TOPPlatformType

返回结果:无

4.11 获取sdk版本号接口

gameSDKManager.getSDKVersion();

该接⼝⽤于获取sdk版本号。

参数:无

返回结果

key含义类型
返回值sdk版本号String

4.12 开启或关闭debug模式接口

gameSDKManager.setDebugEnabled(boolean isEnabled);

该接⼝⽤于开启debug模式,默认是false,可在Logcat查看相关日志,正式包务必注释掉。

参数

key含义类型
isEnabled日志打印(true表示启用,false标识关闭)boolean

返回结果:无

5、SDK事件上报使用说明

5.1 TOPData全局单例获取

TOPData topData = TOPData.getInstance();

TOPData基于单例模式设计,必须使⽤该接⼝来获取唯⼀实例,才能正常使⽤。后续接⼝都必须通过单例来调⽤。

5.2 设置唯一用户ID

给事件上报设置唯一用户ID

  • 1、如果已接入TopSDK登录SDK,忽略该设置;

  • 2、如果没有接入TopSDK登录SDK,上报事件需要设置唯一用户ID,否则上报信息无效,调用时机务必在所有事件上报之前

方法

void setAccountId(String accountId);

参数介绍

参数名介绍类型
accountId游戏唯一用户IDString

5.3 登录事件

事件说明

在用户登录时触发,此事件会上报至所有集成的数据平台(Appsflyer、GA、Adjust)

SDK已自动上报此事件,用户无需单独上报

方法

void loginEvent(String method);

参数介绍

参数名介绍类型
method登录使用的方法,比如:GOOGLE、FACEBOOK、GUESTString

5.4 注册事件

事件说明

在新用户首次注册时触发,此事件会上报至所有集成的数据平台(Appsflyer、GA、Adjust)

SDK已自动上报此事件,用户无需单独上报

方法

void signupEvent(String method);

参数介绍

参数名介绍类型
method登录使用的方法,比如:GOOGLE、FACEBOOK、GUESTString

5.5 支付事件

事件说明

用户支付成功时触发,此事件会上报至所有集成的数据平台(Appsflyer、GA、Adjust)

SDK已自动上报此事件,用户无需单独上报

方法

void purchaseEvent(TOPPurchaseData data);

参数介绍

TOPPurchaseData:

keydesexample类型
revenue价格1.1double
currency币种USDString
quantity数量,默认11int
productId商品idcom.demo.item01String
orderId订单号12131231231String
receiptId票据idawdfaqwdfqcsString

5.6 开始新手引导事件

事件说明

可选事件,请自行调用,建议在新手引导开始时上报,此事件会上报至所有集成的数据平台(Appsflyer、GA、Adjust)

方法

 void tutorialBeginEvent();

5.7 完成新手引导事件

事件说明

可选事件,请自行调用,建议在新手引导结束时上报,此事件会上报至所有集成的数据平台(Appsflyer、GA、Adjust)

方法

 void tutorialCompleteEvent(String tutorialName, boolean success);

参数介绍

参数名类型介绍
tutorialNameString新手引导名称
successboolean是否完成

5.8 升级事件

事件说明

可选事件,请自行调用,建议在游戏角色升级时上报,此事件会上报至所有集成的数据平台(Appsflyer、GA、Adjust)

方法

 void levelUpEvent(int level, String roleName);

参数介绍

参数名类型介绍
levelint等级
roleNameString角色名

5.9 成就解锁事件

事件说明

可选事件,请自行调用,建议在游戏角色解锁成就时上报,此事件会上报至所有集成的数据平台(Appsflyer、GA、Adjust)

方法

 void unlockAchievementEvent(String achievementId);

参数介绍

参数名类型介绍
achievementIdString成就id

5.10 分享事件

事件说明

可选事件,请自行调用,建议在触发分享时上报,此事件会上报至所有集成的数据平台(Appsflyer、GA、Adjust)

方法

void shareEvent(String method, String contentType, String contentId);

参数介绍

参数名类型介绍
methodString分享渠道,如:Facebook、Twitter、Email...
contentTypeString分享内容类型,如:图片、链接、视频、文本
contentIdString分享内容id,如:活动id

5.11 获得虚拟货币事件

事件说明

可选事件,请自行调用,建议在玩家获得虚拟货币时调用,此事件会上报至所有集成的数据平台(Appsflyer、GA、Adjust)

方法

void earnVirtualCurrencyEvent(String name, int count);

参数介绍

参数名类型介绍
nameString虚拟货币名称,如:宝石、钻石
countint虚拟货币数量,如:100

5.12 支出虚拟货币

事件说明

可选事件,请自行调用,建议在玩家支出虚拟货币时调用,此事件会上报至所有集成的数据平台(Appsflyer、GA、Adjust)

方法

void spendVirtualCurrencyEvent(String name, int count, String goodsName);

参数介绍

参数名类型介绍
nameString虚拟货币名称,如:宝石、钻石
countint虚拟货币数量,如:100
goodsNameString购买的商品名称,如:包月会员

5.13 游戏关卡开始事件

事件说明

可选事件,请自行调用,建议在玩家开始关卡时调用,此事件会上报至所有集成的数据平台(Appsflyer、GA、Adjust)

方法

void levelStartEvent(String levelName);

参数介绍

参数名类型介绍
levelNameString关卡名称,如:1-1

5.14 游戏关卡结束事件

事件说明

可选事件,请自行调用,建议在玩家结束关卡时调用,此事件会上报至所有集成的数据平台(Appsflyer、GA、Adjust)

方法

void levelEndEvent(String levelName, boolean success);

参数介绍

参数名类型介绍
levelNameString关卡名称,如:1-1
successboolean是否成功

5.15 自定义事件上报

事件说明

如果以上模板事件不能满足需求,可选择自定义事件上报

方法

void report(String eventName, Map<String, String> params, TOPDataChannelType channelType);

参数介绍

参数名类型介绍
eventNameString事件名
paramsMap(String:String)参数
channelTypeTOPDataChannelType上报渠道类型,默认All

TOPDataChannelType介绍

类型说明
TOPDataChannelType.All上报到所有接入的数据平台,如:Appsflyer、Firebase、Adjust、Facebook
TOPDataChannelType.AppsFlyer仅上报到Appsflyer
TOPDataChannelType.Firebase仅上报到Firebase
TOPDataChannelType.Adjust仅上报到Adjust
TOPDataChannelType.Facebook仅上报到Facebook

5.16 事件对照表

我们将对应数据平台的模板事件关联,将事件转换为平台对应的模板事件名进行上报,具体事件名如下:

事件TOPDataAFGA&AdjustFacebook Data
登录#top_loginaf_loginloginlogin
注册#top_sign_upaf_complete_registrationsign_upfb_mobile_complete_registration
新手引导开始#top_tutorial_begintutorial_begintutorial_begintutorial_begin
新手引导结束#top_tutorial_completeaf_tutorial_completiontutorial_completefb_mobile_tutorial_completion
角色升级#top_level_upaf_level_achievedlevel_upfb_mobile_level_achieved
成就解锁#top_unlock_achievementaf_achievement_unlockedunlock_achievementfb_mobile_achievement_unlocked
下单#start_pay--fb_mobile_initiated_checkout
支付#top_purchaseaf_purchasepurchasefb_mobile_purchase
分享#top_shareaf_shareshareshare
获取虚拟币#top_earn_virtual_currencyearn_virtual_currencyearn_virtual_currencyearn_virtual_currency
支出虚拟币#top_spend_virtual_currencyspend_virtual_currencyspend_virtual_currencyfb_mobile_spent_credits
关卡开始#top_level_startlevel_startlevel_startlevel_start
关卡结束#top_level_endlevel_endlevel_endlevel_end

6、修改登录面板的 LOGO 图片

如下图所示,找到工程的 application 工程,创建 mipmap-xxhdpi 目录(如果存在请忽略),然后把自己的 LOGO 命名为 custom_logo.png ,放到 mipmap-xxhdpi 目录下,Meetgames 默认 LOGO 宽高为305 × 70,为了保持登录面板 LOGO 排版一致,务必把自己的 LOGO 的宽高保持一致

as-6