Verse8 Ads

Rewarded and interstitial video ads for Verse8 games. Your game calls one function and handles the result.

Install


pnpm add @verse8/ads

Or via CDN — the bundle exposes a single Verse8Ads global. Pin a specific version in production:


<script
  src="https://unpkg.com/@verse8/ads@latest/dist/index.global.js"
  crossorigin="anonymous"
></script>

Show a rewarded ad

Trigger the call from a user gesture (click or tap). Never auto-show on page load — ad networks treat that as a policy violation.


import { Verse8Ads } from "@verse8/ads";
 
async function watchAdToRevive() {
  const result = await Verse8Ads.showRewarded({
    placementId: "revive-hero",
  });
 
  switch (result.status) {
    case "rewarded":
      // User watched the ad to completion. Grant the reward.
      reviveHero();
      break;
    case "dismissed":
      // User closed the ad early. Don't grant.
      break;
    case "failed":
      // Ad couldn't be shown. Show a friendly toast and let the user retry.
      // result.error.code: 'busy' | 'timeout' | 'unsupported_env' | 'platform_error'
      break;
  }
}

showRewarded always resolves — it never throws for ad or network failures. Branch on result.status and treat anything other than 'rewarded' as no-grant.

Statuses


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

`status` / `error.code`	When	Recommended UX
`rewarded`	User watched the ad to completion	Grant the reward
`dismissed`	User closed the ad early	Don’t grant; nudge them if you want
`failed` / `busy`	An ad is already showing	Ignore — disable the button while busy
`failed` / `timeout`	No response within `timeoutMs` (default 30s)	Toast: “ad unavailable, try again later”
`failed` / `unsupported_env`	Ads are unavailable in this environment	Hide the ad button for the session
`failed` / `platform_error`	Ad unavailable	Toast: “ad unavailable”; let the user retry

result.reward is a UX hint, not the source of truth.

Use it for “+1 revive!” animations. For valuable rewards, your game server should derive the grant amount from a server-side reward table and confirm the watch — see Server-Side Verification.

Show an interstitial


await Verse8Ads.showInterstitial({ placementId: "between-levels" });

Interstitials don’t grant rewards. The promise resolves whether the user watched or skipped; no branching needed.

Optional fields


await Verse8Ads.showRewarded({
  placementId: "revive-hero",
  requestId: traceId,    // your own correlation id (UUID v4 auto-generated otherwise)
  timeoutMs: 15_000,     // default 30000
});

Server-side verification

For valuable rewards, verify result.requestId on your server before crediting the player — see Server-Side Verification.