サイトにプレーヤーを設置する

01プレーヤーIDを取得する

プレーヤーとは、埋め込む対象そのものです。ポッドキャスト全体、または特定のエピソードを指し示し、HTMLに貼り付ける公開IDを持ちます。

1. 「アカウント」から「音声プレーヤー」を開きます。
2. プレーヤーを作成し、自分でわかる名前を付けて、再生する内容を追加します。ポッドキャスト全体、1エピソード、または任意の順序で複数のエピソードを指定できます。
3. プレーヤーIDをコピーします。
4. 変更を公開し、プレーヤーを有効にしておきます。下書きの変更は訪問者には表示されません。

音声プレーヤーを開く

IDは公開される前提のものです。ページのソースに書かれ、誰でも読める状態になりますが、問題ありません。このIDが許可するのは1つだけ、そのプレーヤーに入れたエピソードを再生することです。APIキーではなく、アカウント内の他の情報には一切届きません。プレーヤーを無効にすれば、すべての場所で同時に無効になります。

番組全体を選んだプレーヤーには、新しく完成したエピソードが自動表示されます。選択したエピソードや設定を変更したら、その変更を公開してください。埋め込みコードの貼り直しは不要です。

022行貼り付ける

YOUR_WIDGET_IDをご自身のプレーヤーIDに置き換えてください。scriptをページに、divを表示したい場所に置きます。サイト作成ツールでは、スクリプトを許可するカスタムHTMLまたは埋め込みブロックを使ってください。

<script src="https://www.obbo.me/player/obboplayer.js" async></script>
<div data-obbo-player="YOUR_WIDGET_ID"></div>

これで導入は完了です。スクリプトは data-obbo-player 属性を持つ要素をすべて見つけて描画します。ページ上のプレーヤーが1つでも10個でも同じです。スクリプトを2回読み込んでも問題ありません。

音声は再生を押した後にダウンロードされます。エピソード一覧とカバー画像はページと一緒に読み込みますが、音声は訪問者が再生を始めた後に要求されます。ページの表示だけでは再生に数えられません。

03公開ページを確認する

サイトを保存・公開し、訪問者と同じようにページを開いてください。編集画面のプレビューではスクリプトを実行しないツールもあります。

• Obboにログインしなくても番組名と完成したエピソードが表示されることを確認します。
• 再生、シーク、一時停止を試します。操作する前に音声が始まらないことも確認してください。
• スマートフォンと広い画面の両方で確認します。表示されない場合は、サイトの編集ツールがカスタムHTMLと外部スクリプトを許可しているか確認してください。

設置完了です。ここで終了して構いません。別のレイアウトや独自デザイン、カスタム開発が必要な場合だけ、以下をお読みください。

04レイアウトを選ぶ

6つの表示レイアウトとautoがあります。data-obbo-uiで指定してください。省略またはautoなら、公開済みのコンパクト・一覧設定に従います。

プレーヤーの試用ページに戻る

<script src="https://www.obbo.me/player/obboplayer.js" async></script>
<div
  data-obbo-player="YOUR_WIDGET_ID"
  data-obbo-ui="list"
  data-obbo-theme="dark"
></div>

すべての属性

1ページに複数のプレーヤーを置いても問題ありません。エピソード一覧の取得は1回にまとめられ、ひとつを再生すると他は一時停止します。訪問者が2つの音声を同時に聞くことはありません。

05サイトになじませる

プレーヤーはiframeではなくページ内に描画されます。以下の変数で色、角丸、フォントを合わせられます。例にはHTMLとCSSをつなぐクラスも含まれています。

手早く: 9つの変数

<div class="my-player" data-obbo-player="YOUR_WIDGET_ID"></div>

<style>
  .my-player {
    --obbo-player-accent: #a1482e;
    --obbo-player-radius: 8px;
    --obbo-player-font: system-ui, sans-serif;
  }
</style>

しっかり: クラス名

安定したobbo-クラスで操作部を指定できます。ブランド調整には変数、詳細な変更にはクラスを使ってください。data-obbo-stateで読み込みやエラー時の表示を調整できます。再生できないことが伝わるよう、エラーメッセージは隠さないでください。

.obbo-p[data-obbo-state="loading"] { opacity: 0.6; }
.obbo-p[data-obbo-state="error"] .obbo-note { font-weight: 700; }

CSSの影響が強い場合は切り離してください。ページ内レイアウトにdata-obbo-isolateを追加すると、サイトのCSSから保護できます。9つの変数は有効ですが、クラスによる内部の変更はできなくなります。dockはドキュメントに直接追加され、shadow分離には対応しません。

06独自のプレーヤーを作る

用意されたレイアウトを一切使わない方法です。createPlayer がエピソード情報、再生、再生位置を渡すので、マークアップはご自身で書けます。試聴の記録も、期限切れになった音声リンクの復帰も、そのまま働き続けます。下にある操作部は、その下のコードが実際に動いているものです。

<script src="https://www.obbo.me/player/obboplayer.js" async></script>

<button id="play" type="button" disabled>Play</button>
<span id="time">0:00</span>

