跳到主要内容

集成 SDK

提示

目前暂时只支持手动集成的方式。后续计划添加更多的集成方式，如 NuGet。

快速入门

C/C++ 项目手动集成​

Step 1：添加 OmniSDK.dll 文件​

将 OmniSDK.dll 文件添加到你的项目目录中：将 DLL 文件复制到您的项目源码文件所在的文件夹或者一个专门存放库文件的文件夹。

Step 2：链接库文件​

将 OmniSDK.lib 文件路径添加到项目的链接器输入中。

如果您使用的是 Visual Studio，可以按照以下步骤操作：

  1. 打开您的项目在 Visual Studio 中。
  2. 在解决方案资源管理器中，右击您的项目，然后选择 "属性"。
  3. 在弹出的对话框中，导航到 "配置属性" -> "链接器" -> "输入"。
  4. 在 "附加依赖项" 中，点击右侧的下拉箭头，选择 "<编辑...>"。
  5. 在弹出的编辑框中输入 OmniSDK.lib 的路径，点击 "确定"。

Step 3：包含头文件​

在您需要使用 OmniSDK 的源代码文件中，包含 OmniSDK 的头文件，例如：

#include "omnisdk.h"

这将使得您可以在这个文件中使用 OmniSDK 提供的类和函数。

Step 4：使用 OmniSDK​

现在，您可以在代码中创建 OmniSDK 的实例，并使用其提供的方法接入 OmniSDK 的业务逻辑。

接入 OmniSDK 的业务逻辑​

Step 1：初始化​

首先，需要先初始化 OmniSDK。您可以通过调用 omnisdk_start 函数来完成这个步骤。在调用该函数时，您需要提供一些参数：

  • 父窗口的句柄：通常是游戏的主窗口。OmniSDK 的界面将在此窗口中显示。
  • 用于初始化SDK所需的配置项：这些配置项包含在 omnisdk_start_options 结构中，包括应用ID、事件回调等。
  • 用户提供的任意指针：这是一个可选参数，可以用于在 omnisdk_delegate.on_start 回调函数中传递用户数据，以实现更灵活的程序设计。

在配置 omnisdk_start_options 属性时，相关注意事项请参阅这里。

例如，您可以这样调用 omnisdk_start 函数：

void omnisdk_on_start(struct omnisdk_start_result* result, struct omnisdk_error* error, void* userptr) {
    if (result) {
        // TODO: 初始化成功后的操作
    } else if (error) {
        // 初始化失败后的操作
        if (wcscmp(error->error, L"UserCanceledError") == 0) {
            Toast(L"请前往 https://developer.microsoft.com/en-us/microsoft-edge/webview2#download 下载 Webview 环境");
        }
        // TODO: 其他初始化失败错误的处理
        ...
    }
}

HWND hwnd = ... // 获取游戏的主窗口句柄
struct omnisdk_start_options start_options;
start_options.app_id = APP_ID;
start_options.app_key = APP_KEY;
...
start_options.delegate.on_start = &omnisdk_on_start;
start_options.delegate.on_login = ...
...
void* userptr = NULL; // 用户提供的任意指针

omnisdk_start(hwnd, &options, userptr);
提示

注意：omnisdk_start 方法是启动 OmniSDK 的关键步骤，它必须在所有其它 OmniSDK API 调用之前被执行。接入方需要尽早调用 omnisdk_start，如果失败，后续登录、支付等流程将无法执行，并返回 ApiCallError 错误。

然后，您可以通过于struct omnisdk_start_options start

Step 2：初始化回调的处理​

在 Step 1 中，我们通过 omnisdk_start_options.delegate 分别注册了 on_start（初始化完成）、on_login（登录完成）、on_logout（登出完成）、on_purchase（购买完成）四个回调函数，我们可以通过 on_start 来接收初始化完成后的相关数据和错误。

例如：

// 在 omnisdk_start 中注册的 on_start 回调函数
void omnisdk_on_start(struct omnisdk_start_result* result, struct omnisdk_error* error, void* userptr) {
    if (result) {
        // 初始化成功、可以进行后续的登录、购买
    } else if (error) {
        // 初始化失败后的操作
        if (wcscmp(error->error, L"UserCanceledError") == 0) { 
            // Webview2 Runtime 环境检查失败，引导用户安装此环境
            Toast(L"请前往 https://developer.microsoft.com/en-us/microsoft-edge/webview2#download 下载 Webview 环境");
        }
        // TODO: 其他初始化失败错误的处理
        ...
    }
}

该函数的主要作用是处理 OmniSDK 启动的结果：

  • 当 OmniSDK 成功启动时，result 参数将会是一个非空的指针，您可以在这里执行后续的登录、购买等操作。
  • 当 OmniSDK 启动失败时，error 参数将会是一个非空的指针，您需要在这里处理启动失败的情况。

在这个函数的实现中，还特别处理了一个情况：如果 OmniSDK 启动失败，且错误是因为 Webview2 Runtime 环境检查失败（错误信息为 "UserCanceledError"），那么提示用户前往 Microsoft 的网站下载并安装 Webview 环境。

此外，您还可以在这个函数中处理其他类型的启动失败错误。

Step 3：登录​

登录是进入游戏的关键步骤。登录请求可以通过调用 omnisdk_login 函数来发起。同样，您需要提供一些参数：

  • 用于登录所需的配置项：这些配置项包含在 omnisdk_login_options 结构中，包括 Plan ID 、验证方式等。
  • 用户提供的任意指针：这是一个可选参数，可以用于在 omnisdk_delegate.on_login 回调函数中传递用户数据，以实现更灵活的程序设计。

例如：

omnisdk_login_options options = ... // 配置登录选项
void* userptr = ... // 用户提供的任意指针

omnisdk_login(&options, userptr);

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

Step 4：登录回调的处理​

通过在 omnisdk_start 中注册的登录回调函数 on_login，您可以在用户完成登录操作（包括成功登录或取消登录）后，对登录结果进行处理。

例如：

// 在 omnisdk_start 中注册的 on_login 回调函数
void omnisdk_on_login(struct omnisdk_login_result* result, struct omnisdk_error* error, void* userptr) {
    if (result != NULL) {
        Log(L"用户成功登录, UserId: ", result->login_info.user_id);
    }
    if (error != NULL && wcscmp(error->error, L"UserCanceledError") == 0) {
        Log(L"用户取消登录");
    }
}

在这个例子中，我们检查登录结果和错误。如果用户成功登录，我们记录用户ID。如果用户取消登录，我们将记录一个取消登录的日志。

Next Steps​

现在您已经完成 OmniSDK 初始化及登录功能的接入了，有关 OmniSDK 的更多详细信息，请参阅 API 文档了解详细的接口及数据结构定义。

最后于 更新