Livedeck widget SDK:関数とイベント

livedeckオブジェクトでできること:イベント、設定、画像、サウンド、コンテキスト。

9分で読めます 2026年11月4日更新

SDKは、Livedeckが各widgetのアドレスの/sdk/v1.jsで配信している小さなライブラリです。widgetをオーバーレイに接続し、livedeckオブジェクトを提供します。

html
<script src="/sdk/v1.js"></script>

自分のコードより前に読み込んでください。ページが読み込まれると、SDKが自動でオーバーレイに接続を通知します。そのために何かを呼び出す必要はありません。

関数

livedeck.on(type, fn)

このタイプのイベントごとにfnを呼び出します。fnを解除する関数を返します。

livedeck.off(type, fn)

fnを解除します。

livedeck.ready(fn)

オーバーレイに接続され、設定が届いた時点でfnを呼び出します。Promiseも返します。

livedeck.settings

現在の設定(読み取り専用)。ユーザーが何かを変更すると、settingsイベントが届きます。

livedeck.context

{ mode, format, locale, size, scale, test }。sizeはCSSピクセル単位のページサイズ、scaleはサイズ変更されたwidgetの拡大率(デフォルトは1)。modeはlive(OBSリンク)、editor(プレビュー)、demo(Marketplace)のいずれかです。

livedeck.host

配信者の{ handle, nickname, avatar }。host.profile権限がある場合のみで、それ以外はnullです。

livedeck.image(ref)

画像参照(avatar、gift.image)をローカルの画像アドレスに変換します。アドレスまたはnullを返すPromiseです。

livedeck.media.play(key, { volume })

メディア設定keyのサウンドを、マスター音量でLivedeck経由で再生します。volumeは0〜1。media.playが必要です。trueまたはfalseを返すPromiseです。

livedeck.media.url(key)

メディア設定keyの画像またはクリップのローカルアドレス。アドレスまたはnullを返すPromiseです。

livedeck.version

"1"

イベント

gift

権限: events.gift

フィールド: user, gift { id, name, image, diamonds }, count, totalDiamonds, combo { count, ended }, toGuest

chat

権限: events.chat

フィールド: user(+isModerator, isSubscriber, fanLevel), text

like

権限: events.like

フィールド: user(またはnull), count, total

follow

権限: events.follow

フィールド: user

share

権限: events.share

フィールド: user

join

権限: events.join

フィールド: user

fanclub

権限: events.fanclub

フィールド: user

viewers

権限: events.viewers

フィールド: count

stream

権限: stream.status

フィールド: status:live、offlineまたはchecking

settings

権限: なし

フィールド: 新しい設定

context

権限: なし

フィールド: 新しいコンテキスト(例:新しいサイズ)

ready

権限: なし

フィールド: 接続後に1回

*

権限: なし

フィールド: 上記のすべてのライブイベント

すべてのライブイベントにはtypeとidがあります。userは{ handle, nickname, avatar }です。handleは@なしのTikTokユーザー名、avatarはlivedeck.image()用の画像参照です。視聴者はユーザー名("@" + handle)で表示してください。nicknameは視聴者が入力した表示名で、本名であることも多いため表示しないでください。widgetがTikTokの数値ID、メールアドレス、リンクを受け取ることはありません。

json
{
  "type": "gift",
  "id": "42",
  "user": { "handle": "lena.loops", "nickname": "Lena", "avatar": "i:7" },
  "gift": { "id": 5655, "name": "Rose", "image": "i:8", "diamonds": 1 },
  "count": 3,
  "totalDiamonds": 3,
  "combo": { "count": 7, "ended": false },
  "toGuest": false
}

