一、导入SDK资源

1.1 将 gamesdkLibrary.har 包放在⼯程的 libs ⽬录下：

1.2 在 App Module 的 oh-package.json5中，添加依赖项：

"dependencies": {
"gamesdklibrary": "file:./libs/gamesdkLibrary.har"
}

如下图：

1.3 在 App Module 的 module.json5中，配置⽹络访问权限：

"requestPermissions": [

{
"name": "ohos.permission.INTERNET"

}],

如下图：

鸿蒙上架与隐私合规： 请在应⽤《隐私政策》中补充 HarmonyOS 端 个⼈信息收集与 权限列表（权限名称请使⽤ ohos.permission.* 系统常量全称），并与随 SDK 提供的 gamesdkLibrary 包内《SDK 合规使⽤指南》 及仓库 QuickGameSDK鸿蒙-权限说明表.md 保持⼀致；含可选能⼒关闭⽅式、权限申请时机及向⽤户披露的示例条款。完整模板⻅ gamesdk/gamesdkLibrary/SDK合规使⽤指南.md

1.4 在项⽬级 build-profile.json5 中开启 useNormalizedOHMUrl （必须）：
如果接⼊⽅使⽤的是字节码 HAR（本 SDK 默认发布形态）， useNormalizedOHMUrl 不是 true 会在编译时报错：
Bytecode HARS ... not supported when useNormalizedOHMUrl is not true

{
   "app": {
       "products": [
        {
           "name": "default",
           "buildOption": {
               "strictMode": {
                  "useNormalizedOHMUrl": true
           }
        }
      }
    ]
  }
}

说明：
该配置应写在项⽬级 build-profile.json5 （不是 module 级）
如果项⽬有多个 product ，请在实际构建使⽤的 product 下都保持为 true

1.5 在 App Module 的 module.json5的module节点增加如下client_id和app_id属性配置，⽤于华为登录和内购的应⽤身份鉴权：
 
"metadata": [
 {
 "name": "client_id",
 "value": "xxxxxxxxx"
 },
 {
 "name": "app_id",
 "value": "xxxxxxxxx"
 }
 ]

 
如下图：

1.6 华为后台获取Client ID和APP ID：

二、导入SDK接口

import { GameSDKManager, DialogView,DialogViewController, GameSDKUser,GameSDKRoleInfo, GameSDKOrderInfo, NotificationCenter, GameSDKCallBackData} from 'gamesdklibrary'

三、接口调⽤

3.1 创建接口实例对象

// 创建GameSDKManager实例对象 ,参数传SDK后台的productCode参数
gamesdkInstance: GameSDKManager =
GameSDKManager.getInstance('44021448506430380961470188790224')

3.2 初始化接口

this.gamesdkInstance.initWithProductCode('44021448506430380961470188790224')

3.3 华为账号登录接口

//打开华为登录界⾯
this.gamesdkInstance.huaweiLogin(this.getUIContext())

华为后台需要添加公钥指纹，同时这⾥的证书需要和研发⼯程⾥使⽤的证书保持⼀致

SDK后台游戏管理 -功能配置⾥需配置鸿蒙参数

3.4 支付接口

//创建订单数据对象
let orderInfo: GameSDKOrderInfo = {
productId:'testProductId',
productName: 'testProductName',
cpOrderID: 'testCpOrderID',
amount: ‘6’,//单位元
callbackUrl: 'testCallbackUrl', //如果游戏下单时设置支付回调，建议支付回调地址加上IP白名单，防止被攥改！！！
extrasParams: 'testExtrasParams',
productType: '0' //商品类型（可选，默认"0"）："0"消耗型, "1"⾮消耗型, "2"⾃动续期订阅, "3"⾮续期订
阅
}
//调⽤⽀付
this.gamesdkInstance.payWithOrderInfo(orderInfo)

productType 取值说明：

