SDK Initialization

Get SDK

Download the latest C++ SDK package from the PC SDK Download Page.

1. Overview

WebGLHost C++ SDK provides standard C++ interfaces for integrating and managing WebGL game applets in Windows and macOS desktop applications.

2. Load SDK

2.1 Windows Platform

Use LoadLibraryA to dynamically load the DLL file:

#include <windows.h>
#include <iostream>
#include "IBrowsingService.h"

// Load the DLL
HMODULE hDll = LoadLibraryA("host\\webglhost_export.dll");
if (!hDll) {
    std::cerr << "Failed to load DLL: " << GetLastError() << std::endl;
    return 1;
}

// Get factory function
typedef IBrowsingService* (*GetBrowsingServiceFunc)();
GetBrowsingServiceFunc GetBrowsingService = 
    (GetBrowsingServiceFunc)GetProcAddress(hDll, "GetBrowsingService");

if (!GetBrowsingService) {
    std::cerr << "Failed to get GetBrowsingService function" << std::endl;
    FreeLibrary(hDll);
    return 1;
}

2.2 macOS Platform

Use dlopen to dynamically load the dylib file:

#include <dlfcn.h>
#include <iostream>
#include "IBrowsingService.h"

// Load the dylib
void* hDll = dlopen("host/libwebglhost_export.dylib", RTLD_LAZY);
if (!hDll) {
    std::cerr << "Failed to load dylib: " << dlerror() << std::endl;
    return 1;
}

// Get factory function
typedef IBrowsingService* (*GetBrowsingServiceFunc)();
GetBrowsingServiceFunc GetBrowsingService = 
    (GetBrowsingServiceFunc)dlsym(hDll, "GetBrowsingService");

if (!GetBrowsingService) {
    std::cerr << "Failed to get GetBrowsingService function: " << dlerror() << std::endl;
    dlclose(hDll);
    return 1;
}

3. Get Service Instance

3.1 GetBrowsingService

Gets an IBrowsingService service instance.

Function Signature

extern "C" WEBGLHOST_API IBrowsingService* GetBrowsingService();

Return Value

Returns IBrowsingService* - Browsing service interface pointer

Code Example

// Get service instance
IBrowsingService* service = GetBrowsingService();
if (!service) {
    std::cerr << "Failed to get service instance" << std::endl;
    return 1;
}

std::cout << "Service instance created successfully" << std::endl;

4. Initialize Browsing Core

4.1 InitializeBrowsingCore

Initializes the browsing core service and starts the runtime process.

Function Signature

int InitializeBrowsingCore(
    const char* config,
    const char* runtime_path,
    ICoreServiceHandler* handler
);

Parameter Description

Parameter	Type	Required	Description
config	const char*	Yes	JSON format configuration string
runtime_path	const char*	No	Path to runtime executable, pass empty string for auto-detection
handler	ICoreServiceHandler*	No	Event handler, can pass nullptr

Configuration Parameters (config JSON)

{
    "sdkKey": "your-sdk-key",
    "sdkSecret": "your-sdk-secret",
    "debug": true,
    "logLevel": "debug"
}

Field	Type	Required	Description
sdkKey	String	Yes	SDK key
sdkSecret	String	Yes	SDK secret
debug	Boolean	No	Whether to enable debug mode
logLevel	String	No	Log level: "debug", "info", "warn", "error"

Return Value

Value	Constant	Description
0	WMPF_ERRCODE_SUCCESS	Initialization successful
-1	WMPF_ERRCODE_FAIL	Initialization failed (runtime startup failed, connection failed, etc.)
-2	WMPF_ERRCODE_INVALID_PARAM	Invalid parameter
-4	WMPF_ERRCODE_ALREADY_INITIALIZED	Already initialized

Code Example

#include "IBrowsingService.h"
#include "ICoreServiceHandler.h"
#include <iostream>

// Configuration
const char* SDK_KEY = "your-sdk-key";
const char* SDK_SECRET = "your-sdk-secret";

// Event handler implementation
class MyServiceHandler : public WIUnknownImpl {
public:
    void OnContextInitialized() override {
        std::cout << "Context initialized" << std::endl;
    }
    
    void OnServiceDisconnected() override {
        std::cout << "Service disconnected" << std::endl;
    }
    
    bool OnCommonEventHappened(
        const char* event_name,
        int32_t callback_id,
        const char* data,
        const unsigned int data_size
    ) override {
        std::cout << "Event: " << event_name << std::endl;
        return true;
    }
};

int main() {
    // Load library and get service (see above)
    IBrowsingService* service = GetBrowsingService();
    
    // Build config JSON
    char config[1024];
    snprintf(config, sizeof(config), R"({
        "sdkKey": "%s",
        "sdkSecret": "%s",
        "debug": true,
        "logLevel": "debug"
    })", SDK_KEY, SDK_SECRET);
    
    // Create event handler
    MyServiceHandler handler;
    
    // Initialize
    // runtime_path: empty string for auto-detection
    // Windows: will look for "runtime\\webglhost-runtime.exe"
    // macOS: will look for "runtime/webglhost-runtime.app"
    int result = service->InitializeBrowsingCore(config, "", &handler);
    
    if (result == WMPF_ERRCODE_SUCCESS) {
        std::cout << "SDK initialized successfully!" << std::endl;
    } else {
        std::cerr << "SDK initialization failed: " << result << std::endl;
        return 1;
    }
    
    return 0;
}

Runtime Path Description

• Windows: If an empty string is passed, the SDK will look for the runtime at runtime/webglhost-runtime.exe relative to the DLL directory
• macOS: If an empty string is passed, the SDK will look for the runtime at runtime/webglhost-runtime.app relative to the dylib directory
• You can also pass an absolute or relative path to specify the runtime location

5. Uninitialize

5.1 UninitializeBrowsingCore

Uninitializes the browsing core service, terminates the runtime process, and cleans up resources.

Function Signature

void UninitializeBrowsingCore();

Code Example

// Cleanup before exit
service->UninitializeBrowsingCore();
service->Release();

// Unload library
#ifdef _WIN32
    FreeLibrary(hDll);
#else
    dlclose(hDll);
#endif

std::cout << "SDK uninitialized successfully" << std::endl;

Complete Example

For complete initialization examples, please refer to the Quick Integration Guide or the Demo Project.

6. Error Handling

It's recommended to always check return values and handle errors:

int result = service->InitializeBrowsingCore(config, "", &handler);

switch (result) {
    case WMPF_ERRCODE_SUCCESS:
        std::cout << "Initialization successful" << std::endl;
        break;
    case WMPF_ERRCODE_FAIL:
        std::cerr << "Initialization failed: general error" << std::endl;
        break;
    case WMPF_ERRCODE_INVALID_PARAM:
        std::cerr << "Initialization failed: invalid parameters" << std::endl;
        break;
    case WMPF_ERRCODE_ALREADY_INITIALIZED:
        std::cerr << "Already initialized" << std::endl;
        break;
    default:
        std::cerr << "Unknown error: " << result << std::endl;
        break;
}

7. Important Notes

1. Thread Safety: SDK methods are not thread-safe; call them from the main thread
2. Resource Management: Always call UninitializeBrowsingCore and Release when done
3. Event Handler Lifecycle: The passed ICoreServiceHandler object must remain valid throughout the SDK lifecycle
4. Runtime Dependencies: Ensure the runtime executable is accessible at the specified path

8. Related Documentation

• IBrowsingService Interface Details
• ICoreServiceHandler Event Handling
• Error Codes
• Quick Integration Guide