Michao プレイヤー

テーマ

リワード広告を導入する ​

リワード広告は、ユーザーが広告を最後まで視聴することで特典（リワード）を受け取れる広告形式です。Michao プレイヤーでは、Prebid.js で取得した video の入札を渡すと、視聴完了の判定からリワード付与までをプレイヤーが扱います。

サンプル広告でリワードプレイヤーを起動します。

仕組み ​

  1. 入札の取得: Prebid.js で video の入札（VAST）を取得します。
  2. プレイヤーの生成: 入札を createRewardPlayer() に渡すとモーダルが開き、広告の読み込み・再生が始まります。
  3. 視聴: ポリシーの条件（最後まで視聴 / 一定秒数視聴など）を満たすと、特典を受け取れる状態になります。
  4. リワード付与: onReward コールバック、または result の解決で特典を付与します。
  5. エラー: 在庫切れや読み込み失敗時は onFail で扱います（リワードは付与されません）。

クイックスタート ​

Prebid の video 入札（vastXml または vastUrl）を渡します。

html
<div id="reward-slot"></div>
<script src="https://cdn.michao-ssp.com/player/v1/reward.js"></script>
<script>
  const handle = window.michao.createRewardPlayer({
    target: "reward-slot", // 要素 ID か HTMLElement
    bid, // Prebid の video 入札
    reward: "コイン50枚", // 任意: アクセントカラーで強調表示
    policy: { trigger: { type: "watchThroughOr", seconds: 15 } },
    callbacks: {
      onReward: () => grantReward(), // 特典を付与
      onClose: () => {},
    },
  });
</script>
ts
import { createRewardPlayer } from "https://cdn.michao-ssp.com/player/v1/reward.mjs";

const handle = createRewardPlayer({
  target: "reward-slot",
  bid,
  reward: "コイン50枚",
  policy: { trigger: { type: "watchThroughOr", seconds: 15 } },
  callbacks: {
    onReward: () => grantReward(),
    onClose: () => {},
  },
});

結果を待つ ​

コールバックの代わりに、result の Promise で最終結果を待つこともできます。結果は 1 度だけ解決します。

ts
const result = await handle.result;
// { status: "rewarded" | "dismissed" | "failed", reason?: string }

if (result.status === "rewarded") {
  grantReward();
}

handle.destroy(); // 早期に破棄（保留中なら "dismissed" として解決）

入札（bid）の形 ​

Prebid の video 入札の部分集合を渡します。VAST は vastXml（インライン XML）または vastUrl（タグ URL）のいずれかで指定します。

ts
const bid = {
  mediaType: "video",
  adUnitCode: "reward-slot",
  vastXml: "<VAST>…</VAST>", // または vastUrl: "https://…"
  width: 640,
  height: 360,
};

VAST は video の imp から

VAST は video の入札からのみ得られます。Prebid では video アダプタを動かしてください。banner の imp はマークアップを返し、VAST は返しません。

イベント（コールバック） ​

callbacks で各イベントを購読できます。計測やリワード付与に利用します。

コールバック発火タイミング
onImpression広告が表示された
onClick広告がクリックされた
onRewardリワードが付与された
onCloseユーザーが閉じた
onFail広告の読み込み・再生に失敗した
onQuartile再生の節目（first / mid / third / complete）

リワードポリシー ​

policy で「いつ特典が得られるか」と、閉じる・受け取りの挙動を制御します。既定は 最後まで視聴で獲得（must-watch）です。

ts
createRewardPlayer({
  target: "reward-slot",
  bid,
  policy: {
    // 一定秒数の視聴、または最後まで視聴で獲得
    trigger: { type: "watchThroughOr", seconds: 15 },
    // スキップ不可（must-watch）
    skip: { mode: "disabled" },
  },
});

長尺の広告では

既定は「最後まで視聴」です。60 秒級のクリエイティブでは、minWatch や watchThroughOr を使うと、終わる前に受け取れます。

各項目の詳細は API リファレンス を参照してください。

