Variable PixllandSDKConst

PixllandSDK: {
    account: {
        displayName(): null | string;
        get(): Promise<null | User>;
        getToken(): Promise<null | string>;
        id(): null | string;
        isSignedIn(): boolean;
        onChange(_cb: ((signedIn: boolean) => void)): Unsubscribe;
        signIn(): Promise<null | User>;
    };
    data: {
        delete(_key: string): Promise<void>;
        get<T>(_key: string): Promise<null | T>;
        keys(): Promise<string[]>;
        set(_key: string, _value: unknown): Promise<void>;
    };
    protocol: number;
    version: string;
    captureError(err: string | Error): void;
    commercialBreak(): Promise<void>;
    gameLoadingFinished(): void;
    gameLoadingProgress(ratio: number): void;
    gameplayStart(): void;
    gameplayStop(): void;
    getURLParam(name: string): null | string;
    happyTime(value: number): void;
    init(opts?: InitOptions): Promise<InitResult>;
    measure(category: string, what: string, action: string): void;
    movePill(_topPercent: number, _topPx: number): void;
    playerLocale(): string;
    requestHapticFeedback(kind: HapticKind): void;
    rewardedBreak(): Promise<RewardedResult>;
    setDebug(enabled: boolean): void;
    shareableURL(params?: Record<string, string>): string;
} = ...

The @pixlland/sdk runtime singleton. Auto-exposed on window.PixllandSDK for games loaded via <script src="/sdk/v1/pixlland.js">. Also importable via import { PixllandSDK } from '@pixlland/sdk' for bundled workflows.

Lifecycle order a game should follow:

await PixllandSDK.init();              // 1. handshake with portal
PixllandSDK.gameLoadingProgress(0.5);  // 2. report asset loading
PixllandSDK.gameLoadingFinished();     // 3. ready to play
PixllandSDK.gameplayStart();           // 4. user clicks Play
// ... gameplay ...
PixllandSDK.gameplayStop();            // 5. user paused / died / quit