值	类型	说明
"0"	消耗型	可重复购买的商品（如钻⽯、⾦币），默认值
"1"	⾮消耗型	⼀次性购买的商品（如去⼴告、永久解锁⻆⾊）
"2"	⾃动续期订阅	⾃动续费型订阅（如⽉卡、VIP 会员）
"3"	⾮续期订阅	固定时⻓、不⾃动续费的订阅（如 30 天体验卡）

华为后台开通应⽤内购买服务

SDK后台游戏管理  -> ⽀付通道 里需添加鸿蒙⽀付并配置参数：

注意：
1. 沙盒测试需要在华为后台添加测试账号，同时测试设备的系统设置⾥⾯需要登录该账号
2. 华为后台的商品id状态处于"草稿"状态不能测试，必须是"待提交"或者"审核通过"的状态
3. SDK后台需正确配置包名，商品id，商品⾦额，否则⽀付完成⽆法到账

  
3.5 查询订阅状态接⼝（选接）

当使⽤⾃动续期订阅（productType="2"）时，可通过此接⼝查询⽤户当前的订阅状态

//查询订阅状态，参数为业务⾃定义的订阅组标识，会透传到回调中
this.gamesdkInstance.querySubscriptionStatus('mySubGroupId')

查询结果通过 GAMESDK_NOTIFICATION_KEY_SUBSCRIPTION_STATUS 回调通知返回，见下方"注册SDK回调通知"章节

3.6 上传⾓⾊接口

//创建⻆⾊数据对象
let roleInfo: GameSDKRoleInfo = {
roleId:'testRoleId',
roleName: 'testRoleName',
serverId: 'testServerId',
serverName: 'testServerName',
roleLevel: 'testRoleLevel',
vipLevel: 'testVipLevel'
}
//上传游戏⻆⾊
this.gamesdkInstance.updateRoleInfo(roleInfo)

3.7 隐私弹窗接口

//打开隐私弹窗
this.gamesdkInstance.openPrivacyDialog(this.getUIContext())

3.8 解绑华为账号接⼝

//如果是华为⽤户登录可解绑
if (this.gamesdkInstance.isHuaweiUser()) {
 this.gamesdkInstance.unbindHuaweiAccount()
}

3.9 退出登录接⼝

this.gamesdkInstance.logout()

3.10 去掉游戏官⽅账号登录接⼝

//⽆官包体系的游戏，可以调这个接⼝来关闭游戏官⽅账号登录，需在登录之前调⽤
this.gamesdkInstance.enableGameOfficeLogin(false)

3.11 设置游戏官⽅账号登录按钮⽂案接⼝

说明：华为联合登录⾯板中，第三⽅游戏官⽅账号⼊⼝的展示名称由gamePlayer.ThirdAccountInfo.accountName 传⼊，SDK 默认⽂案为「游戏官⽅账号登录」。若需改为「xx游账号登录」「xx通⾏证登录」等，可在调⽤ huaweiLogin / 触发联合登录前调⽤本接⼝。⽂案会先 trim() ，若为空则恢复默认

// 需在华为账号登录前调⽤
this.gamesdkInstance.setOfficialAccountLoginButtonText('XX账号登录（官服）')

3.12 HarmonyOS 5.0与HarmonyOS 4及以下账号互通

说明：华为转移登录时，HarmonyOS 4及以下游戏的玩家标识应与HarmonyOS 5.0及以上游戏的玩家标识gamePlayerId建⽴映射

1. 前往AppGallery Connect配置新⽼系统游戏的APP ID映射关系
参考华为⽂档： https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/gameservice-gameplayer-huawei#section3907114313255

2. 处理登录回调返回的gamePlayerId 

 
当gamePlayerId不为空值时，代表华为转移⽤户登录，即该玩家是之前在HarmonyOS 4及以下游戏的玩家，此时需要实现和HarmonyOS 4及以下系统上游戏内资产互通。这⾥返回的gamePlayerId就是安卓华为渠道的uid，通过判断gamePlayerId和安卓华为渠道的uid值是否⼀样，值⼀样就互通游戏内资产。如果安卓华为渠道的uid拼接了渠道号，那么gamePlayerId需要拼接同⼀个渠道号

判断是否华为转移⽤户接口

