谷歌游戏相关功能接入说明

谷歌游戏相关功能接入说明

文档说明

此文档主要是用于在游戏及应用开发商需要接入海外SDK各地区特殊功能时的补充文档。

**请各位根据接入的地区查看需要的接口使用。

1.1 阅读对象

接入海外SDK的游戏及应用的android客户端开发者。

1.2 功能回调

因为此文档内接口回调接口为一个，根据接口内ID区分，所以建议在初始化就注册回调，回调接口使用在每个接口内有具体说明。

 MIDBaseSDK.getInstance(this).MIDBaseSDKSetExtendListener(mBaseExtendListener);

1.3 功能说明

谷歌游戏解锁成就、打开成就弹窗、打开排行榜弹窗、增加排行榜积分功能

1.4 解锁谷歌成就

解锁成就，谷歌成就key在谷歌后台获取。样式举例:”CgkIopmSrtYdEAIQAw”

1.4.1 接口定义


/**
* @param value0 解锁成就固定值
* @param value1 谷歌成就key
*/
MIDBaseSDK.getInstance(this).MIDBaseSDKChannelExtend("GLoginMethodName_Unlock", "CgkIr-GG-IwUEAIQAg");

1.4.2 参数说明

参数名称	重要性	类型	说明
Value0	必传	String	接口ID
Value1	必传	String	谷歌成就key

1.4.3 谷歌成就回调说明

extendListener 接口说明

参数	类型	说明
id	String	解锁成就固定值”GLoginMethodName_Unlock”
values	String数组	values[0] == “0” 解锁成功， values[0] != “0” 解锁失败

// 设置扩展功能回调
MIDBaseSDK.getInstance(this).MIDBaseSDKSetExtendListener(mBaseExtendListener);
/**
* 扩展功能回调
* @param id  功能接口id
* @param values 返回数据
*              values[0] == "0"  解锁成功
*              values[0] !=  "0"  解锁失败
*/
   private MIDBaseExtendListener mBaseExtendListener = new MIDBaseExtendListener() {
        @Override
        public void extendListener(String id, String... values) {
            Logs.i(LOGTAG, "  id:" + id + "  strings[0]:" + values[0]);
            if (id.equals("GLoginMethodName_Unlock")) {
                if (values[0].equals("0")) {
                    Toast.makeText(LTBase_Demo_GoogleGame.this, "解锁成就完成", Toast.LENGTH_SHORT).show();
                } else {
                    Toast.makeText(LTBase_Demo_GoogleGame.this, "解锁成就失败", Toast.LENGTH_SHORT).show();
                }
            }
        }
    };

1.5 成就进度累加

针对有进度的成就系统，累加成就进度。
设置的进度为累加的。
谷歌成就key在谷歌后台获取。样式举例:”CgkIopmSrtYdEAIQAw”

1.5.1 接口定义


/**
* @param value0 解锁成就固定值
* @param value1 谷歌成就key
* @param value1 本次需要增加的进度
*/
MIDBaseSDK.getInstance(this).MIDBaseSDKChannelExtend("GLoginMethodName_Increment", "CgkIr-GG-IwUEAIQAg"，"10");

1.5.2 参数说明

参数名称	重要性	类型	说明
Value0	必传	String	接口ID
Value1	必传	String	谷歌成就key
Value2	必传	String	本次需要增加的进度字符串串类型的数字

1.5.3 谷歌成就回调说明

extendListener 接口说明

参数	类型	说明
id	String	解锁成就固定值”incrementEvent”
values	String数组	values[0] == “0” 解锁成功， values[0] != “0” 解锁失败

// 设置扩展功能回调
MIDBaseSDK.getInstance(this).MIDBaseSDKSetExtendListener(mBaseExtendListener);
/**
* 扩展功能回调
* @param id  功能接口id
* @param values 返回数据
*              values[0] == "0"  解锁成功
*              values[0] !=  "0"  解锁失败
*/
   private MIDBaseExtendListener mBaseExtendListener = new MIDBaseExtendListener() {
        @Override
        public void extendListener(String id, String... values) {
            Logs.i(LOGTAG, "  id:" + id + "  strings[0]:" + values[0]);
            if (id.equals("incrementEvent")) {
                if (values[0].equals("0")) {
                    Toast.makeText(LTBase_Demo_GoogleGame.this, "累加成就完成", Toast.LENGTH_SHORT).show();
                } else {
                    Toast.makeText(LTBase_Demo_GoogleGame.this, "累加成就失败", Toast.LENGTH_SHORT).show();
                }
            }
        }
    };