Type declaration

  • account: {
        displayName(): null | string;
        get(): Promise<null | User>;
        getToken(): Promise<null | string>;
        id(): null | string;
        isSignedIn(): boolean;
        onChange(_cb: ((signedIn: boolean) => void)): Unsubscribe;
        signIn(): Promise<null | User>;
    }
    • displayName:function
      • displayName(): null | string

      • Returns null | string

    • get:function
    • getToken:function
      • getToken(): Promise<null | string>

      • Returns Promise<null | string>

    • id:function
      • id(): null | string

      • Returns null | string

    • isSignedIn:function
    • onChange:function
    • signIn:function
  • data: {
        delete(_key: string): Promise<void>;
        get<T>(_key: string): Promise<null | T>;
        keys(): Promise<string[]>;
        set(_key: string, _value: unknown): Promise<void>;
    }
    • delete:function
      • delete(_key): Promise<void>

      • Parameters

        • _key: string

        Returns Promise<void>

    • get:function
      • get<T>(_key): Promise<null | T>

      • Type Parameters

        • T = unknown

        Parameters

        • _key: string

        Returns Promise<null | T>

    • keys:function
      • keys(): Promise<string[]>

      • Returns Promise<string[]>

    • set:function
      • set(_key, _value): Promise<void>

      • Parameters

        • _key: string
        • _value: unknown

        Returns Promise<void>

  • protocol: number

    Wire protocol version. Bumped only when shell <-> SDK contract breaks.

  • version: string

    SDK version (semver). Bumped on breaking surface changes.

  • captureError:function
    • captureError(err): void

    • Forward a recoverable error to Sentry via the portal. Use for caught exceptions you want to track without crashing the game.

      Parameters

      • err: string | Error

      Returns void

      Example

      try { saveProgress(); } catch (e) { PixllandSDK.captureError(e); }
  • commercialBreak:function
    • commercialBreak(): Promise<void>

    • Show a non-rewarded ad break (interstitial / display). Resolves when the ad finishes (or instantly when there is no fill, no consent, or the SDK is in standalone mode). Hard timeout of 30s so games never freeze waiting for an ad.

      Returns Promise<void>

      Example

      if (levelsBeaten % 3 === 0) await PixllandSDK.commercialBreak();
  • gameLoadingFinished:function
    • gameLoadingFinished(): void

    • Signal the game is fully loaded and the loading overlay should fade. Call exactly once after final asset is ready.

      Returns void

  • gameLoadingProgress:function
    • gameLoadingProgress(ratio): void

    • Report asset loading progress. Drives the Poki-style progress bar the portal shows over the iframe before the game is ready.

      Parameters

      • ratio: number

        Number in [0, 1]. Values outside the range are clamped.

      Returns void

  • gameplayStart:function
    • gameplayStart(): void

    • Mark the start of a gameplay session. The portal uses this to gate commercialBreak() / rewardedBreak() calls (ads only allowed during gameplay) and to record session-length analytics.

      Calling twice without an intervening gameplayStop emits sdk:error gameplay_already_started.

      Returns void

  • gameplayStop:function
    • gameplayStop(): void

    • Mark the end of a gameplay session. Call when the player pauses, dies, returns to the main menu, or quits. Pairs with gameplayStart. Calling without a matching start emits sdk:error gameplay_not_started.

      Returns void

  • getURLParam:function
    • getURLParam(name): null | string

    • Read a single query-string parameter from the current iframe URL. Returns null when the param is absent.

      Parameters

      • name: string

      Returns null | string

  • happyTime:function
    • happyTime(value): void

    • "Happy time" — Poki's primary engagement metric. Number of seconds the player is judged to be having fun (typically incremented per frame the gameplay loop runs without errors).

      Parameters

      • value: number

        Seconds of fun delivered since the last call.

      Returns void

  • init:function
    • init(opts?): Promise<InitResult>

    • Handshake with the Pixlland portal. Resolves with the session state (gameId, locale, signedIn). Standalone fallback after 4s when no portal is detected (dev mode, file://, third-party embed, etc.).

      Parameters

      Returns Promise<InitResult>

      A snapshot of the player session — see InitResult.

      Example

      const { gameId, locale, signedIn } = await PixllandSDK.init({
        onError: (e) => console.warn(e),
      });
  • measure:function
    • measure(category, what, action): void

    • Emit a custom analytics event. Three labels, structured for funnel analysis (category -> what -> action). Pipes to the portal's tracker (Cloudflare Analytics / Plausible).

      Parameters

      • category: string
      • what: string
      • action: string

      Returns void

      Example

      PixllandSDK.measure('progress', 'level', 'completed');
  • movePill:function
    • movePill(_topPercent, _topPx): void

    • Reposition the mobile floating pill (logo+search) so it doesn't overlap the game UI. No-op on desktop.

      Parameters

      • _topPercent: number

        Percentage of viewport height (0–100).

      • _topPx: number

        Absolute pixel offset from _topPercent.

      Returns void

  • playerLocale:function
    • playerLocale(): string

    • Player's preferred locale (e.g. "pt-BR", "en"). Set by the portal handshake; falls back to navigator.language in standalone.

      Returns string

  • requestHapticFeedback:function
    • requestHapticFeedback(kind): void

    • Trigger a brief device vibration (when supported). Silently no-ops on platforms without navigator.vibrate. Pattern intensity follows HapticKind.

      Parameters

      Returns void

  • rewardedBreak:function
    • rewardedBreak(): Promise<RewardedResult>

    • Show a rewarded ad break. Resolves with { granted, reason } — only unlock the reward when granted === true. 60s hard timeout. Returns { granted: false, reason: 'ad_blocked' } when the user has not given ads consent.

      Returns Promise<RewardedResult>

      Example

      const { granted } = await PixllandSDK.rewardedBreak();
      if (granted) player.coins += 100;
  • setDebug:function
    • setDebug(enabled): void

    • Toggle verbose [PixllandSDK] console logging. Off by default.

      Parameters

      • enabled: boolean

        true to enable logging.

      Returns void

  • shareableURL:function
    • shareableURL(params?): string

    • Build a deep-link URL preserving every existing query param plus the extra ones in params. Use for "Share my level" / "Invite a friend" flows.

      Parameters

      • params: Record<string, string> = {}

        Extra key/value pairs to merge into the URL.

      Returns string

      A fully-qualified URL safe to share.

Settings

Member Visibility