@verse8/ads

Framework-agnostic browser SDK that exposes Verse8 rewarded and interstitial ads to game creators through a small, Promise-based API.

The SDK is a transport layer only. It never loads Google AdSense H5, AdMob, or any third-party ad network directly. Ad requests are forwarded over postMessage to the Verse8 host (the web shell iframe on verse8.io, or the Flutter WebView bridge on mobile), which talks to the ad network on the SDK's behalf.

Architecture overview: see ARCHITECTURE.md for the end-to-end role / data-flow narrative across all five components (SDK, web parent, H5 renderer, mobile parent, verifier worker).

Install

pnpm add @verse8/ads
# or
npm install @verse8/ads
# or
yarn add @verse8/ads

Script tag / CDN

<script src="https://unpkg.com/@verse8/ads/dist/index.global.js"></script>
<script>
  // window.Verse8Ads is now available
  Verse8Ads.showRewarded({ placementId: "rewarded_1" }).then(console.log);
</script>

A jsdelivr field is also published; you can swap unpkg.com for cdn.jsdelivr.net/npm/... if preferred.

Quick start

ESM

import { Verse8Ads } from "@verse8/ads";

const result = await Verse8Ads.showRewarded({ placementId: "rewarded_1" });
if (result.status === "rewarded") {
  console.log("granted", result.reward);
}

CommonJS

const { Verse8Ads } = require("@verse8/ads");

Verse8Ads.showInterstitial({ placementId: "interstitial_1" }).then((r) => {
  console.log(r.status);
});

<script> tag

<script src="https://unpkg.com/@verse8/ads/dist/index.global.js"></script>
<script>
  Verse8Ads.showRewarded({ placementId: "rewarded_1" }).then((r) => {
    if (r.status === "rewarded") console.log("rewarded", r.reward);
  });
</script>

API

init(opts?: InitOpts): void

Optional. Registers the inbound message listener and lets you configure trust/debug settings. Calling init is idempotent — the second call updates config but does not add a second listener. Any show* call also triggers init lazily if it has not run.

interface InitOpts {
  /** Additional trusted inbound origins. Merged with defaults; never replaces them. */
  extraTrustedOrigins?: string[];
  /** Optional iframe parent targetOrigin override for staging/local shells. */
  parentOrigin?: string;
  /** Enable console.debug logging. Default: false. */
  debug?: boolean;
}

Example:

Verse8Ads.init({
  extraTrustedOrigins: [
    "https://staging.verse8.io",
    "http://localhost:5173",
  ],
  parentOrigin: "https://staging.verse8.io",
  debug: true,
});

Accumulation semantics. extraTrustedOrigins is merged across every init() call and deduped — a second init({extraTrustedOrigins:['…']}) does NOT replace the first call's extras, it extends them. This matches the "never replaces defaults" rule: the allowlist only grows. Reload the page to reset.

showRewarded(opts: ShowOpts): Promise<RewardedAdResult>

Presents a rewarded ad. Resolves (never rejects) with {status:'rewarded', reward?}, {status:'dismissed'}, or {status:'failed', error:{code}}.

showInterstitial(opts: ShowOpts): Promise<InterstitialAdResult>

Presents an interstitial ad. Resolves with {status:'dismissed'} or {status:'failed', error:{code}}. Interstitial never returns a reward.

Types

interface ShowOpts {
  placementId: string;
  /** Optional caller-supplied correlation id. Auto-generated UUID v4 if omitted. */
  requestId?: string;
  /**
   * Per-request timeout in ms. Default: 30_000. Must be a finite positive
   * number; `showRewarded`/`showInterstitial` throws `TypeError` synchronously
   * if given `0`, a negative value, `NaN`, `Infinity`, or a non-number.
   */
  timeoutMs?: number;
  /** Freeform pass-through payload forwarded to the host. */
  meta?: Record<string, unknown>;
}

type AdResult =
  | { status: "rewarded"; requestId: string; reward?: { amount: number; type: string } }
  | { status: "dismissed"; requestId: string }
  | { status: "failed"; requestId: string; error: { code: ErrorCode; message?: string } };

type ErrorCode =
  | "busy"
  | "timeout"
  | "unsupported_env"
  | "platform_error";

Error codes

| Code | Trigger | |---|---| | busy | Another showRewarded / showInterstitial is still pending. The SDK is single-flight. | | timeout | The host did not respond within timeoutMs (default 30_000 ms). | | unsupported_env | Running outside a Verse8 host (top-frame without PING/PONG bridge, or SSR). Resolves in ≤500 ms when detected. | | platform_error | Host returned {status:'failed', error:{code:'platform_error', message?}}, the inbound envelope was malformed, or a synchronous transport error occurred (cross-origin SecurityError, DataCloneError on postMessage). |

Input validation

showRewarded and showInterstitial throw TypeError synchronously for programming errors that should never reach production:

• missing or empty placementId
• timeoutMs that is not a finite positive number (rejects 0, negatives, NaN, Infinity, non-number)

These are promise-less signals — they are bugs in the caller, not recoverable ad states. All host-side or network failures are surfaced through the normal {status:'failed', error:{code}} resolution path.

Troubleshooting

Ads return unsupported_env even though the host is eventually ready

The SDK caches the initial PING/PONG handshake for the lifetime of the page session. If the parent shell's ad handler mounts AFTER the SDK's first show*() call, the handshake is cached as unsupported for the rest of the session. Reload the page to re-probe the bridge.

Platform contract

The SDK talks to the Verse8 host over a correlated {type, requestId, payload} envelope. See PROTOCOL.md for the full spec, including:

• Envelope schema and message type enum
• PING/PONG handshake protocol (500 ms budget, session-cached)
• Request / response examples
• Origin validation rules
• requestId security note (it is a correlation token, NOT an authorization credential)
• Platform-side requirements for the web shell and the FlutterVerse8Ads mobile channel

Bundle size

The IIFE bundle (dist/index.global.js) is under 8 KB gzipped. Zero runtime dependencies. CI fails the build if the budget creeps.

License

MIT