API

API 使用说明

通过 OmniSDK.[API] 实现对应的功能，数据结构存放在 @omnisdk/omnisdk 资源包中。

以调用 OmniSDK 的 login 接口为例：

import { OmniSDK } from '@omnisdk/omnisdk'

OmniSDK.login();

API References

API	Required	Description
onDestroy	true	Ability 销毁时调用
onForeground	true	Ability 进入前台时调用
init	true	初始化 OmniSDK (所有的 API 都必须调用 `init` 成功后才有效)
login	true	调用 OmniSDK 登录，发起账号登录流程
getUserInfo	true	获取用户登录信息
logout	true	调用 OmniSDK 登出，例如在用户点击退出账号时调用
setAccountNotifier	true	设置账号操作相关的结果回调
purchase	true	发起应用内购买流程
setPurchaseNotifier	true	设置支付结果回调
onEnterGame	true	调用华为游戏联运 SDK，上报进入游戏事件
getSDKVersion	false	获取 OmniSDK 的版本号
getChannelId	false	获取 OmniSDK 中的渠道 ID
getChannelName	false	获取 OmniSDK 中的渠道名称
getAppId	false	获取 OmniSDK 中游戏项目的 App ID

生命周期

onDestroy

Ability销毁时调用。

需要在游戏主 UIAbility 组件中对应的生命周期 onDestroy 中调用，且仅需要调用一次。

Signature

public static onDestroy(): void

Sample Code

Show Code

import { OmniSDK } from '@omnisdk/omnisdk';

onDestroy(): void {
    // Ability has been destroy
    super.onDestroy();
    OmniSDK.onDestroy();
}

onForeground

Ability进入前台时调用。

需要在游戏主 UIAbility 组件中对应的生命周期 onForeground 中调用，且仅需要调用一次。

Signature

public static onForeground(): void

Sample Code

Show Code

import { OmniSDK } from '@omnisdk/omnisdk';

onForeground(): void {
    // Ability has brought to foreground
    super.onForeground();
    OmniSDK.onForeground();
}

初始化

init

初始化 OmniSDK，在游戏客户端仅需调用一次。

提示

必须在用户同意游戏侧的用户隐私指引之后调用，避免隐私合规问题。
所有的 OmniSDK API 都必须在调用 init 成功后才能有效。

Signature

public static init(context: common.UIAbilityContext, initOptions: InitOptions) :void

Request

Parameter	Type	Required	Description
context	common.UIAbilityContext	true	UIAbilityContext 是 UIAbility 的上下文环境，提供了访问应用程序资源、启动其他 Ability 等功能的接口
initOptions	InitOptions	true	初始化参数集合

InitOptions

Property	Type	Required	Description
thinkingDataDistinctId	string	true	数数的访客ID
notifier	InitNotifier	true	初始化完成后的回调方法，用于接收初始化的结果

InitNotifier

Property	Type	Description
onSuccess()	function	接收到初始化成功的回调，初始化成功后才可调用 `login` 等其他 API
onFailure( sdkCodeMsg:[number, string], channelCodeMsg?: [number, string] )	function	接收到初始化失败回调： - `sdkCodeMsg`（元组类型）: OmniSDK 方错误码和错误文本信息 - `channelCodeMsg`（元组类型）: 开发者错误码和错误文本信息，用于定位错误

Sample Code

Show Code

import { OmniSDK, InitNotifier, InitOptions } from '@omnisdk/omnisdk';

OmniSDK.init(this.context, new InitOptions('数数 访客ID', {
    onSuccess(): void {
        console.info('初始化成功');
    },
    onFailure(sdkCodeMsg: [number, string], channelCodeMsg?: [number, string]): void {
        console.error(`初始化失败_SDK错误: ${sdkCodeMsg[0]} - ${sdkCodeMsg[1]}`);
        console.error(`初始化失败_渠道错误: ${channelCodeMsg?.[0]} - ${channelCodeMsg?.[1]}`);
    }
}));

账号登录

发起账号登录流程。

Signature

public static login(): void

Sample Code

Show Code

import { OmniSDK } from '@omnisdk/omnisdk';

OmniSDK.login();

logout

登出当前账号。

Signature

public static logout(): void

Sample Code

Show Code

import { OmniSDK } from '@omnisdk/omnisdk';

OmniSDK.logout();

setAccountNotifier

设置账号操作相关的结果回调，需要在调用 login、logout 之前设置。

Signature

public static setAccountNotifier(notifier: AccountNotifier): void

Request

Parameter	Type	Required	Description
notifier	AccountNotifier	true	账号相关回调函数，用于接收处理结果

AccountNotifier