ギフト

  • gift.diamondsはギフト1個あたりのコイン価格です。countはこのイベントでの新しいギフトの数、totalDiamonds = count × gift.diamondsは加算されるコイン数です。コンボはすでに差し引き済みなので、countとtotalDiamondsを合計するだけでOKです。
  • combo は表示専用の連続ギフト全体です(「Rose ×7」)。combo.count はこれまでのギフト数、combo.ended は TikTok がコンボを終了した時点で true になります。combo.count を合計したり、掛け算に使ったりしないでください。
  • コインの値は必ずイベントから取得してください。独自の価格表を使ったり、ギフト名から価格を推測したりしないでください。
  • 最大の単発ギフト:gift.diamonds を比較します。トップサポーター/ランキング:user.handle ごとに totalDiamonds を合計します。
  • マルチゲスト LIVE でギフトがゲストに贈られた場合、toGuest は true になります。
  • 特定のギフトだけを対象にするには、gift タイプの設定を使い、e.gift.id をその値と比較します。

いいね

LIVE 中、Livedeck はいいねを 500 ms ごとに 1 つのイベントにまとめます。count はその間の合計、total は LIVE 全体の合計です。

例:ギフト目標

「manifest.json リファレンス」ページの manifest.json に対応しています。ページには #bar と #label 要素が必要です。

js
let total = 0;
let reached = false;

function render() {
  const goal = Number(livedeck.settings.goal) || 100;
  const bar = document.getElementById("bar");
  bar.style.width = Math.min(total / goal, 1) * 100 + "%";
  bar.style.background = livedeck.settings.accent;
  document.getElementById("label").textContent = total + " / " + goal;
  if (!reached && total >= goal) {
    reached = true;
    if (livedeck.settings.doneSound) livedeck.media.play("doneSound", { volume: 0.8 });
  }
}

livedeck.on("gift", (e) => {
  const only = livedeck.settings.giftId;
  if (only && e.gift.id !== only) return;
  total += e.count; // counts gifts; for a diamond goal use e.totalDiamonds
  render();
});

livedeck.on("settings", render);
livedeck.ready(render);

例:プロフィール画像付きチャット

js
livedeck.on("chat", async (e) => {
  const row = document.createElement("div");
  const img = document.createElement("img");
  img.alt = "";
  row.append(img, "@" + e.user.handle + ": " + e.text);
  document.getElementById("chat").prepend(row);
  // picture reference → local address (or null, then it stays empty)
  const url = await livedeck.image(e.user.avatar);
  if (url) img.src = url;
});

知っておきたいこと

  • 名前やチャットのテキストは視聴者が入力したものです。必ず textContent で挿入し、innerHTML は使わないでください。
  • ウィジェットはブラウザストレージを使えません。localStorage、sessionStorage、IndexedDB、Cookie はブロックされます。状態はメモリに保持してください。ユーザーがオーバーレイを再読み込みすると、ウィジェットは最初からやり直しになります。
  • 読み込みは自分のパッケージからのみ可能です。他サイトへの fetch、WebSocket、フレーム、フォーム、ポップアップ、ページ移動はブロックされます。
  • オーバーレイは 2000 ms ごとにウィジェットが応答しているか確認します。コードがブラウザをブロックしない限り、SDK が自動で応答します。
  • LIVE 中、ウィジェットが受け取るメッセージは最大で毎秒 50 件です。イベントが非常に多い場合は、ギフトとチャットが優先されます。
  • ウィジェットからオーバーレイへのリクエスト(例:livedeck.image)は毎秒最大 10 件、1 件あたり最大 64 KB です。SDK は画像を記憶するため、同じ参照のコストは 1 回分だけです。
  • livedeck.media.play で再生したサウンドは Livedeck のオーディオを通るため、マスター音量とユーザーが選んだ出力先が適用されます。パッケージ内のサウンドを <audio> で再生することもできますが、その場合は Livedeck の音量設定を通りません。
  • フォントは .woff2 としてパッケージに入れ、@font-face と相対パスで読み込んでください。画像を自分で生成することもできます(canvas、data:、blob:)。

この記事は役に立ちましたか?