跳到主要内容

API

接口概要​

APIDescription
omnisdk_start初始化 OmniSDK (所有的 API 都必须调用 Start 成功后才有效)
omnisdk_login调用 OmniSDK 登录，弹出登录窗口
omnisdk_logout当前用户退出登录
omnisdk_purchase调用 OmniSDK 购买，弹出购买窗口
omnisdk_get_login_info获取用户登录信息

接口定义​

omnisdk_start​

启动SDK。

警告
  • omnisdk_start 方法是启动 OmniSDK 的关键步骤，它必须在所有其它 OmniSDK API 调用之前被执行。
  • 接入方需要尽早调用 Start，如果失败，建议后续登录流程不需要再执行。
  • omnisdk_start 方法调用时会进行 Webview2 Runtime 环境检查，如环境检查失败则通过 omnisdk_delegate.on_start 返回 EnvironmentError 错误信息，建议游戏侧捕获此错误并弹出提示引导用户安装 Webview2 Evergreen Runtime 环境。

签名​

void omnisdk_start(HWND hwnd, struct omnisdk_start_options* options, void* userptr = NULL);

参数​

参数类型描述
hwndHWND[In] 父窗口的句柄，通常是游戏的主窗口。OmniSDK 的界面将在此窗口中显示
optionsstruct omnisdk_start_options*[In] 用于初始化 SDK 所需的配置项。其中包括应用ID、事件回调等
userptrvoid*[In, Optional] 用户提供的一个任意指针。它可以用于在 omnisdk_delegate.on_start 回调函数中传递用户数据，以实现更灵活的程序设计

回调​

通过 omnisdk_delegate.on_start 返回结果

参数类型描述
resultstruct omnisdk_start_result*start 成功后返回的结果
errorstruct omnisdk_error*start 失败后返回的错误
userptrvoid*omnisdk_start 传入的用户指针

用例​

Show Code 
void omnisdk_on_start(struct omnisdk_start_result* result, struct omnisdk_error* error, void* userptr) {
    auto r = result;
    auto e = error;
}

void omnisdk_on_login(struct omnisdk_login_result* result, struct omnisdk_error* error, void* userptr) {
    auto r = result;
    auto e = error;
}

void omnisdk_on_logout(struct omnisdk_logout_result* result, struct omnisdk_error* error, void* userptr) {
    auto r = result;
    auto e = error;
}

void omnisdk_on_purchase(struct omnisdk_purchase_result* result, struct omnisdk_error* error, void* userptr) {
    auto r = result;
    auto e = error;
}

// 初始化示例函数
void init_example_proc() {
    omnisdk_start_options start_options;
    start_options.app_id = L"15023";
    start_options.app_key = L"x5cr9d1fx1839d4s";
    start_options.bundle_id = L"com.seayoo.demo";
    start_options.bundle_version = L"1.0.0.1";
    start_options.delegate.on_start = &omnisdk_on_start;
    start_options.delegate.on_login = &omnisdk_on_login;
    start_options.delegate.on_purchase = &omnisdk_on_purchase;
    start_options.delegate.on_logout = &omnisdk_on_logout;
    omnisdk_start(g_hWnd, &start_options);
}

omnisdk_login​

发起登录请求。

警告
  • omnisdk_login 方法必须在 omnisdk_start 成功后执行，否则会引起 ApiCallError。
  • 通常在点击进入游戏按钮时调用。

签名​

void omnisdk_login(struct omnisdk_login_options* options, void* userptr = NULL);

参数​

参数类型描述
optionsomnisdk_login_options*[In] 用于登录所需的配置项，包括 Plan ID 、验证方式等
userptrvoid*[In, Optional] 用户提供的一个任意指针。它可以用于在 omnisdk_delegate.on_login 回调函数中传递用户数据，以实现更灵活的程序设计

回调​

通过 omnisdk_delegate.on_login 返回结果

参数类型描述
resultstruct omnisdk_login_result*login 成功后返回的结果
errorstruct omnisdk_error*login 失败后返回的错误
userptrvoid*omnisdk_login 传入的用户指针

用例​

