跳到主要内容

Cocos接入文档

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

2、SDK快速接入

Android_Cocos_Demo工程,仅供研发接入参考

iOS_Cocos_Demo工程,仅供研发接入参考

2.1 Android配置要求

  • minSdkVersion ≥ 21(Android 5.0 或更高版本)
  • Java 8或更高版本
  • AndroidX 支持
  • Cocos Creator 2.x.x 及以上版本

2.2 iOS配置要求

  • iOS 9及以上
  • Cocos Creator 2.x.x 及以上版本

2.3 SDK集成

3、SDK回调函数使用说明

3.1 初始化回调函数

//事件注册(务必在以下接口调用前进行注册)
TopSDKEmitter.register("EmitInitSuccessEvent", this.EmitInitSuccessEvent, this);
TopSDKEmitter.register("EmitInitFailedEvent", this.EmitInitFailedEvent, this);
//初始化成功,事件返回参数为(eventName:string)
EmitInitSuccessEvent(eventName: string) {
//eventName
}
//初始化失败,事件返回参数为(eventName:string)
EmitInitFailedEvent(eventName: string) {
//eventName
}

3.2 登录回调函数

//事件注册(务必在以下接口调用前进行注册)
TopSDKEmitter.register("EmitLoginSuccessEvent", this.EmitLoginSuccessEvent, this);
TopSDKEmitter.register("EmitLoginFailedEvent", this.EmitLoginFailedEvent, this);
//登录成功,事件返回参数为(eventName:string, userInfo:Map<string, any>)
EmitLoginSuccessEvent(eventName: string, userInfo: Map<string, any>) {
//eventName
//userInfo:Map<string, any>返回字段说明
//userInfo.get('id');//用户id
//userInfo.get('name');//用户名
//userInfo.get('token');//用户token
}
//登录失败,事件返回参数为(eventName:string, errorInfo:Map<string, any>)
EmitLoginFailedEvent(eventName: string, errorInfo: Map<string, any>) {
//eventName
//失败 errorInfo:Map<string, any>返回字段说明
//errorInfo.get('code');//错误码
//errorInfo.get('message');//错误信息
}

3.3 支付回调函数(该支付结果仅作为参考,真实结果请以服务器结果为准)

//事件注册(务必在以下接口调用前进行注册)
TopSDKEmitter.register("EmitPaySuccessEvent", this.EmitPaySuccessEvent, this);
TopSDKEmitter.register("EmitPayFailedEvent", this.EmitPayFailedEvent, this);
//支付成功,事件返回参数为(eventName:string, payInfo:Map<string, any>)
EmitPaySuccessEvent(eventName: string, payInfo: Map<string, any>) {
//eventName
//支付成功 payInfo:Map<string, any>返回字段说明
//payInfo.get('productId');//商品ID
//payInfo.get('orderNo');//TOP平台交易OrderNo
//payInfo.get('payPlatformOrderNo');//三方支付平台交易OrderNo
}
//支付失败,事件返回参数为(eventName:string, errorInfo:Map<string, any>)
EmitPayFailedEvent(eventName: string, errorInfo: Map<string, any>) {
//eventName
//失败 errorInfo:Map<string, any>返回字段说明
//errorInfo.get('code');//错误码
//errorInfo.get('message');//错误信息
}

3.4 登出回调函数

//事件注册(务必在以下接口调用前进行注册)
TopSDKEmitter.register("EmitLogoutSuccessEvent", this.EmitLogoutSuccessEvent, this);
//退出登录成功,事件返回参数为(eventName:string)
EmitLogoutSuccessEvent(eventName: string) {
//eventName
}

3.5 用户信息获取回调函数