//是否华为转移⽤户
this.gamesdkInstance.isHuaweiTransferAccount()

3.13 绑定⼿机号接口（选接）

两种接⼊⽅式：
1. SDK ⾃带 UI： bindPhone(uiContext) 拉起 SDK 弹窗；个⼈中⼼ H5 内绑定/换绑仍⾛ SDK UI
2. 游戏⾃建 UI：只调⽆界⾯ API（发码 / 绑定 / 换绑 / 解绑），结果看返回值，也可继续监听下⽅通知

import { BoundPhoneApiResult } from 'gamesdklibrary'
// 查询是否已绑定 / 已绑定号码（脱敏或明⽂）
const bound = this.gamesdkInstance.isBindPhone()
const mobile = this.gamesdkInstance.getBoundPhone()
// —— ⽅式⼀：拉起 SDK 绑定界⾯（未登录或已绑定时内部直接 return）——
this.gamesdkInstance.bindPhone(this.getUIContext())
// —— ⽅式⼆：游戏⾃建⻚⾯（⽆ UI）——
// ⾸次绑定：发码(sendType=2) → 提交
const send1: BoundPhoneApiResult = await
this.gamesdkInstance.sendBindSmsCode('13800138000')
const bind1: BoundPhoneApiResult = await
this.gamesdkInstance.bindPhoneWithCode('13800138000', '123456')
// 换绑：旧机发码(sendType=3) → 校验旧机 → 新号发码(sendType=2) → 提交换绑
await this.gamesdkInstance.sendVerifyBoundSmsCode()
await this.gamesdkInstance.verifyBoundPhoneForRebind('123456')
await this.gamesdkInstance.sendBindSmsCode('13900139000')
await this.gamesdkInstance.reBindPhoneWithCode('13900139000', '654321')
// 解绑：旧机发码 → 提交解绑（成功后 SDK ⾃动 logout，并抛出 UNBIND_MOBILE_SUCCESS + 
LOGOUT_SUCCESS）
await this.gamesdkInstance.sendVerifyBoundSmsCode()
await this.gamesdkInstance.unBindPhoneWithCode('123456')

注册绑定结果回调（须在初始化后、调⽤绑定相关接⼝前注册）：

import {
NotificationCenter,
GAMESDK_NOTIFICATION_KEY_BIND_MOBILE_SUCCESS,
GAMESDK_NOTIFICATION_KEY_BIND_MOBILE_FAIL,
GAMESDK_NOTIFICATION_KEY_UNBIND_MOBILE_SUCCESS,
} from 'gamesdklibrary'
NotificationCenter.getInstance().addObserver(
GAMESDK_NOTIFICATION_KEY_BIND_MOBILE_SUCCESS,
 (data) => {
// ⾸次绑定与换绑成功均⾛此通知；换绑时 message 可能为 rebind phone success
console.log(`绑定/换绑⼿机成功 uid:${data.uid} mobile:${data.mobile}
message:${data.message}`)
 }
)
NotificationCenter.getInstance().addObserver(
GAMESDK_NOTIFICATION_KEY_BIND_MOBILE_FAIL,
 (data) => {
console.log(`绑定/换绑⼿机失败:${data.message}`)
 }
)
NotificationCenter.getInstance().addObserver(
GAMESDK_NOTIFICATION_KEY_UNBIND_MOBILE_SUCCESS,
 (data) => {
// 纯解绑⼿机成功（随后 SDK 会退出登录并抛出 LOGOUT_SUCCESS）
console.log(`解绑⼿机成功 uid:${data.uid}`)
 }
)
  

说明：