<script>
  addEventListener('load', function () {
    var player = Obbo.createPlayer({ widgetId: 'YOUR_WIDGET_ID' });
    var button = document.getElementById('play');
    var time = document.getElementById('time');

    player.subscribe(function (state) {
      button.disabled = state.status !== 'ready' || !state.playable;
      button.textContent = state.playing ? 'Pause' : 'Play';
      time.textContent = Obbo.formatTime(state.position);
    });

    button.onclick = function () { player.toggle(); };
  });
</script>

status が ready になるまでボタンは無効にしてください。iOSでは、音声を再生する許可はそれを求めたタップに結び付いています。プレーヤーがまだ応じられないタップは無駄になり、訪問者はもう一度タップすることになります。

07音声に追従する文字起こし

文字起こしレイアウトは、エピソード全体をテキストとしてページに置き、音声と歩調を合わせます。Obboのエピソードは制作の一環として文単位のタイムスタンプ付きで書き起こされるため、準備は不要です。

• 話している行がハイライトされ、自動で見える位置までスクロールします。読者が自分でスクロールすると追従を止め、戻るためのボタンを出します。スクロールを奪い合うことはありません。
• 任意の行をクリックするとそこから再生されるので、エピソードが引用可能になります。読者は目当ての一文を見つけて、それが語られるのを聴けます。
• 文字起こしは選択できるテキストで、読み込み後は支援技術で読めます。検索での表示が重要な文章はページ自身のHTMLにも置いてください。JavaScriptで描画した文章の索引化は保証されません。

<script src="https://www.obbo.me/player/obboplayer.js" async></script>
<div data-obbo-player="YOUR_WIDGET_ID" data-obbo-ui="transcript"></div>

各エピソードで利用できる文字起こしを表示します。完成した文字起こしは埋め込みAPIから配信されます。存在しない場合も音声は再生でき、その旨が表示されます。プレーヤーの試用ページで読み合わせを体験できます。

08APIリファレンス

Obbo.createPlayer(options)

プレーヤー

状態

Obbo のその他

09React、Vue など

自動スキャンに頼らないでください。コンテナを再描画するフレームワークはプレーヤーのマークアップを消し去り、イベントリスナーだけを残します。自分で設置し、アンマウント時に破棄してください。設置先の要素には自分で何も描画しないでください。

import { useEffect, useRef, useState } from 'react';

let sdkPromise;
function loadPlayer() {
  if (window.Obbo) return Promise.resolve(window.Obbo);
  if (sdkPromise) return sdkPromise;
  sdkPromise = new Promise((resolve, reject) => {
    const script = document.createElement('script');
    script.src = 'https://www.obbo.me/player/obboplayer.js';
    script.async = true;
    script.onload = () => {
      if (window.Obbo) resolve(window.Obbo);
      else {
        sdkPromise = null;
        script.remove();
        reject(new Error('Player SDK unavailable'));
      }
    };
    script.onerror = () => {
      sdkPromise = null;
      script.remove();
      reject(new Error('Player SDK could not load'));
    };
    document.head.appendChild(script);
  });
  return sdkPromise;
}

export function Player({ widgetId, locale = 'en' }) {
  const host = useRef(null);
  const [failed, setFailed] = useState(false);
  const [attempt, setAttempt] = useState(0);

  useEffect(() => {
    let cancelled = false;
    let cleanup;
    loadPlayer().then((Obbo) => {
      if (cancelled) return;
      const player = Obbo.createPlayer({ widgetId, locale, language: locale });
      const ui = Obbo.ui.list(host.current, player, { locale });
      cleanup = () => { ui.destroy(); player.destroy(); };
    }).catch((error) => {
      if (!cancelled) {
        console.error('Player failed to load', error);
        setFailed(true);
      }
    });
    return () => { cancelled = true; cleanup?.(); };
  }, [widgetId, locale, attempt]);

  return <>
    <div ref={host} />
    {failed && <p role="alert">
      The player could not load.
      <button type="button" onClick={() => {
        setFailed(false);
        setAttempt((value) => value + 1);
      }}>Try again</button>
    </p>}
  </>;
}

この例はSDKの読み込みを待ち、遅れたマウントを中止し、終了時に表示とプレーヤーを破棄します。サイトの言語をlocaleに渡してください。VueやSvelteでも同じライフサイクルを使います。インライン例にはCSP nonceや外部JavaScriptファイルが必要な場合があります。

10Content-Security-Policy

Content-Security-Policyを使うサイトでは、開発者と以下を確認してください。既存のポリシーに必要なホストを追加します。この表はそのまま貼れる完全なポリシーではありません。

見落とされるのは media-src です。音声はAPIとは別のホストのストレージから配信されます。これを省くと、プレーヤーは一見まったく正常に見えたまま、誰かが再生を押した瞬間に失敗します。

11記録される内容

サイトでの試聴は Obbo の分析に表示されます。プレーヤーが読み込まれた回数、再生が始まった回数、そして実際に聴かれた量です。

• 訪問者が特定されることはありません。アカウントもログインも不要で、プレーヤーはCookieを設定しません。レポートは所有者であるあなたに紐づき、聴いている人には紐づきません。
• ページの表示は再生ではありません。音声が実際に始まるまで、再生としては数えられません。
• 試聴時間は推測ではなく計測です。early飛ばした部分は聴いたことになりません。

12うまくいかないとき

それでも解決しない場合ページのアドレス、プレーヤーID、Obbo.version の値を添えてご連絡ください: hello@obbo.me