//事件注册(务必在以下接口调用前进行注册)
TopSDKEmitter.register("EmitUserInfoSuccessEvent", this.EmitUserInfoSuccessEvent, this);
TopSDKEmitter.register("EmitUserInfoFailedEvent", this.EmitUserInfoFailedEvent, this);
//获取用户信息成功,事件返回参数为(eventName:string, userInfo:Map<string, any>)
EmitUserInfoSuccessEvent(eventName: string, userInfo: Map<string, any>) {
//eventName;
//成功 userInfo:Map<string, any>返回字段说明
//userInfo.get('id');//用户id
//userInfo.get('name');//用户名

}
//获取用户信息失败,事件返回参数为(eventName:string, errorInfo:Map<string, any>)
EmitUserInfoFailedEvent(eventName: string, errorInfo: Map<string, any>) {
//eventName
//失败 errorInfo:Map<string, any>返回字段说明
//errorInfo.get('code');//错误码
//errorInfo.get('message');//错误信息
}

3.6 用户绑定的三方平台获取回调函数

//事件注册(务必在以下接口调用前进行注册)
TopSDKEmitter.register("EmitUserBindInfoSuccessEvent", this.EmitUserBindInfoSuccessEvent, this);
TopSDKEmitter.register("EmitUserBindInfoFailedEvent", this.EmitUserBindInfoFailedEvent, this);
//获取用户绑定信息成功,事件返回参数为(eventName:string, bindInfo:Array<string>)
EmitUserBindInfoSuccessEvent(eventName: string, bindInfo: Array<string>) {
//eventName
//成功 bindInfo:Array<string>返回字段说明
for (let i = 0; i < bindInfo.length; i++){
//三方平台类型(FACEBOOK,GOOGLE等)
string name = bindInfo[i];
}
}
//获取用户绑定信息失败,事件返回参数为(eventName:string, errorInfo:Map<string, any>)
EmitUserBindInfoFailedEvent(eventName: string, errorInfo: Map<string, any>) {
//eventName
//失败 errorInfo:Map<string, any>返回字段说明
//errorInfo.get('code');//错误码
//errorInfo.get('message');//错误信息
}

3.7 绑定账号回调函数

//事件注册(务必在以下接口调用前进行注册)
TopSDKEmitter.register("EmitBindSuccessEvent", this.EmitBindSuccessEvent, this);
TopSDKEmitter.register("EmitBindFailedEvent", this.EmitBindFailedEvent, this);
//用户绑定三方平台成功,事件返回参数为(eventName:string, bindInfo:Map<string,any>)
EmitBindSuccessEvent(eventName: string, bindInfo: Map<string, any>) {
//eventName
//成功bindInfo:Map<string,any>返回字段说明
//string platformType = bindInfo.get('platform');//三方平台类型(FACEBOOK,GOOGLE等)
//int bindStatus = bindInfo.get('bindStatus');//1:绑定/已绑定
}
//用户绑定三方平台失败,事件返回参数为(eventName:string, errorInfo:Map<string, any>)
EmitBindFailedEvent(eventName: string, errorInfo: Map<string, any>) {
//eventName
//失败 errorInfo:Map<string, any>返回字段说明
//errorInfo.get('code');//错误码
//errorInfo.get('message');//错误信息
}

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

//事件注册(务必在以下接口调用前进行注册)
TopSDKEmitter.register("EmitUserCenterCloseSuccessEvent", this.EmitUserCenterCloseSuccessEvent, this);
//用户中心返回关闭,事件返回参数为(eventName:string)
EmitUserCenterCloseSuccessEvent(eventName: string) {
//eventName
}

4、SDK接口使用说明

4.1 初始化接口

TopSDK.init(appId: string);

该接⼝⽤于进⾏SDK初始化操作,必须在调⽤SDK其他接⼝前尽早调⽤并确保在使用其他功能前已经初始化成功。调用此接口务必要实现3.1的回调,用来接收初始化回调监听。

参数

key含义类型
appId每款应用在平台的唯一标识,由平台分配string

返回结果:无

4.2 登录接口

TopSDK.login();

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

参数:无

返回结果:无

4.3 支付接口

支付流程图:

top_pay_pic

TopSDK.pay(parameters: TOPPayParamenters, roleInfo: TOPRoleInfo);