1. BoundPhoneApiResult ： success / message / 可选 code 、 mobile 、 uid 。⾃建 UI 以返回值为准；通知⽤于与个⼈中⼼等路径统⼀监听。发码仅看返回值，⽆单独发码通知
2. GAMESDK_NOTIFICATION_KEY_BIND_MOBILE_SUCCESS ：覆盖⾸次绑定与换绑成功（含个⼈中⼼与⾃建UI）
3. GAMESDK_NOTIFICATION_KEY_BIND_MOBILE_FAIL ：绑定/换绑提交失败（含已绑定等业务失败）；参数校验类失败（如⼿机号位数不对）通常只体现在返回值
4. 个⼈中⼼ H5： showBindPhone / showUnBindPhone / switchBindPhone 仍打开 SDK 弹窗，与⾃建 UI 可并存
5. 换绑须先 verifyBoundPhoneForRebind 成功再 reBindPhoneWithCode 。纯解绑：⼿机号注册⽤户（ isMbUser ）仍不⽀持。登出后换绑校验态会清空
6. GAMESDK_NOTIFICATION_KEY_UNBIND_MOBILE_SUCCESS ：仅纯解绑⼿机成功；成功后会登出，请同时关注LOGOUT_SUCCESS 。与解绑华为账号的 UNBIND_SUCCESS 不同，请勿混淆

3.14 打开个⼈中⼼接⼝（选接）

须已登录。个⼈中⼼为 H5 ⻚⾯，内含绑定/换绑⼿机、切换账号等能⼒；绑定或换绑成功后 SDK 会⾃动刷新个⼈中⼼⻚⾯

this.gamesdkInstance.openUserCenter(this.getUIContext())

3.15 打开云客服接⼝

需先联系商务开通Quick云客服产品，获取客服产品code，将产品code传⼊客服接⼝

//打开云客服，参数传云客服后台的产品code
this.gamesdkInstance.openServiceCenter(this.getUIContext(),
'11145220560844xxxxxxxxxxxxxxx')

3.16 初始化窗⼝对象，需在Ability的onWindowStageCreate中调⽤如下⽅法

windowStage.getMainWindow((err, data) => {
     if (err.code) {
       console.error('获取失败' + JSON.stringify(err));
       return;
     }
     console.info('获取主窗⼝的实例：' + JSON.stringify(data));
     globalThis.windowClass = data // 赋值给全局变量windowClass
   });

如下图：

3.17 注册SDK回调通知

//注册SDK初始化回调事件
NotificationCenter.getInstance().addObserver('GAMESDK_NOTIFICATION_KEY_INIT_SUCCESS', 
(data: GameSDKCallBackData) => {
console.log(`SDK初始化成功：message:${data.message}`)
 });
//注册SDK登录回调事件
NotificationCenter.getInstance().addObserver('GAMESDK_NOTIFICATION_KEY_LOGIN_SUCCESS', 
(data: GameSDKCallBackData) => {
//回调返回⽤户信息：
console.log(`SDK登录成功：uid:${data.uid}, userName:${data.userName}, 
token:${data.token}, gamePlayerId:${data.gamePlayerId},`)
//通过GameSDKUser⽤户类获取⽤户信息
promptAction.showDialog({ message: `uid:${GameSDKUser.getInstance().uid}, 
userName:${GameSDKUser.getInstance().userName}, token:${GameSDKUser.getInstance().token}`
})
//HarmonyOS 4及以下游戏的玩家标识openId/playerId，如何与HarmonyOS 5.0及以上游戏的玩家标识
gamePlayerId建⽴映射
//1. 前往AppGallery Connect配置新⽼系统游戏的APP ID映射关
系,https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/gameservice-gameplayerhuawei#section3907114313255
//2. 当回调⾥的gamePlayerId不为空值时，代表华为转移⽤户登录，即该玩家是之前在HarmonyOS 4及以下游戏
的玩家，此时需要实现和HarmonyOS 4及以下系统上游 戏内资产互通。这⾥返回的gamePlayerId就是安卓华为
渠道的uid，通过判断gamePlayerId和安卓华为渠道的uid值是否⼀样，值⼀样就互通游戏内资产。
//3. 如果安卓华为渠道的uid拼接了渠道号，那么gamePlayerId需要拼接同⼀个渠道号。
 });