Show Code 
// 登录处理示例函数
void login_btn_example_proc() {
    omnisdk_login_options login_options;
    login_options.plan_id = L"80061";
    login_options.channel_id = L"jinshan";
    login_options.auth_method = OMNISDK_AUTH_METHOD_GUEST;
    omnisdk_login(&login_options);
}

omnisdk_logout​

发起登出请求。

警告
  • omnisdk_logout 方法必须在 omnisdk_start 成功后执行，否则会引起 ApiCallError。
  • 通常在点击登出按钮时调用。

签名​

void omnisdk_logout(void* userptr = NULL);

参数​

参数类型描述
userptrvoid*[In, Optional] 用户提供的一个任意指针。它可以用于在 omnisdk_delegate.on_logout 回调函数中传递用户数据，以实现更灵活的程序设计

回调​

通过 omnisdk_delegate.on_logout 返回结果

参数类型描述
resultstruct omnisdk_logout_result*login 成功后返回的结果
errorstruct omnisdk_error*login 失败后返回的错误
userptrvoid*omnisdk_logout 传入的用户指针

用例​

Show Code 
// 登出处理示例函数
void logout_btn_example_proc() {
    omnisdk_logout();
}

omnisdk_purchase​

发起购买商品请求。

警告
  • omnisdk_purchase 方法必须在 omnisdk_start 成功后执行，否则会引起 ApiCallError。
  • 通常在点击购买按钮时调用。

签名​

void omnisdk_purchase(struct omnisdk_purchase_options* options, void* userptr = NULL);

参数​

参数类型描述
optionsomnisdk_purchase_options*[In] 包含了与购买操作相关的选项，如商品ID、价格、游戏角色 ID等
userptrvoid*[In, Optional] 用户提供的一个任意指针。它可以用于在 omnisdk_delegate.on_purchase 回调函数中传递用户数据，以实现更灵活的程序设计

回调​

通过 omnisdk_delegate.on_purchase 返回结果

参数类型描述
resultstruct omnisdk_purchase_result*purchase 成功后返回的结果
errorstruct omnisdk_error*purchase 失败后返回的错误
userptrvoid*omnisdk_purchase 传入的用户指针

用例​

Show Code 
// 获取已登录用户信息示例函数
void get_login_info_example_proc() {
    omnisdk_purchase_options purchase_options;
    purchase_options.product_id = itemIdStr;
    purchase_options.product_name = productNameStr;
    purchase_options.product_desc = const_cast<wchar_t*>(L"test item");
    purchase_options.product_unit = const_cast<wchar_t*>(L"piece");
    purchase_options.product_unit_price = payAmount;
    purchase_options.purchase_amount = payAmount;
    purchase_options.purchase_quantity = 1;
    purchase_options.purchase_callback_url = callbackServerStr;
    purchase_options.game_order_id = gameOrderIdStr;
    purchase_options.ext_json = const_cast<wchar_t*>(L"{}");
    purchase_options.game_role_id = const_cast<wchar_t*>(L"role_01");
    purchase_options.game_role_name = const_cast<wchar_t*>(L"AwesomePlayer");
    purchase_options.game_role_level = const_cast<wchar_t*>(L"10");
    purchase_options.game_role_vip_level = const_cast<wchar_t*>(L"5");
    purchase_options.game_zone_id = const_cast<wchar_t*>(L"zone_01");
    purchase_options.game_server_id = const_cast<wchar_t*>(L"server_01");
    omnisdk_purchase(&purchase_options);
}

omnisdk_get_login_info​

获取登录信息。

警告

omnisdk_get_login_info 需要在成功登录后才能正确获取到用户信息，否则 omnisdk_login_info* 中的字段将被设置为 NULL。

签名​

void omnisdk_get_login_info(struct omnisdk_login_info* rinfo);

参数​

参数类型描述
rinfostruct omnisdk_login_info*[Out] 指向接收登录信息的结构体指针

用例​

Show Code 
// 获取已登录用户信息示例函数
void get_login_info_example_proc() {
    omnisdk_login_info rinfo;
    omnisdk_get_login_info(&rinfo);
    std::wcout << L"user login: " << rinfo.user_id << std::endl;
}

数据结构定义​

struct omnisdk_start_options​

相关接口：omnisdk_start

初始化 OmniSDK 所需的配置项。

参数​