该接⼝⽤于SDK支付功能。调用此接口务必要实现3.3的回调,用来接收支付回调监听。

参数

key含义类型
parameters商品信息TOPPayParameters
roleInfo角色信息TOPRoleInfo

TOPPayParameters实体类参数说明:

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

TOPRoleInfo实体类参数说明:

key含义类型
roleId角色IDstring
roleName角色名称string
roleLevel角色等级string
serverId区服idstring
serverName区服名称string
vipLevelvip等级string

返回结果:无

4.4 登出接口

TopSDK.logout();

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

参数:无

返回结果:无

4.5 打开用户中心界面接口

TopSDK.enterUserCenter();

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

参数:无

返回结果:无

4.6 获取用户信息接口

TopSDK.getUserInfo();

该接⼝⽤于获取用户信息接口。调用此接口务必要实现3.5的回调,用来接收用户信息回调监听。

参数: 无

返回结果:无

4.7 获取账号绑定信息接口

TopSDK.getUserBindInfo();

该接⼝⽤于获取账号绑定信息接口。调用此接口务必要实现3.6的回调,用来接收绑定信息回调监听。

参数: 无

返回结果:无

4.8 绑定账号接口

TopSDK.bindPlatform(platform: TOPPlatformType);

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

参数

key含义类型
platform需要绑定的三方平台,如TOPPlatformType.GOOGLE、TOPPlatformType.FACEBOOK等TOPPlatformType

返回结果:无

4.9 获取sdk版本号接口

string ver = TopSDK.getVersion();

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

参数:无

返回结果

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

5、SDK事件上报使用说明

5.1 设置唯一用户ID

TopSDK.setAccountId(accountId: string);

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

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

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

参数

key含义类型
accountId游戏唯一用户IDstring

返回结果:无

5.2 是否关闭收集IDFA(仅iOS)

TopSDK.disableCollectIDFA(isDisable: boolean);

该接⼝用于关闭iOS收集IDFA,默认会收集IDFA,从而提升归因准确率

参数

key含义类型
isDisable是否关闭IDFABoolean

返回结果:无

5.3 上报登录事件(TOPSDK自动上报)

TopSDK.loginEvent(method: string);

该接⼝用于上报登录事件,TOPSDK会自动上报该事件,无需单独上报

参数

key含义类型
method登录方式,如:GOOGLE、FACEBOOK、GUESTstring

返回结果:无

5.4 上报注册事件(TOPSDK自动上报)

TopSDK.signupEvent(method: string);

该接⼝用于上报注册事件,TOPSDK会自动上报该事件,无需单独上报

参数

key含义类型
method登录方式,如:GOOGLE、FACEBOOK、GUESTstring

返回结果:无

5.5 上报支付事件(TOPSDK自动上报)

TopSDK.purchaseEvent(purchase: TOPPurchaseData);

该接⼝用于上报注册事件,TOPSDK会自动上报该事件,无需单独上报

参数

key含义类型
purchase支付信息TOPPurchaseData

TOPPurchaseData介绍

key类型介绍
currencystring币种,如:USD
revenuedouble价格,如:101.01
quantityint数量,默认1
productIdstring商品id,如:com.sino.item1
orderIdstring订单号,如:11230912739
receiptIdstring收据编号,如:lashdaioasd

返回结果:无

5.6 上报新手引导开始事件

TopSDK.tutorialBeginEvent();

该接⼝用于上报新手引导开始事件,如有需求,请自行调用上报

参数: 无

返回结果:无

5.7 上报新手引导结束事件

TopSDK.tutorialCompleteEvent(tutorialName: string, success: boolean);

该接⼝用于上报新手引导开始事件,如有需求,请自行调用上报

参数

key含义类型
tutorialName新手引导名称string
success是否完成boolean

返回结果:无

5.8 上报升级事件

TopSDK.levelUpEvent(level: number, roleName: string);

该接⼝用于上报升级事件,如有需求,请自行调用上报

参数

key含义类型
level等级,如:100int
roleName角色名,如:小白string