Property	Type	Description
onLoginSuccess()	function	用户登录账号成功
onLogoutSuccess()	function	用户登出账号成功
onFailure( sdkCodeMsg:[number, string], channelCodeMsg?: [number, string] )	function	登录失败处理： - `sdkCodeMsg`（元组类型）: OmniSDK 方错误码和错误文本信息 - `channelCodeMsg`（元组类型）: huawei 渠道的错误码和错误文本信息
onKickedOut(forceLogout: boolean)	function	- `forceLogout`：是否被强制（防沉迷原因，被动切换账号）退出账号

Sample Code

Show Code

import { OmniSDK, AccountNotifier } from '@omnisdk/omnisdk';

OmniSDK.setAccountNotifier({
    onLoginSuccess(): void {
        console.info('登录成功');
    },

    onLogoutSuccess(): void {
        console.info('登出成功');
    },

    onFailure(sdkCodeMsg: [number, string], channelCodeMsg?: [number, string]): void {
        console.error(`SDK错误: ${sdkCodeMsg[0]} - ${sdkCodeMsg[1]}`);
        console.error(`渠道错误: ${channelCodeMsg?.[0]} - ${channelCodeMsg?.[1]}`);
    },

    onKickedOut(force: boolean): void {
        console.warn(force ? '强制登出（防沉迷）' : '渠道主动登出');
    },
});

getUserInfo

在登录成功之后调用，获取登录用户信息参数

Signature

public static getUserInfo(): UserInfo｜undefined

Response

用户未登录，返回 undefined
用户登录成功后，返回 UserInfo

UserInfo

Property	Type	Description
cpUid	string	OmniSDK 返回给游戏的账号 ID
verifySign	string	登录账号数据的验证 Sign 值，出于安全考虑该数据不要进行本地数据库存储
verifyTimestamp	number	验证Sign值产生的Unix时间戳，单位为秒；出于安全考虑该数据不要进行本地数据库存储

Sample Code

Show Code

import { OmniSDK, UserInfo } from '@omnisdk/omnisdk';

const loginInfo = OmniSDK.getUserInfo();
if (loginInfo) {
    let cpUid = loginInfo.cpUid;
    let verifySign = loginInfo.verifySign;
    let verifyTimestamp = loginInfo.verifyTimestamp;
} else {
    console.info("请先登录后再调用");
}

支付

purchase

发起应用内购买流程。

Signature

public static purchase(opts: PurchaseOptions): void

Request

Parameter	Type	Required	Description
opts	PurchaseOptions	true	支付参数集

PurchaseOptions

Property	Type	Required	Description
product	Product	true	商品信息

Product

Property	Type	Required	Description
productId	string	true	商品 ID：与所有后台商品 ID 保持一致，否则渠道无法拉起支付
productName	string	true	商品名称：不能包含特殊字符
productDesc	string	true	商品描述：不能包含特殊字符
productPrice	number	true	商品单价：单位：元
purchaseAmount	number	true	实际支付总额：单位：元
serverId	string	true	服务器 ID：必须为纯数字
roleId	string	true	角色 ID
gameTradeNo	string	true	游戏订单 ID：不可重复的字符串
gameCallbackUrl	string	true	支付回调地址：如果为空字符串，则使用后台配置的回调地址
extJson	string	true	扩展参数：JSON 格式；无传空字符串

Sample Code

Show Code

import { OmniSDK, PurchaseOptions, Product } from '@omnisdk/omnisdk';

let product = new Product(
  "1001",                        // productId
  "钻石礼包",                     // productName
  "内含 100 颗钻石",               // productDesc
  30,                            // productPrice
  30,                            // purchaseAmount
  "1",                           // serverId
  "role_123",                    // roleId
  "order_" + Date.now(),         // gameTradeNo
  "https://example.com/callback",// gameCallbackUrl
  JSON.stringify({
    channel: "huawei",
    campaign: "summer_event"
  })                             // extJson
)
let opts = new PurchaseOptions(product)
OmniSDK.purchase(opts)

setPurchaseNotifier

设置支付结果回调，需要在调用 purchase 之前设置。

Signature

public static setPurchaseNotifier(notifier: PurchaseNotifier): void

Request

Parameter	Type	Required	Description
notifier	PurchaseNotifier	true	账号相关回调函数，用于接收处理结果

PurchaseNotifier

Property	Type	Description
onSuccess(order?: Order)	function	支付成功 - `order`(Order 类型): 订单信息，订单创建成功并正常启动支付模块的情况下一般一定会有；但未知异常下可能无值
onFailure( sdkCodeMsg:[number, string], channelCodeMsg?: [number, string], order?: Order )	function	支付失败处理： - `order`(Order 类型): 订单信息，订单创建成功并正常启动支付模块的情况下一般一定会有；但未知异常下可能无值 - `sdkCodeMsg`(元组类型): OmniSDK 方错误码和错误文本信息 - `channelCodeMsg`(元组类型): huawei 渠道的错误码和错误文本信息

Order

Property	Type	Description
orderId	string	订单 ID
gameTradeNo	string	游戏订单 ID：不可重复的字符串
extJson	string	额外参数信息

Sample Code

Show Code