名称类型描述
delegatestruct omnisdk_delegate用于接收 OmniSDK 的事件回调协议
bundle_idconst wchar_t*软件包 ID
bundle_versionconst wchar_t*软件包版本
app_idconst wchar_t*OmniSDK App Id
app_keyconst wchar_t*OmniSDK App Key

声明​

Show Code 
struct omnisdk_start_options {
    struct omnisdk_delegate delegate;
    const wchar_t* bundle_id = NULL;
    const wchar_t* bundle_version = NULL;
    const wchar_t* app_id = NULL;
    const wchar_t* app_key = NULL;
};

struct omnisdk_delegate​

相关接口：omnisdk_start；omnisdk_login；omnisdk_logout；omnisdk_purchase

接收 OmniSDK 的事件回调协议。

危险

所有的回调均为异步，请确保所传入的回调函数指针在 OmniSDK 执行的整个生命周期内有效！如传入的回调函数所在的区域（比如动态库）被卸载，或者函数是一个局部的 lambda，这将可能导致未定义行为，引发程序崩溃。

参数​

名称类型描述
on_startfunction pointerOmniSDK Start 完成时的回调函数，传入参数类型为：
struct omnisdk_start_result* 结构体指针（表示 Start 结果）；
struct omnisdk_error* 结构指针（如果有错误发生）；
void* 用户指针
on_loginfunction pointerOmniSDK Login 完成时的回调函数，传入参数类型为：
struct omnisdk_login_result* 结构体（表示 Login 结果）；
struct omnisdk_error* 结构体（如果有错误发生）；
void* 用户指针
on_logoutfunction pointerOmniSDK Logout 完成时的回调函数，传入参数类型为：
struct omnisdk_logout_result* 结构体（表示Logout 结果）；
struct omnisdk_error* 结构体（如果有错误发生）；
void* 用户指针
on_purchasefunction pointerOmniSDK Purchase 完成时的回调函数，传入的参数类型为：
struct omnisdk_purchase_result* 结构体（表示 Purchase 结果）；
struct omnisdk_error* 结构体（如果有错误发生）；
void* 用户指针
提示

以上各回调函数的触发都代表着对应的行为已完成，无论执行结果是成功还是失败。如 on_login 的触发代表 login 已完成。每个回调函数都有三个参数，包括 result（成功时返回的结果）、error（失败时返回的错误信息）和 userptr（用户指针）。值得注意的是，在每次回调触发时，result 和 error 中只有一个是有效的（另一个参数的值将为 NULL）。

声明​

Show Code 
struct omnisdk_delegate {
    void (*on_start)(struct omnisdk_start_result* result, struct omnisdk_error* error, void* userptr) = NULL;
    void (*on_login)(struct omnisdk_login_result* result, struct omnisdk_error* error, void* userptr) = NULL;
    void (*on_logout)(struct omnisdk_logout_result* result, struct omnisdk_error* error, void* userptr) = NULL;
    void (*on_purchase)(struct omnisdk_purchase_result* result, struct omnisdk_error* error, void* userptr) = NULL;
};

struct omnisdk_start_result​

相关接口：omnisdk_start

OmniSDK 的初始化结果。

参数​

名称类型描述

声明​

Show Code 
struct omnisdk_start_result {
};

struct omnisdk_login_options​

相关接口：omnisdk_login

用于配置 OmniSDK 的登录选项。

参数​

名称类型描述
plan_idconst wchar_t*计划 ID
channel_idconst wchar_t*渠道 ID
auth_methodenum omnisdk_auth_method认证方法

声明​

Show Code 
struct omnisdk_login_options {
    const wchar_t* plan_id = NULL;
    const wchar_t* channel_id = NULL;
    enum omnisdk_auth_method auth_method;
};

enum omnisdk_auth_method​

相关接口：omnisdk_login

OmniSDK 登录认证方法枚举。

参数​

Key描述
OMNISDK_AUTH_METHOD_GUEST游客登录
OMNISDK_AUTH_METHOD_APPLEApple ID 登录
OMNISDK_AUTH_METHOD_FACEBOOKFacebook 登录

声明​

Show Code 
enum omnisdk_auth_method {
    OMNISDK_AUTH_METHOD_GUEST = 1,
    OMNISDK_AUTH_METHOD_APPLE = 7,
    OMNISDK_AUTH_METHOD_FACEBOOK = 3
};

