API reference

createRewardPlayer

const handle = createRewardPlayer(options);

Option	Default	Description
target	—	Element ID or HTMLElement
bid	—	A Prebid-format bid. Pass one with mediaType: "video"
mode	"normal"	Playback method. "normal" (standard VAST playback) or "ima" (Google IMA)
policy	See below	When the reward can be earned, and the close/claim behavior (Reward policy)
skin	"responsive"	Display format. responsive / modal / sheet / fullscreen, or a custom skin
theme	"auto"	Color scheme. auto (follows the OS) / ivory (light) / noir (dark), or { accent, radius, density, … }
text	—	Override the displayed text (title, description, button labels, etc.)
reward	—	Reward name. Displayed prominently in the accent color (e.g. "50 coins")
successToast	true	Show a small completion notification (toast) when the reward is earned
confirmClose	true	Confirm before closing when the user tries to close without claiming the reward
muted	true	Start muted (for autoplay). The user can turn sound on with the audio button
omid	false	Measurement via Open Measurement (normal mode). See Measurement (OMID)
loadTimeoutMs	3000	Treat as a failure if the ad does not start within this time (ms)
render	—	Required for banner bids. A function receiving (slot, bid) that draws the creative into slot (the render-target element itself) (Prebid renderAd / GPT). bid.adId is also available. The player does not render; it only handles the viewing timer
locale	Auto	Display language. "ja" / "en"
callbacks	—	Callbacks for the various events (list)

Return value (RewardHandle)

interface RewardHandle {
  result: Promise<RewardResult>; // resolves exactly once
  destroy(): void; // destroy early (resolves "dismissed" if pending)
}

type RewardResult =
  | { status: "rewarded" }
  | { status: "dismissed" }
  | { status: "failed"; reason?: string };

Callbacks

interface RewardCallbacks {
  onImpression?: () => void;
  onClick?: () => void;
  onReward?: () => void;
  onClose?: () => void;
  onFail?: () => void;
  onQuartile?: (q: "first" | "mid" | "third" | "complete") => void;
}

Reward policy

interface RewardPolicy {
  trigger:
    | { type: "watchThrough" } // earned after watching the ad to the end
    | { type: "minWatch"; seconds: number } // earned after watching N seconds (default: 15s; to the end if the ad is shorter)
    | { type: "watchThroughOr"; seconds: number }; // earned at whichever comes first: the end or N seconds
  // Whether skipping is allowed. Default disabled (skipping not allowed = must watch to the end).
  // allowed permits SDK-side skipping (e.g. the IMA skip button), and
  // rewardOnSkip decides whether the reward is earned on skip.
  skip:
    | { mode: "disabled" }
    | { mode: "allowed"; rewardOnSkip: boolean };
  pod: { required: number | "all" }; // number of ads in the pod that must be watched through to earn the reward (default 1; "all" for all of them)
  closableBeforeClaim: boolean; // whether it can be closed before the reward is earned (default false)
  requireClaimClick: boolean; // whether claiming requires a button action (default true; false grants automatically)
  closeAfterClaim: boolean; // whether to close the modal after claiming (default true)
  onAdFailure: "grant" | "deny" | "retry"; // on ad failure: grant / do not grant / retry (default deny)
}

The default is minWatch 15 seconds. The reward is earned after 15 seconds of viewing, or—if the ad is shorter—by watching it to the end. Even for overly long ads, users are not forced to watch the whole thing.

normal vs ima skip behavior

• normal: You have full control over skipping. With skip.mode: "disabled", no skip control is shown at all (watching to the end is required).
• ima: Google IMA shows its own skip button according to the tag's skipoffset. The player accepts that skip and handles it according to the skip policy.

Theme

You can pass either a preset name or an object to theme.

type ThemeInput = "auto" | "ivory" | "noir" | Theme;

interface Theme {
  preset?: "auto" | "ivory" | "noir";
  accent?: string; // accent color
  accentText?: string;
  bg?: string;
  fg?: string;
  overlayBg?: string;
  radius?: string;
  maxWidth?: string;
  density?: "standard" | "minimal";
}

createRewardPlayer({
  target: "reward-slot",
  bid,
  theme: { preset: "noir", accent: "#c3105b" },
});

Measurement (OMID)

When omid is enabled, Open Measurement measurement runs for ads that include <AdVerifications> (normal mode). Setting it to true uses partner Michao / 0.1.0.

createRewardPlayer({ target: "reward-slot", bid, omid: true });

• The session client is loaded from michao's CDN by default (per IAB guidelines, the integrating side hosts these files). You can override it with omid.sessionClientUrl.
• A measurement failure never causes the reward to fail.
• IMA mode performs measurement with IMA's own SDK.

createOutstreamPlayer

const handle = createOutstreamPlayer(options);
await handle.done; // "completed" | "failed" | "dismissed"

Option	Default	Description
target	—	Element ID or HTMLElement
bid	—	A Prebid video bid
mode	"normal"	"normal" or "ima"
viewableThreshold	0.5	The visible fraction at which playback starts (0–1)
onEnd	"collapse"	collapse / replay / keep
collapseOnFail	true	Collapse the ad slot on failure or when there is no fill
muted	true	Start muted
fullscreen	false	Show the fullscreen button
theme	"auto"	Theme
locale	Auto	"ja" / "en"
callbacks	—	onImpression / onComplete / onClick / onFail / onQuartile

interface OutstreamHandle {
  done: Promise<"completed" | "failed" | "dismissed">;
  destroy(): void;
}

Bid type

interface VideoBid {
  mediaType: "video";
  adUnitCode: string;
  vastXml?: string; // inline VAST XML
  vastUrl?: string; // VAST tag URL
  width: number;
  height: number;
  playerWidth?: number;
  playerHeight?: number;
}

Specify either vastXml or vastUrl. VAST is obtained only from video bids.