API リファレンス

createRewardPlayer

const handle = createRewardPlayer(options);

オプション	既定	説明
target	—	要素 ID か HTMLElement
bid	—	Prebid 形式の入札。video（VAST、再生）または banner（display、render で描画）
mode	"normal"	再生方式。"normal"（標準の VAST 再生）または "ima"（Google IMA）
policy	下記参照	特典をいつ獲得できるか、閉じる・受け取りの挙動（リワードポリシー）
skin	"responsive"	表示形式。responsive / modal / sheet / fullscreen、または独自スキン
theme	"auto"	配色。auto（OS 連動）/ ivory（ライト）/ noir（ダーク）、または { accent, radius, density, … }
text	—	表示文言の上書き（タイトル・説明・ボタン名など）
reward	—	特典名。アクセントカラーで目立つように表示します（例 "コイン50枚"）
successToast	true	獲得時に小さな完了通知（トースト）を表示する
confirmClose	true	特典を受け取らずに閉じようとしたとき、確認を挟む
muted	true	ミュートで開始（自動再生のため）。ユーザーは音声ボタンでオンにできます
omid	false	Open Measurement による計測（normal モード）。詳細は計測（OMID）
loadTimeoutMs	3000	この時間（ms）内に広告が始まらなければ失敗扱いにする
render	—	banner 入札のとき必須。(slot, bid) を受け取り、クリエイティブを slot（描画先の要素そのもの）に描画する関数。プレイヤーは描画せず閲覧タイマーのみ担当。詳細はバナーのリワード
locale	自動	表示言語。"ja" / "en"
callbacks	—	各種イベントのコールバック（一覧）

戻り値（RewardHandle）

interface RewardHandle {
  result: Promise<RewardResult>; // 1 度だけ解決
  destroy(): void; // 早期に破棄（保留中なら "dismissed"）
}

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

コールバック

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

リワードポリシー

interface RewardPolicy {
  trigger:
    | { type: "watchThrough" } // 広告を最後まで視聴したら獲得
    | { type: "minWatch"; seconds: number } // N 秒視聴したら獲得（既定: 15秒。広告が短ければ最後まで）
    | { type: "watchThroughOr"; seconds: number }; // 最後まで or N 秒、早い方で獲得
  // スキップの可否。既定 disabled（スキップ不可＝最後まで必須）。
  // allowed は SDK 側のスキップ（IMA のスキップボタン等）を許可し、
  // rewardOnSkip でスキップ時に獲得とするか決めます。
  skip:
    | { mode: "disabled" }
    | { mode: "allowed"; rewardOnSkip: boolean };
  pod: { required: number | "all" }; // 獲得に必要な、ポッド内で見終える広告数（既定 1、"all" で全部）
  closableBeforeClaim: boolean; // 獲得前でも閉じられるか（既定 false）
  requireClaimClick: boolean; // 受け取りにボタン操作を必須にするか（既定 true。false で自動付与）
  closeAfterClaim: boolean; // 受け取り後にモーダルを閉じるか（既定 true）
  onAdFailure: "grant" | "deny" | "retry"; // 広告失敗時: 付与 / 付与しない / 再試行（既定 deny）
}

既定は minWatch 15 秒です。15 秒視聴すれば獲得でき、広告がそれより短ければ最後まで視聴で獲得します。長すぎる広告でも、ユーザーに全編視聴を強いません。

normal と ima のスキップの違い

• normal: スキップを完全に制御できます。skip.mode: "disabled" ならスキップ操作は一切表示されません（最後まで視聴が必須）。
• ima: Google IMA がタグの skipoffset に従って独自のスキップボタンを出します。プレイヤーはそのスキップを受け入れ、skip ポリシーに従って扱います。

テーマ

theme にはプリセット名か、オブジェクトを渡せます。

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

interface Theme {
  preset?: "auto" | "ivory" | "noir";
  accent?: string; // アクセントカラー
  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" },
});

計測（OMID）

omid を有効にすると、<AdVerifications> を持つ広告で Open Measurement の計測が走ります（normal モード）。true でパートナー Michao / 0.1.0 を使います。

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

• セッションクライアントは既定で michao の CDN から読み込まれます。IAB ガイドラインでは導入側でのホスティングが推奨されており、omid.sessionClientUrl で差し替えられます。
• 計測の失敗がリワードの失敗になることはありません。
• IMA モードは IMA 自身の SDK で計測します。

createOutstreamPlayer

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

オプション	既定	説明
target	—	要素 ID か HTMLElement
bid	—	Prebid の video 入札
mode	"normal"	"normal" または "ima"
viewableThreshold	0.5	再生を開始する表示割合（0〜1）
onEnd	"collapse"	collapse / replay / keep
collapseOnFail	true	失敗・在庫切れ時に広告枠を畳む
muted	true	ミュートで開始
fullscreen	false	フルスクリーンボタンを表示
theme	"auto"	テーマ
locale	自動	"ja" / "en"
callbacks	—	onImpression / onComplete / onClick / onFail / onQuartile

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

入札（Bid）の型

interface VideoBid {
  mediaType: "video";
  adUnitCode: string;
  vastXml?: string; // インライン VAST XML
  vastUrl?: string; // VAST タグ URL
  width: number;
  height: number;
  playerWidth?: number; // 要求したプレイヤー幅（Prebid の playerSize）
  playerHeight?: number; // 要求したプレイヤー高さ
}

vastXml か vastUrl のどちらかを指定します。VAST は video の入札からのみ得られます。

アウトストリームの広告枠は、このプレイヤーサイズ（playerWidth / playerHeight、無ければ width / height）のアスペクト比に固定され、広告の読み込み前に確保されます。詳しくは アウトストリームの広告枠サイズ を参照してください。