1.6 打开成就页面

打开成就弹窗

1.6.1 接口定义


/**
* @param value0 打开成就固定值
*/
MIDBaseSDK.getInstance(this).MIDBaseSDKChannelExtend("GLoginMethodName_showAchievements");

1.6.2 参数说明

参数名称	重要性	类型	说明
Value0	必传	String	接口ID

1.7 打开排行榜页面

打开排行榜弹窗

1.7.1 接口定义


/**
* @param value0 打开排行榜固定值
* @param value1 排行榜ID
*/
MIDBaseSDK.getInstance(this).MIDBaseSDKChannelExtend("GLoginMethodName_showLeaderboards", "谷歌游戏后台申请的排行榜id");

1.7.2 参数说明

参数名称	重要性	类型	说明
Value0	必传	String	接口ID
Value1	必传	String	排行榜id

1.8 设置指定排行榜积分

设置指定排行的积分功能。
是修改积分，不是增加.
排行榜积分只能是数字，不带小数点。运营可以在谷歌后台设置积分到小数点后几位。
举例说明：
运营在谷歌后台设置小数点后扩展到4位。游戏想为玩家排行积分设置为：100.0001 需要传入 1000001 中间小数点由谷歌自定添加。

1.8.1 接口定义


/**
* @param value0 修改排行榜接口id
* @param value1 排行榜ID
* @param value2 排行榜积分（只能是数字）
*/
MIDBaseSDK.getInstance(this).MIDBaseSDKChannelExtend("GLoginMethodName_submitScore", "谷歌游戏后台申请的排行榜id","1000001");

1.8.2 参数说明

参数名称	重要性	类型	说明
Value0	必传	String	接口ID
Value1	必传	String	排行榜id
Value2	必传	String	排行积分

1.9 游戏事件，累加事件进度，用于GooglePlay活动

累加指定活动的进度/积分。
对应文档 https://developer.android.com/games/pgs/android/events
eventId 在 Play Console 定义事件时生成。

1.9.1 接口定义


/**
* @param value0 固定值
* @param value1 谷歌游戏后台申请的活动事件id
* @param value2 活动的进度/积分
*/
MIDBaseSDK.getInstance(this).MIDBaseSDKChannelExtend("GLoginMethodName_incrementEvent", "谷歌游戏后台申请的活动事件id","1000001");

1.9.2 参数说明

参数名称	重要性	类型	说明
Value0	必传	String	接口ID 固定值
Value1	必传	String	谷歌游戏后台申请的活动事件id
Value2	必传	String	活动的进度/积分

1.10 上报自定义游戏事件，用于GooglePlay 数据统计

游戏需要根据运营在谷歌后台配置的事件信息，和运营沟通好上报的事件key 和事件值类型。
对应文档 https://developer.android.com/games/pgs/gamestats
用于把游戏内自定义事件（可带属性）上报给 Google 做统计分析。属性 JSON 的值类型自动识别（boolean / 整数 / 小数 / 字符串）。

1.10.1 接口定义

举例 登录事件
/**
* @param value0 固定值
* @param value1 活动名称- 运营配置到谷歌后台的名称
* @param value2 事件属性 - 运营配置到谷歌后台的属性要求
*/
String eventName = "login";
String properties = "{\"userid\":\"user123\",\"username\":\"Player_ABC\"}";
MIDBaseSDK.getInstance(this).MIDBaseSDKChannelExtend(
                "GLoginMethodName_recordGameEvent", eventName, properties);

1.10.2 参数说明