返回结果:无

5.9 上报成就解锁事件

TopSDK.unlockAchievementEvent(achievementId: string);

该接⼝用于上报成就解锁事件,如有需求,请自行调用上报

参数

key含义类型
achievementId成就id,如:level001string

返回结果:无

5.10 上报分享事件

TopSDK.shareEvent(method: string, contentType: string, contentId: string);

该接⼝用于上报分享事件,如有需求,请自行调用上报

参数

key含义类型
method分享方式,如:FACEBOOK、SNAPCHATstring

返回结果:无

5.11 上报获取虚拟币事件

TopSDK.earnVirtualCurrencyEvent(name: string, count: number);

该接⼝用于上报获取虚拟币事件,如有需求,请自行调用上报

参数

key含义类型
name虚拟币名称,如:钻石string
count虚拟币数量,如:10000int

返回结果:无

5.12 上报支出虚拟币事件

TopSDK.spendVirtualCurrencyEvent(name: string, count: number, goodsName: string);

该接⼝用于上报支出虚拟币事件,如有需求,请自行调用上报

参数

key含义类型
name虚拟币名称,如:钻石string
count虚拟币数量,如:10000int
goodsName虚拟币购买的商品名称,如:月卡string

返回结果:无

5.13 上报关卡开始事件

TopSDK.levelStartEvent(levelName: string);

该接⼝用于上报关卡开始事件,如有需求,请自行调用上报

参数

key含义类型
levelName关卡名称,如:1-1string

返回结果:无

5.14 上报关卡结束事件

TopSDK.levelEndEvent(levelName: string, success: boolean);

该接⼝用于上报关卡结束事件,如有需求,请自行调用上报

参数

key含义类型
levelName关卡名称,如:1-1string
success关卡是否通过Boolean

返回结果:无

5.15 上报自定义事件

TopSDK.reportEvent(eventName: string, params: Map<string, string>, channelType: TOPDataChannelType);

该接⼝用于上报自定义事件到指定数据平台,如有需求,请自行调用上报

参数

key含义类型
eventName事件名,如:buystring
params参数JSON Object
channelType上报渠道TOPDataChannelType

TOPDataChannelType介绍

类型说明
ALL上报到所有接入的数据平台,如:Appsflyer、Firebase、Adjust、Facebook
APPSFLYER仅上报到Appsflyer
FIREBASE仅上报到Firebase
ADJUST仅上报到Adjust
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、导出原生项目说明

6.1 导出AndroidStudio项目(Android)

1、 导出AndroidStudio项目

2、请把下载的sdk包中的libs下的文件复制到游戏AndroidStudio项目libservice目录下

3、 启用AndroidX配置,在项目的gradle.properties添加配置以下代码:

android.useAndroidX=true
android.enableJetifier=true

androidx

4、 添加以下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/' }
}
}

cocos-1

5、 添加以下SDK依赖到library模块的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"
//facebook data 数据统计 (可选)
implementation "$groupId:facebook-data:$topsdk_version"
//adjust (可选)
implementation "$groupId:adjust:$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')
}

cocos-2

渠道标识top_channel_id取值

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

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

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

assets目录创建方式

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

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

cocos-google-services 7、将 adjust Android 配置文件添加到您的应用(如果添加了adjust依赖<)

​ 将下载的 topsdk_adjust_event.json 配置文件,复制到游戏工程assets目录下 (和渠道配置文件同目录)

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

6.2 导出Xcode项目(iOS)

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

找到工程的 application 工程,进⼊ src ⽬录新建 main ⽂件夹,在 main ⽂件夹下新建 res ⽂件夹,在 res 文件夹下新建 mipmap-xxhdpi 目录(如果存在请忽略),然后把自己的 LOGO 命名为 custom_logo.png ,放到 mipmap-xxhdpi 目录下,Meetgames 默认 LOGO 宽高为305 × 70,为了保持登录面板 LOGO 排版一致,务必把自己的 LOGO 的宽高保持一致