広告ポッド（複数広告） ​

VAST が複数の広告（sequence 付きの広告ポッド）を返す場合、各広告が順番に再生されます。policy.pod で、ポッド内のいくつを見終えれば獲得とするかを指定できます（既定は 1、"all" ですべて必須）。

ts
createRewardPlayer({
  target: "reward-slot",
  bid, // 複数広告を含む VAST
  policy: { pod: { required: "all" } }, // すべて見終えると獲得
});
2 本の広告が順番に再生され、すべて見終えると受け取れます。

バナーのリワード（display） ​

video だけでなく、banner（display）入札でもリワードを出せます。ただしクリエイティブの描画は呼び出し側で行います（Prebid renderAd / GPT）。プレイヤーは広告の描画責務を持たず、「N 秒表示で獲得」のゲーティングだけを担当します。

  • bid に mediaType: "banner" を渡し、render でスロットに描画します。
  • banner には「最後まで」が無いため、時間トリガー（minWatch / watchThroughOr）が必須です。
ts
createRewardPlayer({
  target: "reward-slot",
  bid, // banner 入札（width / height を使用）
  policy: { trigger: { type: "minWatch", seconds: 15 } },
  // クリエイティブは自分で描画する（プレイヤーは描画しない）
  render: (slot) => {
    const iframe = document.createElement("iframe");
    iframe.style.cssText = "width:100%;height:100%;border:0";
    slot.appendChild(iframe);
    window.pbjs.renderAd(iframe.contentWindow.document, bid.adId);
    // GPT の場合は googletag で slot 内に display
  },
});
render で描いたバナーを 5 秒見ると受け取れます。

計測について

display の計測（ビューアビリティ等）は Prebid / 広告サーバー側の仕組みに従います。プレイヤーは描画も計測も持ちません。

複数回表示する ​

createRewardPlayer() の呼び出しごとに 1 つのインスタンスが生成されます。もう一度表示したいときは、再度呼び出してください。前回のハンドルが残っている場合は destroy() してから生成します。

ts
let handle = null;

function showRewardAd() {
  handle?.destroy();
  handle = createRewardPlayer({ target: "reward-slot", bid, callbacks: { onReward } });
}

完全な実装例 ​

ボタンを押すとリワード広告を表示し、視聴完了でコインを付与する最小例です。

html
<!DOCTYPE html>
<html lang="ja">
  <head>
    <meta charset="UTF-8" />
    <title>リワード広告デモ</title>
    <script src="https://cdn.michao-ssp.com/player/v1/reward.js"></script>
  </head>
  <body>
    <h1>コイン: <span id="coins">0</span></h1>
    <button id="watch">動画を見て 50 コイン獲得</button>
    <div id="reward-slot"></div>

    <script>
      let coins = 0;

      document.getElementById("watch").addEventListener("click", () => {
        // bid は Prebid で取得した video 入札
        window.michao.createRewardPlayer({
          target: "reward-slot",
          bid,
          reward: "コイン50枚",
          policy: { trigger: { type: "watchThroughOr", seconds: 15 } },
          callbacks: {
            onReward: () => {
              coins += 50;
              document.getElementById("coins").textContent = coins;
            },
            onFail: () => alert("広告を読み込めませんでした。後でお試しください。"),
          },
        });
      });
    </script>
  </body>
</html>

技術的ポイント ​

  • エラー処理: 在庫切れ・ネットワークエラーに備え、必ず onFail（または result.status === "failed"）を扱ってください。計測（OMID）の失敗はリワードの失敗にはなりません。
  • ミュート再生: 既定はミュート自動再生で、ユーザーが音声をオンにできます。muted: false にすると、最初のタップで音声付き再生を開始するゲートが表示されます。
  • テーマ: theme で auto（OS 連動）/ ivory（ライト）/ noir（ダーク）、またはアクセントカラー等を指定できます。詳細は API リファレンス を参照してください。

Michao!! のプレイヤードキュメント

© Lookverin