1.简介
UWingSDK是基于WingSDK功能实现的，支持快速接入的一套SDK方案。与传统的SDK接入不同，UWingSDK除了登录，大部分功能均无SDK后台限制，实现支持直接返回结果，直接调试接口，有效提升了接入效率。
2.快速开始
2.1.项目配置要求
API版本：最低API版本24，目标API版本35或以上
|
1 2 3 4 5 6 |
defaultConfig { applicationId "xxxxxx" minSdk 24 // 最低API版本24 targetSdk 35 // 目标API版本35或以上 } |
2.2.集成SDK
a、添加仓库地址
新项目配置：在项目根目录下的settings.gradle文件添加以下配置：
|
1 2 3 4 5 6 7 8 9 10 11 12 13 |
dependencyResolutionManagement { repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS) repositories { google() mavenCentral() //这里是UWingSDK的maven地址，内部声明支持http请求 maven { allowInsecureProtocol = true url "http://repo.wingsdk.cn:8081/repository/winga-group/" } } } |
旧项目配置：在项目根目录下的build.gradle文件添加以下配置：
|
1 2 3 4 5 6 7 8 9 10 11 12 13 |
apply plugin: 'maven' allprojects { repositories { jcenter() //这里是UWingSDK的maven地址，内部声明支持http请求 maven { allowInsecureProtocol= true url "http://repo.wingsdk.cn:8081/repository/winga-group/" } } } |
b、在项目的app/build.gradle中添加SDK库：
|
1 2 3 |
implementation 'com.uwa.sdk:uwa-sdk-base:1.0.0' |
2.3.AndroidManifest.xml配置
在清单配置中添加下面配置，sdk_app_id和sdk_app_key具体值从对接表中获取
|
1 2 3 4 5 6 7 8 |
<meta-data android:name="com.wa.sdk.APP_ID" android:value="@string/sdk_app_id" /> <meta-data android:name="com.wa.sdk.APP_KEY" android:value="@string/sdk_app_key" /> |
2.4 Activity结果传递
重写Activity的onActivityResult方法，并调用下面方法
|
1 2 |
UWingSDK.onActivityResult(Activity activity, int requestCode, int resultCode, Intent data) |
参考示例
|
1 2 3 4 5 6 7 |
@Override protected void onActivityResult(int requestCode, int resultCode, Intent data) { super.onActivityResult(requestCode, resultCode, data); // 必须添加该方法，否则可能收不到登录和支付等回调结果 UWingSDK.onActivityResult(activity, requestCode, resultCode, data); } |
注意：若未添加该方法，可能导致无法接收登录、支付等功能的回调结果。
2.5 SDK初始化
在游戏页面Activity的onCreate中调用下面方法
|
1 2 |
UWingSDK.initialize(Activity activity, UWCallback<Void> sdkInitCallback) |
示例如下
|
1 2 3 4 5 6 7 8 9 10 11 12 13 |
//初始化sdk，在游戏页面的onCreate中调用 UWingSDK.initialize(activity, new UWCallback<Void>() { @Override public void onSuccess(int code, String message, Void result) { Log.i(TAG, "初始化成功：" + message); } @Override public void onError(int code, String message, Void result, Throwable throwable) { Log.i(TAG, "初始化失败（" + code + "）：" + message); } }); |
注意
1.SDK初始化必须在游戏页Activity（不能是闪屏页）的onCreate()方法中调用。
2.其他所有SDK接口都必须在SDK初始化成功的情况下才能调用。
2.6 添加测试设备
在登录测试框中点击蓝色ClientID文字进行复制，把该内容提供的运营添加测试设备
如果未添加测试设备，会导致无法使用登录，支付等功能。
3. 功能接入
3.1 登录
调用方法：
|
1 2 |
UWingSDK.User.login(Activity activity, UWCallback<UWLoginResult> callback) |
登录结果UWLoginResult说明
| 字段名 | 类型 | 说明 | 备注 |
|---|---|---|---|
| userId | String | SDK的用户ID | |
| token | String | SDK的登录token | |
| platform | String | 当前登录平台（如GOOGLE、FACEBOOK） |
示例如下：
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 |
UWingSDK.User.login(activity, new UWCallback<UWLoginResult>() { @Override public void onSuccess(int code, String message, UWLoginResult result) { String userId = result.getUserId(); String token = result.getToken(); String platform = result.getPlatform(); String msg = "登录成功. uid: " + userId + "\ntoken:" + token + "\nplatform:" + platform; showMsg(msg); } @Override public void onError(int code, String message, UWLoginResult result, Throwable throwable) { showMsg("登录失败（" + code + "）：" + message); } }); |
3.2 登出
调用方法
|
1 2 |
UWingSDK.User.logout(Activity activity) |
3.3 支付
调用方法
|
1 2 |
UWingSDK.User.pay(Activity activity, String sdkProductId, String extInfo, UWCallback<UWPayResult> callback) |
方法参数说明
| 参数名 | 类型 | 说明 | 备注 |
|---|---|---|---|
| activity | Activity | 当前Activity | |
| sdkProductId | String | SDK的商品ID（非Google商品ID），从运营处获取 | |
| extInfo | String | 扩展信息，可用于透传（如透传订单号或发货接口），支付成功后会原样通知CP服务器 | |
| callback | UWCallback |
支付回调处理 |
支付结果UWPayResult说明
| 字段名 | 类型 | 说明 | 备注 |
|---|---|---|---|
| platform | String | 支付平台（如GOOGLE） | |
| sdkProductId | String | SDK的商品ID | |
| extInfo | String | 扩展信息 | 支付时传入的extInfo一致 |
| orderId | String | SDK订单ID | 部分支付方式没有 |
| currency | String | 货币类型（基准货币） | 由SDK后台定义 |
| price | long | 商品价格，单位微分（1元=1000000） | 由SDK后台定义 |
示例如下：
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 |
// SDK 商品ID，从运营提供的商品列表中获取商品对应的值 String sdkProductId = "1"; // 额外信息，可用于透传，比如透传订单号或发货接口。该信息会在支付成功后原样通知到 CP 服务器，供 CP 用于检验 String extInfo = "test_ext_info_1111"; UWingSDK.User.pay(activity, sdkProductId, extInfo, new UWCallback<UWPayResult>() { @Override public void onSuccess(int code, String message, UWPayResult result) { String productId = result.getSdkProductId(); // SDK商品ID String info = result.getExtInfo(); // 额外信息 String platform = result.getPlatform(); // 支付平台 String currency = result.getCurrency(); // 币种（由SDK后台定义的基准货币） long price = result.getPrice(); // 商品价格，单位微分，1元=1000000（由SDK后台定义的基准货币价格） String orderId = result.getOrderId(); // SDK订单ID showMsg("支付成功. ProductId:" + productId + ", ExtInfo：" + info); } @Override public void onCancel() { showMsg("支付取消."); } @Override public void onError(int code, String message, UWPayResult result, Throwable throwable) { showMsg("支付失败（" + code + "）: " + message + ". UWPayResult:" + result); } }); |
测试发货：具体查看《CP接口测试》章节中的 《内购商品发货接口》
3.4 事件发送
3.4.1 进入游戏服务器
调用方法：
|
1 2 |
UWingSDK.TrackEvent.enterGameServer(String serverId, String gameUserId, String nickname, int level) |
参数说明：
| 参数名 | 类型 | 说明 | 备注 |
|---|---|---|---|
| serverId | String | 服务器ID | |
| gameUserId | String | 游戏角色ID | 如果未创角，可以设置为 “-1” |
| nickname | String | 游戏角色名（昵称） | 如果未创角，可以设置为空字符串”” |
| level | int | 游戏角色当前等级 | 如果未创角，填入游戏角色初始等级，一般为 1 |
3.4.2 用户创建角色
调用方法：
|
1 2 |
UWingSDK.TrackEvent.createRole(String serverId, String gameUserId, String nickname, int level, long registerTime) |
参数说明：
| 参数名 | 类型 | 说明 | 备注 |
|---|---|---|---|
| serverId | String | 服务器ID | |
| gameUserId | String | 游戏角色ID | |
| nickname | String | 游戏角色名（昵称） | |
| level | int | 游戏角色当前等级 | |
| registerTime | long | 创建角色时的时间戳，单位为毫秒，长度13位 |
3.4.3 角色等级升级
调用方法：
|
1 2 |
UWingSDK.TrackEvent.levelUp(int currentLevel) |
参数说明：
| 参数名 | 类型 | 说明 | 备注 |
|---|---|---|---|
| currentLevel | int | 游戏角色当前等级 |
3.4.4 修改游戏角色名
调用方法：
|
1 2 |
UWingSDK.TrackEvent.updateNickname(String nickname) |
参数说明：
| 参数名 | 类型 | 说明 | 备注 |
|---|---|---|---|
| nickname | String | 更改后的游戏角色名（昵称） |
3.4.5 用户点击支付
调用方法：
|
1 2 |
UWingSDK.TrackEvent.clickToPay() |
3.4.6 新手任务完成
调用方法：
|
1 2 |
UWingSDK.TrackEvent.tutorialCompleted() |
3.5 客服中心
添加该功能入口：
在游戏设置页中添加该功能入口，入口的图标和名称可以使用SDK内置的资源。
文案资源（文案已国际化）：R.string.wa_sdk_settings_customer_center
图标资源：R.drawable.wa_sdk_settings_center
效果如下：
调用方法：
|
1 2 |
UWingSDK.User.showCustomerCenter(Activity activity, UWIAccountCallback accountCallback) |
UWIAccountCallback 回调说明：
| 方法 | 说明 | CP需要处理 |
|---|---|---|
| onSwitchAccount(String userId, String token, Bundle bundle) | 账号切换成功 | 游戏客户端要回到登录页并重新登录 |
| onBindAccount(boolean isBound, String platform, Bundle bundle) | 账号绑定状态变更 | 无 |
| onDeleteAccount | 账号申请注销成功 | 游戏客户端要退出游戏回到登录页 |
示例如下：
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 |
UWingSDK.User.showCustomerCenter(activity, new UWAccountCallback() { @Override public void onSwitchAccount(String userId, String token, Bundle bundle) { showMsg("账号切换成功【游戏客户端要回到登录页并重新登录】， uid: " + userId + ", token: " + token + ", 其他信息: " + bundle); } @Override public void onBindAccount(boolean isBound, String platform, Bundle bundle) { showMsg("账号绑定状态变更: " + (isBound ? "绑定" : "解绑") + ", 平台: " + platform + ", 其他信息: " + bundle); } @Override public void onDeleteAccount() { showMsg("账号申请注销成功!\n【游戏客户端要退出游戏回到登录页】"); } }); |
3.6 AiHelp客服
3.6.1 添加该功能入口
在游戏登录页中添加该功能入口，入口的图标和名称可以使用SDK内置的资源。
文案资源（文案已国际化）：R.string.wa_sdk_settings_customer_center
图标资源：R.drawable.wa_sdk_settings_center
效果如下：
3.6.2 判断是否开启
调用方法：
|
1 2 |
boolean isEnable = UWingSDK.AiHelp.isEnable() |
返回结果说明：
true – 开启；false – 未开启
示例如下：
|
1 2 3 4 5 |
// 获取是否开启AiHelp boolean isEnable = UWingSDK.AiHelp.isEnable(); // 开启时显示AiHelp客服按钮，未开启时隐藏 btnAiHelp.setVisibility(isEnable ? View.VISIBLE : View.GONE); |
3.6.3 显示AiHelp客服
调用方法：
|
1 2 |
UWingSDK.AiHelp.show() |
3.6.4 获取未读消息
在SDK初始成功之后，调用方法：
|
1 2 |
UWingSDK.AiHelp.getUnreadMessageCount(UWCallback<Integer> callback) |
示例如下：
|
1 2 3 4 5 6 7 8 9 10 |
// 在SDK初始成功之后，才可以调用该方法获取未读消息数 UWingSDK.AiHelp.getUnreadMessageCount(new UWCallback<Integer>() { @Override public void onSuccess(int code, String message, Integer result) { Log.i(TAG, "AiHelp未读消息数: " + result); // 更新未读数，大于0则需要显示红点，否则移除红点 mAiHelpRedDot.setVisibility(result > 0 ? View.VISIBLE : View.GONE); } }); |
3.7 游戏评价
3.7.1.判断是否开启
如果游戏有做评价发奖的引导页， 需要根据该状态决定是否弹出引导页，true需要弹出，false不需要弹出
调用方法：
|
1 2 |
boolean isEnable = UWingSDK.GameReview.isEnable() |
示例如下：
|
1 2 3 4 5 |
//是否开启游戏评价 boolean isEnable = UWingSDK.GameReview.isEnable(); // 为 true 时才显示评价发奖的引导页 if (isEnable) showGameReviewGuide(); |
3.7.2.展示游戏评价弹窗
调用方法：
|
1 2 |
UWingSDK.GameReview.show(Activity activity, UWGameReviewCallback gameReviewCallback) |
示例如下：
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
UWingSDK.GameReview.show(activity, new UWGameReviewCallback() { @Override public void onSuccess(int action) { // 1-好评；2-打开客服；3-拒绝； if (action == UWGameReviewCallback.ACTION_COMMENT) { // 如果需要好评发奖，可以在这里通知发奖 showMsg("游戏评价成功"); } else if (action == UWGameReviewCallback.ACTION_OPEN_CUSTOMER) { showMsg("打开客服"); } else if (action == UWGameReviewCallback.ACTION_REFUSE) { showMsg("拒绝评价"); } } }); |
注意：如果有多个触发点的情况，各触发点相互独立，不需要规定它们之间的逻辑关系（比如不要规定A点评价了B点就不弹评价等）
3.8 AdMob广告
3.8.1 判断是否开启奖励广告
调用方法：
|
1 2 |
boolean isEnable = UWingSDK.AdMob.RewardedAd.isEnable(String adName); |
参数说明：
| 参数名 | 类型 | 说明 | 备注 |
|---|---|---|---|
| adName | String | 广告名称，SDK后台配置的广告名称 | 具体值从运营处获取 |
3.8.2 展示激励广告
调用方法：
|
1 2 |
UWingSDK.AdMob.RewardedAd.showAd(Activity activity, String adName, String extInfo, UWAdMobAdsCallback callback) |
参数说明：
| 参数名 | 类型 | 说明 | 备注 |
|---|---|---|---|
| activity | Activity | 当前 Activity | |
| adName | String | 广告名称，SDK后台配置的广告名称 | 具体值从运营处获取 |
| extInfo | String | 额外信息，可用作透传，比如透传礼包ID | 该参数随广告奖励通知接口传递给游戏服务端，长度限制为100个字符 |
| callback | UWAdMobAdsCallback | 广告回调 |
UWAdMobAdsCallback广告回调说明：
| 方法 | 说明 |
|---|---|
| onAdShowed() | 广告页面成功显示 |
| onAdDismissed() | 广告页面关闭 |
| onAdFailed(String error_message) | 广告加载失败 |
示例如下：
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 |
UWingSDK.AdMob.RewardedAd.showAd(activity, adName, extInfo, new UWAdMobAdsCallback() { @Override public void onAdShowed() { showMsg("广告已显示"); } @Override public void onAdFailed(String error_message) { showMsg("广告加载失败: " + error_message); } @Override public void onAdDismissed() { showMsg("广告已关闭"); } }); |
测试发货：具体查看《CP接口测试》章节中的 《AdMob激励广告通知接口》
3.9 退出游戏提示
拦截用户返回操作，弹出退出提示框，用户点击确认退出时，会finish所有Activity，并结束游戏进程
调用方法：
|
1 2 |
UWingSDK.showExitDialog(Activity activity, UWCallback<Void> callback) |
示例如下：
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
// 返回手势拦截（建议使用该方式拦截返回手势，因为后续 目标 API 升级为 36（Android 16）时，onBackPress 需要也迁移到这种方式实现） getOnBackPressedDispatcher().addCallback(this, new OnBackPressedCallback(true) { @Override public void handleOnBackPressed() { // 退出游戏提示 UWingSDK.showExitDialog(activity, new UWCallback<Void>() { @Override public void onSuccess(int code, String message, Void result) { // 用户点击确认后会先调用该回调，然后在内部执行退出应用 } }); } }); |
显示效果如下：
4. CP接口测试
根据接入需求，可能会要求CP提供商品发货接口（应用内购），礼包通知接口（预注册，浮窗礼包），AdMob激励广告通知接口，这些接口都可在相关功能调用中进行测试，下面对这些接口测试进行介绍说明。
重要提示：
1.长按输出的信息可以进行复制
2.调试信息中，会打印请求时所用参数
4.1 内购商品发货接口
该接口用于SDK进行应用内商品购买时，通知CP进行发货，具体接入实现要求参考文档：
https://blog.wing-analytics.com/archives/2510.html#cp_deliver
4.1.1 在UWingSDK中测试
前提条件：
1. CP已提供内购商品发货通知接口，并且运营已在SDK后台中配置该接口
2. 已经与运营沟通好商品列表，并在列表中提供有对应SDK商品ID
测试步骤：
1.游戏正常接入支付接口 UWingSDK.User.pay()，其传入的sdkProductId和extInfo会传递给通知发货接口
2.游戏调用支付接口，在弹出的支付测试框中点击支付，会直接通知已配置在SDK后台的内购商品发货接口
3.如果提示成功，则表接口接入正常，按照蓝字提示完成发货即可
4.如果提示异常，请按照提示调整发货接口；同时可以查看调试信息，检查和校对请求时所用的参数（长按输出内容可以进行复制）
测试效果如下：
4.2.礼包通知接口（预注册，浮窗礼包）
该接口用于SDK的预注册和浮窗礼包功能，通知CP进行礼包发货，具体接入实现要求参考文档：
https://blog.wing-analytics.com/archives/2510.html#gift_url
4.2.1 在UWingSDK中测试
前提条件：
1. CP已提供礼包通知接口，并且运营已在SDK后台中配置该接口
2. 已经与运营沟通好礼包内容与对应的礼包ID
测试步骤：
1.游戏调用客服中心接口UWingSDK.User.showCustomerCenter()，在测试框中点击“礼包通知发货”
2.在输入礼包ID提示框中，输入与运营约定的礼包ID
3.点击确定后会开始通知已配置在SDK后台的礼包通知接口
4.如果提示成功，则表接口接入正常，按照蓝字提示完成发货即可
5.如果提示异常，请按照提示调整发货接口；同时可以查看调试信息，检查和校对请求时所用的参数（长按输出内容可以进行复制）
测试效果如下：
4.3 AdMob激励广告通知接口
该接口用于SDK的AdMob激励广告功能，通知CP进行激励广告奖励发货，具体接入实现要求参考文档：
https://blog.wing-analytics.com/archives/2510.html#admob
4.3.1 在UWingSDK中测试
前提条件：
1. CP已提供AdMob激励广告通知接口，并且运营已在SDK后台中配置该接口
2. 已经与运营沟通好奖励内容与对应的SDK广告名称
测试步骤：
1.游戏调用AdMob激励广告接口，其传入的adName和extInfo会传递给奖励通知接口
2.弹出激励广告窗口，点击“通知发货”
3.在输入AdMob广告信息提示框中，确认信息正确后点击确定后会开始通知已配置在SDK后台的AdMob激励广告通知接口
4.如果提示成功，则表接口接入正常，按照蓝字提示完成发货即可
5.如果提示异常，请按照提示调整发货接口；同时可以查看调试信息，检查和校对请求时所用的参数（长按输出内容可以进行复制）
测试效果如下：
