Skip to Content
4. API

API 参考

本页面覆盖 docs/spec-1.0.md 和 docs/spec-1.0_publish.md 定义的 v1.0 API 接口。

初始化

import { PHSDK } from "@playsout/hybrid-sdk";
 
const sdk = await PHSDK.init({
  appId: "my-game",
  pay: { catalog: productCatalog },
});

商品目录格式见：Getting Started

runtime 模块

sdk.runtime.getCapabilities()

返回合并后的 Capabilities 对象（同步，init 完成后已缓存）。

const caps = sdk.runtime.getCapabilities();

返回：

{
  protocolVersion: "1.0",
  runtime: { hostType: "injected_provider", adapters: [...] },
  modules: {
    runtime: { getCapabilities: true, getHostInfo: boolean, request: boolean },
    identity: { get: boolean, signIn: boolean, sign: boolean },
    account: { getIdentifier: boolean, getNetwork: boolean, switchNetwork: boolean },
    pay: { purchase: boolean, getEntitlements: boolean, consumeEntitlement: boolean, modes: [...] },
    storage: { get: boolean, set: boolean, remove: boolean, secure: boolean },
    ui: { open: boolean, toast: boolean, showPaymentUI: boolean },
  }
}

sdk.runtime.getHostInfo()

const info = sdk.runtime.getHostInfo();
// { hostType: "injected_provider", userAgent: "...", timezone: "Asia/Tokyo" }

sdk.runtime.request(method, params?)

底层 provider 透传（高级用途）。仅 InjectedProviderAdapter 和 NativeBridgeAdapter 支持，不支持时抛 E_UNSUPPORTED。

identity 模块

sdk.identity.get()

获取当前身份，不触发登录提示。

const identity = await sdk.identity.get();

返回：

{
  subject: "eip155:8453:0xabc...",  // 或 "playsout:user:123" 或 "anon:device:xxx"
  displayName?: string,
  isAnonymous: boolean,
  proof?: { type: "none" | "signature" | "token" | "oauth", data?: string }
}

sdk.identity.signIn(options?)

触发宿主登录流程（钱包连接、OAuth 等）。

const identity = await sdk.identity.signIn();

sdk.identity.sign(message)

对 message 进行签名。

const result = await sdk.identity.sign("my message");
// { message: "my message", signature: "0x...", signer: "0xabc..." }

account 模块

sdk.account.getIdentifier()

获取当前账号标识符数组（钱包地址 / 用户 ID 等）。

const ids = await sdk.account.getIdentifier();
// ["0xabc..."]

sdk.account.getNetwork()

const network = await sdk.account.getNetwork();
// { id: 8453, name: "Base", type: "blockchain" }

sdk.account.switchNetwork(networkId)

切换网络 / 链。不支持时抛 E_UNSUPPORTED。

await sdk.account.switchNetwork(8453);

pay 模块

sdk.pay.purchase({ productId })

发起购买。价格、token、链由 catalog 决定，游戏只传 productId。

const result = await sdk.pay.purchase({ productId: "coin_pack_1" });

返回：

{
  status: "SUBMITTED" | "CONFIRMED" | "FAILED" | "REJECTED",
  productId: string,
  transactionRef?: string,          // txHash（链上）或 orderId（native）
  confirmation?: { blockNumber?: number, orderId?: string, timestamp?: number },
  entitlementApplied?: boolean,
}

sdk.pay.getEntitlements()

查询权益（Phase 1：本地存储）。

const { entitlements } = await sdk.pay.getEntitlements();

示例返回：

{
  "entitlements": [
    { "id": "remove_ads", "type": "non_consumable", "active": true },
    { "id": "coin_pack_1", "type": "consumable", "balance": 2000 }
  ]
}

sdk.pay.consumeEntitlement(id, amount?)

消耗一个消耗型权益。amount 默认为 1。

await sdk.pay.consumeEntitlement("coin_pack_1", 100);

storage 模块

sdk.storage.get(key) / set(key, value) / remove(key)

键值存储，key 自动加 namespace 前缀。

await sdk.storage.set("myKey", { foo: "bar" });
const val = await sdk.storage.get("myKey");
await sdk.storage.remove("myKey");

ui 模块

sdk.ui.open(url)

在宿主浏览器或内置浏览器中打开 URL。

sdk.ui.toast(message)

显示浮层提示。标准浏览器环境降级为 console。

事件

sdk.on(eventName, handler) / sdk.off(eventName, handler)

// 账号 / 身份变更
sdk.on("identity.changed", ({ identifiers }) => {
  console.log("账号变更", identifiers);
});
 
// 网络 / 链变更
sdk.on("network.changed", ({ network }) => {
  console.log("网络变更", network);
});
 
// 支付状态更新
sdk.on("pay.statusChanged", ({ productId, status, transactionRef }) => {
  console.log(productId, status);
});
 
// 取消订阅
sdk.off("identity.changed", handler);

sdk.debug

sdk.debug.sdkVersion       // "1.0.0"
sdk.debug.protocolVersion  // "1.0"
sdk.debug.adapters         // ["injected_provider", "standard_web"]
sdk.debug.primaryAdapter   // "injected_provider"
3. 宿主接入指南