参数名称	重要性	类型	说明
Value0	必传	String	接口ID 固定值
Value1	必传	String	活动名称- 运营配置到谷歌后台的名称
Value2	必传	String	事件属性 - 运营配置到谷歌后台的属性要求

1.11 查询当前登录谷歌账号下、尚未兑换的 GP积分奖励商品

查询当前登录谷歌账号下、尚未兑换的 GP积分奖励商品

1.11.1 接口定义


/**
* @param value0 固定值
*/
MIDBaseSDK.getInstance(context).MIDBaseSDKChannelExtend("GPPlayPointsQuery");

1.11.2 查询回调说明

extendListener 接口说明

参数	类型	说明
id	String	解锁成就固定值”GPPlayPointsQuery “
values	查询到商品数组	没有可兑换商品、或查询失败（未连接谷歌服务等），都回调空数组 []，两种情况不做区分——查询失败不阻塞游戏逻辑，研发按”当前没有可兑换商品”处理即可，可以稍后重试。

商品数组说明

参数	类型	说明
productId	String	Google Play 后台配置的商品ID，固定以 midbase.gpplaypoints 开头
purchaseToken	String	本次购买的唯一凭证，兑换时必须原样传回
orderId	String	Google 订单号，格式如 GPA.xxxx-xxxx-xxxx-xxxxx
purchaseTime	number	购买时间戳，毫秒
purchaseState	number	购买状态，本接口只会返回 1（PURCHASED，已付款完成）
quantity	number	购买数量
acknowledged	boolean	Google 侧是否已确认，不影响能否兑换

示例

[
  {
    "productId": "midbase.gpplaypoints.123",
    "purchaseToken": "opaque-token-abcdef123456",
    "orderId": "GPA.3300-1234-5678-90123",
    "purchaseTime": 1758345600000,
    "purchaseState": 1,
    "quantity": 1,
    "acknowledged": true
  }
]

// 设置扩展功能回调
MIDBaseSDK.getInstance(this).MIDBaseSDKSetExtendListener(mBaseExtendListener);
/**
* 扩展功能回调
* @param id  功能接口id
* @param values 返回数据
*              values[0] == "0"  解锁成功
*              values[0] !=  "0"  解锁失败
*/
   private MIDBaseExtendListener mBaseExtendListener = new MIDBaseExtendListener() {
        @Override
        public void extendListener(String id, String... values) {
            Logs.i(LOGTAG, "  id:" + id + "  strings[0]:" + values[0]);
            if (id.equals("GPPlayPointsQuery")) {
                handleGPPlayPointsQueryResult(strings.length > 0 ? strings[0] : "[]");
            }
        }
    };
// 处理查询到的商品列表
private void handleGPPlayPointsQueryResult(String json) {
            try {
                JSONArray purchases = new JSONArray(json);
                Logs.i(LOGTAG, "GPPlayPointsQuery 结果，共" + purchases.length() + "个: " + json);
                if (purchases.length() == 0) {
                    mLastGPPlayPointsToken = null;
                    Toast.makeText(MIDBase_Demo_GoogleGame.this, "没有待兑换的GP积分奖励商品", Toast.LENGTH_SHORT).show();
                    return;
                }
                // 演示用：记住第一个商品的purchaseToken，方便直接点“兑换奖励商品”按钮测试
                JSONObject first = purchases.getJSONObject(0);
                mLastGPPlayPointsToken = first.getString("purchaseToken");
                Toast.makeText(MIDBase_Demo_GoogleGame.this,
                        "查询到" + purchases.length() + "个奖励商品，productId=" + first.optString("productId"),
                        Toast.LENGTH_SHORT).show();
            } catch (JSONException e) {
                Logs.i(LOGTAG, "GPPlayPointsQuery 结果解析失败: " + e.getMessage());
                Toast.makeText(MIDBase_Demo_GoogleGame.this, "查询结果解析失败", Toast.LENGTH_SHORT).show();
            }
        }

1.12 兑换奖励商品

通知 SDK 消耗一个 GP积分奖励商品

1.12.1 接口定义


