Skip to Content
4. API

API Reference

This page covers the v1.0 API surface defined in docs/spec-1.0.md and docs/spec-1.0_publish.md.

Initialize

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

See: Getting Started for catalog format.

runtime module

sdk.runtime.getCapabilities()

Returns the merged Capabilities object (synchronous — cached after init).

const caps = sdk.runtime.getCapabilities();

Returns:

{
  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?)

Raw provider pass-through (advanced use). Only available on InjectedProviderAdapter and NativeBridgeAdapter.

identity module

sdk.identity.get()

Get the current identity without triggering a login prompt.

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

Returns:

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

sdk.identity.signIn(options?)

Trigger the host login flow (wallet connect, OAuth, etc.).

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

sdk.identity.sign(message)

Sign an arbitrary message with the current identity.

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

account module

sdk.account.getIdentifier()

Get current account identifiers (wallet addresses, user IDs, etc.).

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)

Request a network switch. Throws E_UNSUPPORTED if not supported by the host.

await sdk.account.switchNetwork(8453);

pay module

sdk.pay.purchase({ productId })

Start a purchase. The product’s pricing, token, and chain come from the catalog — the game only passes productId.

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

Returns:

{
  status: "SUBMITTED" | "CONFIRMED" | "FAILED" | "REJECTED",
  productId: string,
  transactionRef?: string,         // txHash (on-chain) or orderId (native)
  confirmation?: { blockNumber?: number, orderId?: string, timestamp?: number },
  entitlementApplied?: boolean,
}

sdk.pay.getEntitlements()

Query entitlements (Phase 1: local storage).

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

Example response:

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

sdk.pay.consumeEntitlement(id, amount?)

Consume a consumable entitlement. amount defaults to 1.

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

storage module

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

Key-value persistence. Keys are automatically namespaced.

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

ui module

sdk.ui.open(url)

Open a URL in the host browser or in-app browser.

sdk.ui.toast(message)

Show a brief notification. Falls back to console in standard browser environments.

Events

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

// Account/identity changed
sdk.on("identity.changed", ({ identifiers }) => {
  console.log("identity changed", identifiers);
});
 
// Network/chain changed
sdk.on("network.changed", ({ network }) => {
  console.log("network changed", network);
});
 
// Purchase status updated
sdk.on("pay.statusChanged", ({ productId, status, transactionRef }) => {
  console.log(productId, status);
});
 
// Unsubscribe
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. Host App Guide