import { OmniSDK, PurchaseNotifier, Order } from '@omnisdk/omnisdk';

OmniSDK.setPurchaseNotifier({
    onSuccess(order?: Order | undefined): void {
        console.error(`order: ${order?.orderId}`);
    },

    onFailure(sdkCodeMsg: [number, string], channelCodeMsg?: [number, string],
    order?: Order | undefined): void {
        console.error(`支付失败：SDK错误: ${sdkCodeMsg[0]} - ${sdkCodeMsg[1]}`);
        console.error(`渠道错误: ${channelCodeMsg?.[0]} - ${channelCodeMsg?.[1]}`);
        console.error(`order: ${order?.orderId}`);
    }
});

数据上报

onEnterGame

按照华为联运的审核要求，调用华为游戏联运 SDK，上报进入游戏事件。

Signature

public static onEnterGame(roleInfo: RoleInfo): void

Request

Parameter	Type	Required	Description
roleInfo	RoleInfo	true	用户角色信息

RoleInfo

Property	Type	Required	Description
uid	string	true	账号ID
roleId	string	true	角色ID
roleName	string	true	角色名称
serverId	string	true	服ID：必须为纯数字
serverName	string	true	服名称

Sample Code

Show Code

import { OmniSDK, RoleInfo } from '@omnisdk/omnisdk';

OmniSDK.onEnterGame(new RoleInfo('huawei_1111111', '123456', 'test', '1111', 'normal'));

其他

getSDKVersion

获取 OmniSDK 的版本号。

Signature

public static getSDKVersion(): string

Response

返回 OmniSDK 的版本号，示例：0.1.0

Sample Code

Show Code

import { OmniSDK } from '@omnisdk/omnisdk';

let version = OmniSDK.getSDKVersion();

getChannelId

获取 OmniSDK 中的渠道 ID。

Signature

public static getChannelId(): string

Response

返回 OmniSDK 中的渠道 ID，示例：10072

Sample Code

Show Code

import { OmniSDK } from '@omnisdk/omnisdk';

let cid = OmniSDK.getChannelId();

getChannelName

获取 OmniSDK 中的渠道名称。

Signature

public static getChannelName(): string

Response

返回 OmniSDK 中的渠道名称，示例：huawei_harmonyos

Sample Code

Show Code

import { OmniSDK } from '@omnisdk/omnisdk';

let cName = OmniSDK.getChannelName();

getAppId

获取 OmniSDK 中游戏项目的 App ID。

Signature

public static getAppId(): string

Response

返回 OmniSDK 中游戏项目的 App ID，示例：15985

Sample Code

Show Code

import { OmniSDK, RoleInfo } from '@omnisdk/omnisdk';

let appId = OmniSDK.getAppId();

ErrorCode

Code	Description
400	网络异常
500	未知错误
999	无结果数据
100000	初始化失败
100010	登录失败
100090	登录取消
200050	支付失败
200010	支付取消
200053	创建订单失败
200054	商品信息错误

API 使用说明​

API References​

生命周期​

onDestroy​

Signature​

Sample Code​

onForeground​

Signature​

Sample Code​

初始化​

init​

Signature​

Request​

InitOptions​

InitNotifier​

Sample Code​

账号登录​

login​

Signature​

Sample Code​

logout​

Signature​

Sample Code​

setAccountNotifier​

Signature​

Request​

AccountNotifier​

Sample Code​

getUserInfo​

Signature​

Response​

UserInfo​

Sample Code​

支付​

purchase​

Signature​

Request​

PurchaseOptions​

Product​

Sample Code​

setPurchaseNotifier​

Signature​

Request​

PurchaseNotifier​

Order​

Sample Code​

数据上报​

onEnterGame​

Signature​

Request​

RoleInfo​

Sample Code​

其他​

getSDKVersion​

Signature​

Response​

Sample Code​

getChannelId​

Signature​

Response​

Sample Code​

getChannelName​

Signature​

Response​

Sample Code​

getAppId​

Signature​

Response​

Sample Code​

ErrorCode​

API 使用说明

API References

生命周期

onDestroy

Signature

Sample Code

onForeground

Signature

Sample Code

初始化

init

Signature

Request

InitOptions

InitNotifier

Sample Code

账号登录

login

Signature

Sample Code

logout

Signature

Sample Code

setAccountNotifier

Signature

Request

AccountNotifier

Sample Code

getUserInfo

Signature

Response

UserInfo

Sample Code

支付

purchase

Signature

Request

PurchaseOptions

Product

Sample Code

setPurchaseNotifier

Signature

Request

PurchaseNotifier

Order

Sample Code

数据上报

onEnterGame

Signature

Request

RoleInfo

Sample Code

其他

getSDKVersion

Signature

Response

Sample Code

getChannelId

Signature

Response

Sample Code

getChannelName

Signature

Response

Sample Code

getAppId

Signature

Response

Sample Code

ErrorCode