/**
* @param value0 固定值
@param value0 purchaseToken  查询到的token
@param value0 roleID  发奖的roleid ，SDK只做打点记录，不判断逻辑。
*/
MIDBaseSDK.getInstance(context).MIDBaseSDKChannelExtend("GPPlayPointsRedeem", purchaseToken, roleID);

1.12.2 查询回调说明

extendListener 接口说明

参数	类型	说明
id	String	解锁成就固定值”GPPlayPointsRedeem “
values	String	兑换结果， JSON格式字符串，见下方字段表

兑换结果说明：

参数	类型	说明
success	boolean	是否兑换（消耗）成功
purchaseToken	String	本次兑换的凭证，原样返回，方便和请求对应
message	String	Google 返回的调试信息，失败时用于排查原因，成功时通常为空

示例：

// 成功
{"success": true, "purchaseToken": "opaque-token-abcdef123456", "message": ""}
// 失败
{"success": false, "purchaseToken": "opaque-token-abcdef123456", "message": "SERVICE_UNAVAILABLE"}

// 设置扩展功能回调
MIDBaseSDK.getInstance(this).MIDBaseSDKSetExtendListener(mBaseExtendListener);
/**
* 扩展功能回调
* @param id  功能接口id
* @param values 返回数据
*              values[0] == "0"  解锁成功
*              values[0] !=  "0"  解锁失败
*/
   private MIDBaseExtendListener mBaseExtendListener = new MIDBaseExtendListener() {
        @Override
        public void extendListener(String id, String... values) {
            Logs.i(LOGTAG, "  id:" + id + "  strings[0]:" + values[0]);
            if (id.equals("GPPlayPointsQuery")) {
                handleGPPlayPointsQueryResult(strings.length > 0 ? strings[0] : "[]");
            } else if (id.equals("GPPlayPointsRedeem")) {
                handleGPPlayPointsRedeemResult(strings.length > 0 ? strings[0] : "");
            }
        }
    };
// 处理兑奖逻辑
private void handleGPPlayPointsRedeemResult(String json) {
            try {
                JSONObject result = new JSONObject(json);
                boolean success = result.optBoolean("success", false);
                String purchaseToken = result.optString("purchaseToken", "");
                String message = result.optString("message", "");
                Logs.i(LOGTAG, "GPPlayPointsRedeem 结果 success=" + success + " token=" + purchaseToken + " msg=" + message);
                if (success) {
                    Toast.makeText(MIDBase_Demo_GoogleGame.this, "兑换成功: " + purchaseToken, Toast.LENGTH_SHORT).show();
                } else {
                    Toast.makeText(MIDBase_Demo_GoogleGame.this, "兑换失败: " + message, Toast.LENGTH_SHORT).show();
                }
            } catch (JSONException e) {
                Logs.i(LOGTAG, "GPPlayPointsRedeem 结果解析失败: " + e.getMessage());
                Toast.makeText(MIDBase_Demo_GoogleGame.this, "兑换结果解析失败", Toast.LENGTH_SHORT).show();
            }
        }

Table of Contents

谷歌游戏相关功能接入说明

文档说明

1.1 阅读对象

1.2 功能回调

1.3 功能说明

1.4 解锁谷歌成就

1.4.1 接口定义

1.4.2 参数说明

1.4.3 谷歌成就回调说明

1.5 成就进度累加

1.5.1 接口定义

1.5.2 参数说明

1.5.3 谷歌成就回调说明

1.6 打开成就页面

1.6.1 接口定义

1.6.2 参数说明

1.7 打开排行榜页面

1.7.1 接口定义

1.7.2 参数说明

1.8 设置指定排行榜积分

1.8.1 接口定义

1.8.2 参数说明

1.9 游戏事件，累加事件进度，用于GooglePlay活动

1.9.1 接口定义

1.9.2 参数说明

1.10 上报自定义游戏事件，用于GooglePlay 数据统计

1.10.1 接口定义

1.10.2 参数说明

1.11 查询当前登录谷歌账号下、尚未兑换的 GP积分奖励商品

1.11.1 接口定义

1.11.2 查询回调说明

1.12 兑换奖励商品

1.12.1 接口定义

1.12.2 查询回调说明