//注册SDK⽀付成功回调事件
NotificationCenter.getInstance().addObserver('GAMESDK_NOTIFICATION_KEY_PAY_SUCCESS', 
(data: GameSDKCallBackData) => {
//回调返回⽀付成功信息：
console.log(`SDK⽀付成功:${data.message}：orderNo:${data.orderNo}, 
productId:${data.productId}, extrasParams:${data.extrasParams}`)
 });
//注册SDK⽀付失败回调事件
NotificationCenter.getInstance().addObserver('GAMESDK_NOTIFICATION_KEY_PAY_FAIL', (data: 
GameSDKCallBackData) => {
//回调返回⽀付失败信息：
console.log(`SDK⽀付失败:${data.message}：orderNo:${data.orderNo}, 
productId:${data.productId}, extrasParams:${data.extrasParams}`)
 });
//注册隐私弹窗同意回调事件
NotificationCenter.getInstance().addObserver('GAMESDK_NOTIFICATION_KEY_AGREE_PRIVACY', 
(data: GameSDKCallBackData) => {
console.log(`点击了同意隐私协议：message:${data.message} 
,isAgreePrivacy:${data.isAgreePrivacy}`)
 });
//注册隐私弹窗不同意回调事件
NotificationCenter.getInstance().addObserver('GAMESDK_NOTIFICATION_KEY_REFUSE_PRIVACY', 
(data: GameSDKCallBackData) => {
console.log(`点击了不同意隐私协议：message:${data.message} 
,isAgreePrivacy:${data.isAgreePrivacy}`)
 });
//注册退出登录回调事件
NotificationCenter.getInstance().addObserver('GAMESDK_NOTIFICATION_KEY_LOGOUT_SUCCESS', 
(data: GameSDKCallBackData) => {
console.log(`退出登录成功`)
 });
//注册订阅状态查询回调事件（使⽤⾃动续期订阅时需要）
NotificationCenter.getInstance().addObserver('GAMESDK_NOTIFICATION_KEY_SUBSCRIPTION_STATUS
', (data: GameSDKCallBackData) => {
console.log(`订阅状态查询结果：subGroupId=${data.subGroupId}, code=${data.code}, 
message=${data.message}`)
if (data.subscriptions) {
data.subscriptions.forEach((sub) => {
console.log(`订阅条⽬：productId=${sub.productId}, status=${sub.status}, 
expirationDate=${sub.expirationDate}`)
 })
 }
 });
//注册解绑华为账号回调事件
NotificationCenter.getInstance().addObserver('GAMESDK_NOTIFICATION_KEY_UNBIND_SUCCESS', 
(data: GameSDKCallBackData) => {
console.log(`华为账号解绑成功`)
 });
//注册华为登录失败回调事件
NotificationCenter.getInstance().addObserver('GAMESDK_NOTIFICATION_KEY_HUAWEILOGIN_FAIL', 
(data: GameSDKCallBackData) => {
console.log(`华为登录失败`)
if (data.code === 1002000016) {//⽤户点击关闭华为登录框
console.log(`⽤户点击关闭华为登录框`)
 }
 });
//注册绑定⼿机号成功回调（含换绑成功）
NotificationCenter.getInstance().addObserver(GAMESDK_NOTIFICATION_KEY_BIND_MOBILE_SUCCESS, 
(data: GameSDKCallBackData) => {
console.log(`绑定/换绑⼿机成功：uid:${data.uid}, mobile:${data.mobile}, 
message:${data.message}`)
 });
//注册绑定⼿机号失败回调
NotificationCenter.getInstance().addObserver(GAMESDK_NOTIFICATION_KEY_BIND_MOBILE_FAIL, 
(data: GameSDKCallBackData) => {
console.log(`绑定/换绑⼿机失败：${data.message}`)
 });
//注册解绑⼿机号成功回调（纯解绑；与华为账号 UNBIND_SUCCESS 不同）
NotificationCenter.getInstance().addObserver(GAMESDK_NOTIFICATION_KEY_UNBIND_MOBILE_SUCCES
S, (data: GameSDKCallBackData) => {
console.log(`解绑⼿机成功：uid:${data.uid}`)
 });