struct omnisdk_login_info​

相关接口：omnisdk_login；omnisdk_get_login_info

OmniSDK 的登录信息。

参数​

名称类型描述
user_idconst wchar_t*账号的唯一标识
用于 Game Server 登录认证字段 uid
tokenconst wchar_t*令牌
channel_idconst wchar_t*当前渠道名称
接入方可用于数据统计 (不参与登录认证)
signatureconst wchar_t*OmniSDK Server 使用 HmacSHA1 生成的哈希值
Game Server 需要用该值与本地结果做校验

声明​

Show Code 
struct omnisdk_login_info {
    const wchar_t* user_id;
    const wchar_t* token;
    const wchar_t* channel_id;
    const wchar_t* signature;
};

struct omnisdk_login_result​

相关接口：omnisdk_login

OmniSDK 的登录结果。

参数​

名称类型描述
login_infostruct omnisdk_login_info登录信息

声明​

Show Code 
struct omnisdk_login_result {
    struct omnisdk_login_info login_info;
};

struct omnisdk_logout_result​

相关接口：omnisdk_logout

OmniSDK 的登出结果。

参数​

名称类型描述
user_idconst wchar_t*用户 ID

声明​

Show Code 
struct omnisdk_logout_result {
    const wchar_t* user_id;
};

struct omnisdk_purchase_options​

相关接口：omnisdk_purchase

用于配置 OmniSDK 的购买选项。

参数​

名称类型描述
product_idwchar_t*商品 ID
product_namewchar_t*商品名称
product_descwchar_t*商品描述
product_unitwchar_t*商品单位
product_unit_pricedouble商品单位价格
purchase_amountdouble购买金额
purchase_quantityint购买数量
purchase_callback_urlwchar_t*购买回调 URL
game_order_idwchar_t*游戏订单 ID
ext_jsonwchar_t*扩展 JSON
game_role_idwchar_t*游戏角色 ID
game_role_namewchar_t*游戏角色名称
game_role_levelwchar_t*游戏角色等级
game_role_vip_levelwchar_t*游戏角色 VIP 等级
game_zone_idwchar_t*游戏区域 ID
game_server_idwchar_t*游戏服务器 ID

声明​

Show Code 
struct omnisdk_purchase_options {
    //商品信息
    wchar_t* product_id;
    wchar_t* product_name;
    wchar_t* product_desc;
    wchar_t* product_unit;
    double product_unit_price;

    //购买信息
    double purchase_amount;
    int purchase_quantity;
    wchar_t* purchase_callback_url;
    wchar_t* game_order_id;
    wchar_t* ext_json;

    //角色信息
    wchar_t* game_role_id;
    wchar_t* game_role_name;
    wchar_t* game_role_level;
    wchar_t* game_role_vip_level;
    wchar_t* game_zone_id;
    wchar_t* game_server_id;
};

struct omnisdk_purchase_result​

相关接口：omnisdk_purchase

OmniSDK 的购买结果。

参数​

名称类型描述
order_idconst wchar_t*订单 ID
purchase_infostruct omnisdk_purchase_options购买信息

声明​

Show Code 
struct omnisdk_purchase_result {
    const wchar_t* order_id;
    struct omnisdk_purchase_options purchase_info;
};

struct omnisdk_error​

omnisdk_error 结构体包含 OmniSDK 操作中可能出现的错误信息。

参数​

名称类型描述
errorconst wchar_t*错误类型
messageconst wchar_t*错误信息的详细描述

声明​

Show Code 
struct omnisdk_error {
    const wchar_t* error;
    const wchar_t* message;
};

错误类型​

错误类型描述
NetworkError网络错误
ApiCallErrorAPI 调用失败，如在 start 成功前调用 login 等
UserCanceledError用户取消操作，如取消登录、购买等
InternalError内部错误，通常是 Native 与 Webview 通信间出现异常
ServerError服务器错误，OmniSDK 服务端返回的错误
EnvironmentError环境错误，如用户系统 未安装 Webview2 Runtime 环境等
InvalidHWndError无效的窗口句柄
UnknownError未知错误，此类错误出现的几率很低
最后于 更新