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

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

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

1. 「アカウント」から「音声プレーヤー」を開きます。
2. プレーヤーを作成し、自分でわかる名前を付けて、再生する内容を追加します。ポッドキャスト全体、1エピソード、または任意の順序で複数のエピソードを指定できます。
3. プレーヤーIDをコピーします。

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

後からエピソードを追加すると、そのプレーヤーのすべての埋め込みに即座に反映されます。貼り直しは不要です。

022行貼り付ける

スクリプトはページのどこに置いても構いません。divはプレーヤーを表示したい場所に置きます。

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

<div data-obbo-player="YOUR_PLAYER_ID"></div>

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

誰かが再生を押すまで、何もダウンロードされません。プレーヤーは読み込み時にエピソード一覧を取得しますが、実際に誰かが再生を始めるまで音声は要求されません。ページにプレーヤーを置いても訪問者に負担はかからず、実際には起きていない再生が記録されることもありません。

03レイアウトを選ぶ

7種類が用意されています。data-obbo-ui で指定してください。省略すると、プレーヤー作成時に選んだものが使われるので、ページを編集せずに後から変更できます。

<div data-obbo-player="YOUR_PLAYER_ID"
     data-obbo-ui="list"
     data-obbo-theme="dark"></div>

すべての属性

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

04サイトになじませる

プレーヤーは閉じたフレームではなく、ページ自身のDOMに描画されます。スタイルシートが届き、フォントも継承されます。

手早く: 9つの変数

.my-player {
  --obbo-player-accent: #e5484d;
  --obbo-player-radius: 4px;
  --obbo-player-font: 'Söhne', system-ui, sans-serif;
}

@media (prefers-color-scheme: dark) {
  .my-player {
    --obbo-player-bg: #181d24;
    --obbo-player-fg: #f2f5f8;
  }
}

しっかり: クラス名

各要素には obbo- で始まる安定したクラス名が付いており、こちらが提供するルールはすべて単一クラスセレクタです。そのため !important なしでご自身のルールが優先されます。ルート要素には data-obbo-state も付くので、内部構造を知らなくても読み込み中やエラー時の見た目を調整できます。

.obbo-p[data-obbo-state="loading"] { opacity: 0.6; }
.obbo-p[data-obbo-state="error"]   { display: none; }

CSSの影響が強い場合は切り離してください。強力なフレームワークのリセットはプレーヤーにも届きます。data-obbo-isolate を追加すると shadow root 内に描画され、スタイルシートの影響を受けません。9つの変数は引き続き有効なので、色の調整は残り、クラス単位の調整だけができなくなります。

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

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

<button id="play" disabled>Play</button>
<span id="title"></span>
<div id="track"><div id="fill"></div></div>

<script>
  var player = Obbo.createPlayer({ widgetId: 'YOUR_PLAYER_ID' });

  player.subscribe(function (state) {
    play.disabled     = state.status !== 'ready';
    play.textContent  = state.playing ? 'Pause' : 'Play';
    title.textContent = state.episode ? state.episode.title : '';
    fill.style.width  = (state.position / state.duration * 100) + '%';
  });

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

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

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

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

• 話している行がハイライトされ、自動で見える位置までスクロールします。読者が自分でスクロールすると追従を止め、戻るためのボタンを出します。スクロールを奪い合うことはありません。
• 任意の行をクリックするとそこから再生されるので、エピソードが引用可能になります。読者は目当ての一文を見つけて、それが語られるのを聴けます。
• テキストはページ内の本物のテキストなので、検索エンジンが索引化し、スクリーンリーダーが読み上げます。そのままでは中身の見えない音声の箱だったエピソードが、テーマに関するコンテンツになります。

<div data-obbo-player="YOUR_PLAYER_ID"
     data-obbo-ui="transcript"></div>

まだ有効になっていません。文字起こしは全エピソードで生成されていますが、埋め込みAPIではまだ公開していないため、現時点ではテキストの代わりに注記を添えたプレーヤーが表示されます。こちらでフィールドを有効にすれば自動的に表示されます。ページ側の変更は不要です。

07APIリファレンス

Obbo.createPlayer(options)

プレーヤー

状態

Obbo のその他

08React、Vue など

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

function Player({ widgetId }) {
  const host = useRef(null);

  useEffect(() => {
    const player = Obbo.createPlayer({ widgetId });
    const ui = Obbo.ui.list(host.current, player);
    return () => { ui.destroy(); player.destroy(); };
  }, [widgetId]);

  return <div ref={host} />;
}

スクリプトは、エフェクトが動く前に一度だけ、document の head か小さなローダーで読み込んでください。Vue の onMounted と onUnmounted、Svelte の onMount でも同じです。

09Content-Security-Policy

サイトが Content-Security-Policy ヘッダーを送っている場合、3つのディレクティブが必要です。

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

10記録される内容

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

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

11うまくいかないとき

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