注意：为防止账号信息被篡改，游戏客户端获取到登录成功的回调后，需将回调里的uid跟token发送给游戏服务器端进行验证，具体操作详见QuickGameSDK服务器接入文档

四、其他接⼝（选接）

4.1 初始化微信QQ登录（选接）

//初始化微信登录
this.gamesdkInstance.initWxLogin("wxd6bxxxxxxxxxxx", "8606969ec8eb7ebxxxxxxxxxxxxx")
//初始化QQ登录
this.gamesdkInstance.initQQLogin("1022xxxxxx", "iNr8Hxxxxxxxx")
//在EntryAbility中响应来⾃微信/QQ的回调（须传⼊ this.context，热启动 onNewWant 同理；
onNewWant(want: Want, launchParam: AbilityConstant.LaunchParam): void {
GameSDKManager.getInstance('').handleAuthResult(want, this.context)
}

发⾏包裁剪说明： 

若商务提供的 HAR 为裁剪版（ build_info.json 中 includeWx=false / includeQQ=false ），则对应 OpenSDK 未编⼊发⾏包。此时请勿调⽤ initWxLogin / initQQLogin ，且module.json5 中 ⽆需 配置 weixin / qqopenapi 的 querySchemes 与 QQ AppLink；仅保留实际接⼊的第三⽅ scheme

微信 OpenSDK 版本： 接⼊微信登录时，⼯程依赖 @tencent/wechat_open_sdk 须为 1.0.20 及以上（发⾏包 / Demo 已按此版本锁定）。 module.json5 的 querySchemes 须包含 weixin （建议同时保留wxopensdk 若⽂档或模板已列出）

另注意：

微信登录时⼯程需要使⽤⼿动签名，不然会报错："由于应⽤BundleID信息校验不通过，⽆法使⽤微信登录"
QQ后台需要正确配置鸿蒙应⽤签名，不然会报错："error authResponse is null"
参考⽂档：https://wiki.connect.qq.com/harmonyos_sdk%e5%b8%b8%e8%a7%81%e9%97%ae%e9%a2%98

QQ后台AppLinking状态需要验证通过

module.json5 配置⽂件修改

// module.json5 的"module"节点下配置 querySchemes
"querySchemes": [
   "https",
   "qqopenapi",
   "weixin"
]  
// 在 Ability 的 skills 节点中配置scheme
"skills": [
{
   "entities": [
     "entity.system.browser"
   ],
   "actions": [
     "ohos.want.action.viewData"
   ],
   "uris": [
     {
       "scheme": "qqopenapi", // 接收 QQ 回调数据
       "host": "（替换申请的互联 appId）", // 业务申请的互联 appId，如果填错会导致 QQ ⽆法回调
       "path": "auth",
       "linkFeature": "Login",
     }
   ]
}
]

如下图：

在业务 Ability.onNewWant() 中调⽤SDK如下⽅法：

//在EntryAbility中响应来⾃微信/QQ的回调
GameSDKManager.getInstance('').handleAuthResult(want)

4.2 SDK域名配置（选接）

当需要修改sdk的默认域名时，可通过配置⽂件或代码接⼝两种⽅式设置SDK主接⼝地址

⽅式⼀：修改配置⽂件

打开⼯程找到sdk配置⽂件，⽂件路径：oh_modules/gamesdklibrary/src/main/resources/rawfile/sdk_config.json，然后修改⽂件中mainurl对应的value值

⽅式⼆：调⽤接⼝动态设置

//设置SDK主接⼝地址，需在初始化前调⽤
this.gamesdkInstance.setApiBaseUrl('https://sdkapi.example.com')
//再调⽤初始化
this.gamesdkInstance.initWithProductCode('44021448506430380xxxxxxxxxxxxx')

说明：
1. mainurl ⽤于配置SDK主接⼝默认域名
2. setApiBaseUrl() ⽤于运⾏时动态设置SDK主接⼝地址，建议在初始化前调⽤
3. 优先级： setApiBaseUrl() 设置的地址 > sdk_config.json 中的 mainurl > SDK默认地址