Shoplive ショートフォーム Web SDK 連携ガイド
視聴者がどこでショートフォームに出会うかを基準に、ページへの組み込み方を説明します。ミッションは順番ではなくリストなので、必要なものだけ選んで適用してください。
概要 & 要件
Shoplive ショートフォーム Web SDK は、スクリプトタグ 1 行でショートフォームを Web ページに組み込みます。パッケージのインストールやビルドツールの設定は不要です。SDK が描画する画面は 5 種類です。
| 画面 | 何か | どこに置くか |
|---|---|---|
| 一覧（コレクション） | ショートフォームのカードが並ぶフィード。カードをタップするとプレイヤーが開きます | メイン · ショートフォームタブ · 特集ページ |
| プレイヤー | 全画面の縦型動画に商品 · コメント · いいね · 共有が付いたもの。以下すべての経路の到達先です | モーダルとして自動生成（または自分の領域にインライン） |
| プレビュー | 画面の隅に浮かび、ミュートで自動再生される小さなプレイヤー | 商品詳細 |
| ショーケース | 商品画像ギャラリーの位置を占めるショートフォームカード | 商品詳細 · 商品一覧のタイル |
| ストーリー | ブランド・タグ・グループごとに円を 1 つずつ、インスタグラムのストーリーのように横に並べます | メイン · ショートフォーム タブ |
必要なもの
| 項目 | 確認方法 |
|---|---|
| Access Key | Shoplive Admin で確認します。ライブ SDK と同じキーを使用します |
| 公開済みのショートフォーム | Shoplive Admin にショートフォームが 1 件以上登録・公開されている必要があります |
| （商品連携を行う場合）商品 URL | ショートフォームに紐づけた商品に遷移先 URL が登録されていないと、クリックしても商品ページに遷移しません |
導線マップ — 自社のページはどれですか？
視聴者がいるページを選べば、組み込むものが決まります。上の 5 つは互いに独立していて順番はありません — 1 つだけ使っても、複数を組み合わせても構いません。下の 4 つは、どの方法で表示した場合でもその後に共通して必要になるものです。機能名がすでに分かっている場合は、左サイドバーから直接移動してください。
| 視聴者がいる場所 | 組み込むもの | ガイド |
|---|---|---|
| メイン · ショートフォームタブ · 特集ページ | 一覧（コレクション） | ミッション 1 · コレクション — 一覧として表示 |
| 商品詳細 — 隅にさりげなく | プレビュー | ミッション 3 · プレビュー — 画面の隅に浮かせる |
| 商品詳細 — ギャラリーの位置に大きく · 商品一覧のタイル | ショーケース | ミッション 4 · ショーケース — 商品ギャラリーの位置に |
| メイン · ショートフォーム タブ — ブランドやタグで選んで見せる | ストーリー | ミッション 2 · ストーリー — ブランド · タグごとにまとめて見せる |
| バナー · ボタン · イベントのランディング | コードでプレイヤーを開く | ミッション 5 · プレイヤー — コードから直接開く |
| （表示したあと）共有されたリンク · 広告 URL | ディープリンク | ミッション 6 · ディープリンク — 共有リンクから開く |
| （表示したあと）コメント · いいね · ブックマーク | ユーザー情報 | ミッション 7 · ユーザー情報の連携 |
| （表示したあと）商品クリック · 共有 · アナリティクス | イベント処理 | ミッション 8 · イベント · 商品クリック · データ収集 |
| （表示したあと）購入完了ページ — 視聴が購入につながったか | コンバージョン報告 | ミッション 9 · 購入コンバージョン計測 |
| モーダルではなく自分の領域にプレイヤー · Shopify · SPA など | — | 付録 |
shoplive.js）とショートフォーム（shoplive-shortform.js）は別々のスクリプトですが、同じ window.cloud.shoplive オブジェクトに関数を追加する方式のため、1 つのページに同時に読み込めます。初期化はそれぞれ（initPlugin / initShortform）呼び出し、ユーザー情報の関数（setUserObject · setUserJWT · logout）は両 SDK で共有されるので 1 回だけ呼び出します。クイックスタート
最短の手順でショートフォーム一覧を表示する例です。スクリプトタグ 1 行、初期化 1 行、表示 1 行です。
<script src="https://static.shoplive.cloud/shoplive-shortform.js"></script>
<script>
cloud.shoplive.initShortform({ accessKey: 'YOUR_ACCESS_KEY' });
</script>
<div id="shoplive-shortform-area"></div>
<script>
cloud.shoplive.setShortformCollection('shoplive-shortform-area');
</script>呼び出し順のルール
initShortform()はページ内で1 回だけ呼び出します。2 回目以降は無視されます。- 表示関数（
setShortformCollection·showShortformPreview·setShortformShowcase·showShortformPlayerModal）はinitShortform()より前に呼び出しても、内部のキューに積まれ、初期化が完了すると自動的に実行されます。スクリプトが<head>と<body>に分かれていても構いません。 - ただし SDK のスクリプトタグ自体は、
cloud.shopliveを呼び出すコードより前に置く必要があります。
次のステップ画面の用語ガイド →
画面の用語ガイド
ショートフォーム SDK は同じ動画をいくつかの形で表示します。各ミッションではその形の名前をそのまま使うため、「ショーケースはプレビューと何が違うのか」と迷ったらこの節に戻ってきてください。形をクリックすると該当ミッションに移動します。
画面の形
上の図は実際の画面ではなく、形だけを描いたものです。どこに置くかは導線マップにあります。
実際の画面
div の中に SDK がカード一覧をまとめて描画し、もっと見る · フィルタータブ · クリック時のプレイヤー起動までその中で処理します。ヘッダーなどページの他の部分はそのままです。
混同しやすい組み合わせ
| 用語 | 混同しやすい相手 | 見分け方 |
|---|---|---|
| コレクション | Admin の「グループ」· カード 1 枚 | 画面でいうコレクションは一覧領域全体です。一方、コードの shortformCollectionId は運営者が Admin でキュレーションしたまとまりを指し、Admin の画面ではそれを「グループ」と呼びます（ミッション 2） |
| プレビュー | ショーケース | プレビューはページの上に浮かぶのでレイアウトはそのまま、ショーケースはギャラリーの位置を置き換えるのでレイアウトの中に入ります。どちらも商品 URL 連携を使い、同じページに併用もできます |
| プレイヤー | コレクション · プレビュー · ショーケース | プレイヤーはこれらすべての到達点です。既定では画面を覆うモーダルとして開き、自分の領域にインラインで埋め込むこともできます（付録 A） |
前へ ← クイックスタート次へ → ミッション 1 · コレクション — 一覧として表示
ミッション 1 · コレクション — ショートフォーム一覧をページに表示する
コレクションは id を持つ空の div に描画されます。カードをクリックすると SDK が自動的にプレイヤー（モーダル）を開き、そのショートフォームから再生するため、一覧を敷くだけで再生まで動作します。コレクションが画面上でどこまでを指すのかは画面の用語ガイド · 実際の画面にあります。
ステップ 1 · レイアウトを選ぶ
GRID1 デフォルトカードが大きいGRID2カードが小さいHORIZONTAL1 行で横スクロール| テンプレート | 見た目 | 向いている場所 |
|---|---|---|
GRID1 | カードが大きく表示され、タイトル · ブランドがカードの上に重ねて表示されます。デフォルト値 | ショートフォームが主役の特集 · 専用タブ |
GRID2 | カードが小さく表示され、タイトル · ブランドがカードの下に表示されます。同じ画面に GRID1 より多くのショートフォームが入ります | 他のコンテンツと並ぶ一覧領域 |
HORIZONTAL | 折り返さず 1 行に並び、横スクロールします。左右の矢印 · 自動フローのオプションがあります | メインページの帯、商品詳細下部の「関連ショートフォーム」 |
ステップ 2 · どのショートフォームを見せるか — フィルター 任意
このステップは飛ばしても構いません。 フィルターを 1 つも指定しなければ、Admin で公開されているショートフォームがデフォルトの順序で表示されるため、ステップ 1 の setShortformCollection('コンテナid') 1 行だけで一覧は動作します。以下のオプションは特定の条件のショートフォームだけを表示したいときに、必要なものだけ選んで追加してください。
<div id="shoplive-shortform-area"></div>
<script >
cloud.shoplive.setShortformCollection('shoplive-shortform-area', {
template: 'HORIZONTAL',
tags: ['sale', 'new'], // タグでフィルター。文字列ではなく配列で渡します
tagSearchOperator: 'OR', // 'OR' いずれか一致 · 'AND' すべて一致
displayTags: ['sale', 'new', 'best'], // 一覧の上部にフィルタータブとして表示
horizontalOption: { hasDirectionWhenHorizontal: true, lineItemCount: 4 }
});
</script>| オプション | 説明 |
|---|---|
tags: string[] | Admin でショートフォームに付けたタグでフィルター。tagSearchOperator で OR/AND を選択 |
brands: string[] | ブランド識別子でフィルター |
skus: string[] | 紐づく商品 SKU でフィルター — 商品詳細下部の「この商品が登場するショートフォーム」に適しています |
shortformCollectionId | Admin で作成したグループをそのまま表示 |
shuffle: true | ランダム順 |
sortProperty / sortDirection | 並び替えの基準と方向。sortProperty は 'createdAt'（登録日） · 'updatedAt'（更新日） · 'viewCount'（再生） · 'likeCount'（いいね） · 'commentCount'（コメント） · 'shareCount'（共有） · 'bookmarkCount'（ブックマーク）のいずれか、sortDirection は 'asc' | 'desc' です。指定しない場合は Admin で設定した順序がそのまま使われます |
displayTags: string[] | 一覧の上部にフィルタータブとして表示するタグ。視聴者がタブを押して絞り込めます |
brands · tags は必ず配列で
tags: 'sale' のように文字列を渡すと、コンソールに "tags" property must be array というエラーが出て描画が中断されます。値が 1 つでも ['sale'] のように配列で囲んでください。ここに入れる tags · brands の値は、Admin でショートフォームに設定した値と正確に一致している必要があります。どこで決まるかは以下のとおりです。
tags · displayTags で、Brand に紐づけたブランドが brands でフィルターされます。1 つのショートフォームにタグは 5 個まで付けられます。
brands に渡す値はブランド名（Title）ではなく Brand Identifier です。ブランド作成時に決めたこの文字列をそのまま配列に入れてください。ステップ 3 · もっと読み込むときの方式 — ボタン vs 無限スクロール 任意
このステップも飛ばせます。 何も指定しなければ一覧の下にもっと見るボタンが付きます（hasMoreButton のデフォルトは true）。false にするとボタンがなくなる代わりに無限スクロールになるので、そうしたいときだけ指定してください。
| 設定 | GRID1 · GRID2 | HORIZONTAL |
|---|---|---|
hasMoreButton: true（デフォルト） | 下部にもっと見るボタン。押すと次のまとまりが追加され、フォーカスが新しいカードに移ります | スクロールの終わりに近づくと自動的に次のまとまりを読み込みます |
hasMoreButton: false | 一覧の末尾が画面に入ると自動的に読み込みます（無限スクロール） | 自動読み込み。ただし limit を併せて指定するとその件数で止まります |
| オプション | 説明 |
|---|---|
rows | 最初に表示する行数。デフォルトは 2 |
limit | 一覧に表示するショートフォームの最大数。HORIZONTAL + hasMoreButton: false では「ちょうど N 件だけ」見せる用途に使います |
ステップ 4 · 表示オプション 任意
このステップもすべて任意です。指定しなければ以下のデフォルト値で動作します。
| オプション | デフォルト | 説明 |
|---|---|---|
productLayout | 'CIRCLE' | カードに表示される商品サムネイルの形（'CIRCLE' 円形 · 'CARD' カード型）。アカウントに別途設定がある場合はその値が 'CIRCLE' より優先され、コードで指定するとそれよりさらに優先されます |
disablePreviewVideoPlay | false | true にすると、カードにマウスを乗せたときのプレビュー動画の再生を無効にします |
previewVideoAutoPlayType | なし | 'intersection' を指定すると、カードが画面に入ったタイミングでプレビュー動画を再生します（HORIZONTAL 以外のテンプレート） |
horizontalOption.hasDirectionWhenHorizontal | false | true にすると、横スクロールの左右に矢印ボタンを表示します（HORIZONTAL 専用） |
horizontalOption.lineItemCount | なし | 1 行に表示するカード数。指定するとコンテナ幅をこの数で割ってカード幅を計算します。指定しない場合はテンプレートのデフォルト幅です（HORIZONTAL 専用） |
horizontalOption.autoFlow | false | true にすると、カードが右から左へ自動的に流れます（HORIZONTAL 専用） |
horizontalOption.insideDescription | false | true にすると、ブランド・タイトル・説明をカードの下ではなくカード内部の下側（グラデーションの上に白文字）に表示します。カード下の情報エリアは描画しません（HORIZONTAL 専用） |
horizontalOption.scrollIndicator | false | true にすると、リストの下に横スクロールの進行バーを表示します。クリック・ドラッグで移動でき、カードが画面内に収まりスクロールする余地がない場合は描画しません（HORIZONTAL 専用） |
showProduct | false | true にすると、各カードの下に紐付いた商品を最大 2 件（サムネイル・商品名・価格）表示します。商品が 2 件以上あると商品をもっと見るリンクが付き、タップするとプレイヤーが開きます（モバイルレイアウトでは商品リストが開いた状態で遷移）。このときカード内部の商品ボタンは重複するため非表示になります — 内部ボタン自体は Admin のコレクション設定で別途制御します |
enableGestureSlide | true | false にすると、ドラッグ / スワイプを無効にし、矢印ボタンだけで移動します |
disableQueryParamHistory | false | true にすると、カードのクリック時に URL へショートフォーム ID を記録しません — ディープリンクを参照 |
横スクロールの帯に商品リストとカード内の説明まで組み合わせた例です。3 つのオプションはそれぞれ独立しているため、必要なものだけ選んで使えます。
// 横スクロール + カード下の商品リスト + タイトル・説明をカード内に + スクロール進行バー
cloud.shoplive.setShortformCollection('shoplive-shortform-area', {
template: 'HORIZONTAL',
showProduct: true,
horizontalOption: {
insideDescription: true,
scrollIndicator: true,
hasDirectionWhenHorizontal: true,
lineItemCount: 5
}
});showProduct の商品リストは、まずリスト取得レスポンスに含まれる商品で描画し、紐付いた商品がさらにある場合はカードが画面に入ったときに残りを 1 回だけ取得します。表示カード数の分だけリクエストが増えるため、ショートフォームごとに多くの商品を紐付けたリストでは limit・rows で最初の画面のカード数を調整してください。
ステップ 5 · 後片付け 任意
タブの切り替えなどで一覧を取り除く必要があるときは destroyShortformCollection('コンテナid') を呼び出します。引数を省略するとページ上のすべてのコレクションを削除します。同じコンテナに setShortformCollection を再度呼び出すと既存の一覧を片付けてから描き直すので、フィルターを変えて描き直す場合は destroy なしで再呼び出しして構いません。
完了の確認
- 指定した
divの位置に、選んだテンプレートの見た目でショートフォームカードが描画される - カードをクリックすると全画面プレイヤーが開き、そのショートフォームから再生される
- 一覧の末尾でもっと見るボタン（または無限スクロール）により次のまとまりが続く
- フィルターを掛けた場合、条件に合うショートフォームだけが表示される — 何も表示されないときは、Admin に該当するタグ · SKU の公開ショートフォームがあるか確認してください
ミッション 2 · ストーリー — ブランド · タグごとにまとめて見せる
条件 1 つが円 1 つです。ブランドを 3 つ渡せば円が 3 つでき、それぞれがその条件のショートフォームのまとまりを表します。視聴者が円をタップするとそのまとまりが開きます。
上のキャプチャのようにブランドだけで円を描くには、brands だけを渡します。渡した順に左から円が並びます。配列には Admin ブランドの Identifier を入れます — 円の下に表示されるブランド名（Title）ではないので、大文字・小文字までそのまま書き写してください（ステップ 1 の ② を参照）。
// キャプチャと同じストーリー — ブランド 3 つ = 円 3 つ
cloud.shoplive.setShortformStory('story-tray', {
brands: ['shoplive', 'shoplive2', 'TESTER']
});<div id="story-tray"></div>
<script>
cloud.shoplive.setShortformStory('story-tray', {
brands: ['mybrand'],
tags: ['新着'],
shortformCollectionIds: ['1272599072386056193']
});
</script>上の例では円 3 つのストーリーが描かれます — ブランド 1 つ + タグ 1 つ + グループ 1 つ。
ステップ 1 · どの円を作るか
3 種類の条件は混ぜて使え、配列に入れた順に円が並びます。円のラベルと画像はSDK が取得結果から自動で拾います — 指定するものではありません。
| 条件 | 円のラベル | 円の画像 |
|---|---|---|
brands | ブランド名。なければ渡した識別子そのまま | ブランドロゴ → なければ最初のショートフォームのサムネイル |
tags | タグ文字列そのまま | 最初のショートフォームのサムネイル |
shortformCollectionIds | グループのタイトル。なければ ID そのまま | 最初のショートフォームのサムネイル |
shortformCollectionIds に入れる値は、Admin で運営者がキュレーションしたショートフォーム グループの ID です。コード上の名前（collection）と Admin の表記（グループ）が異なるので、担当者と話すときに取り違えないようご注意ください。同じ値をコレクション・プレビューでは shortformCollectionId（単数）として使います。3 つの条件の値はいずれも Admin のショートフォーム編集画面で決まります。どこで確認するかを順に見ていきます。
brands・tags・shortformCollectionIds に対応します。ここで設定した値とコードに渡す値が一致して初めて、その円にショートフォームが集まります。
brands に入れる値は Identifier 列です — 数字の ID でも、画面に見える Title でもありません。上の画面のように Title が同じ Shoplive のブランドが 2 つあっても Identifier（Shoplive・shoplive）で区別されるので、大文字・小文字までそのまま写してください。
shortformCollectionIds に入れるグループ ID です。隣のリンクアイコンでコピーできます。
該当するショートフォームが 0 件の円、取得に失敗した円は描画されません。条件を 3 つ渡したのに円が 2 つしか見えない場合、残り 1 つに公開済みのショートフォームがありません — どの円がどうなったかはレンダー結果イベントで確認できます。
ステップ 2 · 円をタップしたとき 任意
既定では全画面のプレイヤー モーダルが開きます。grid: true を渡すと代わりにストーリーの下にその条件のコレクションが敷かれます。
既定（grid 未指定） | grid: true | |
|---|---|---|
| 最初の表示 | ストーリーだけが見えます | 最初の円が自動で有効になり、そのコレクションも一緒に見えます |
| 円をタップすると | プレイヤー モーダルが開きます | モーダルは開かず下のコレクションがその条件に入れ替わります |
| プレイヤーが開くのは | 円をタップしたとき | 下のコレクションのカードをタップしたとき |
// ストーリーの下にコレクションも敷き、円で切り替えて見せる
cloud.shoplive.setShortformStory('story-tray', {
brands: ['brand-a', 'brand-b'],
grid: true
});
// コレクションをストーリーの直下ではなくページの別の場所に置きたい場合
cloud.shoplive.setShortformStory('story-tray', {
brands: ['brand-a', 'brand-b'],
grid: true,
gridContainerId: 'my-collection-area'
});gridContainerId で指定した要素が存在しない場合や、ストーリー自身またはその祖先を指している場合（ストーリーが自分自身を消してしまいます）は、コンソールに警告を残してストーリーの直下に戻します。コレクションのレイアウトは GRID2 固定で、コレクションの template・rows などのオプションはこのモードでは指定できません。
ステップ 3 · 新着の表示 — 虹色リングとグレーのリング
インスタグラムと同じルールです。まだ見ていないショートフォームがあれば虹色のリング、すべて見ていればグレーのリングです。自社で行うことはなく、SDK が処理します。
- 記録されるのはタップした時点です — 円が画面に描かれただけでは「見た」ことになりません
- ブラウザの
localStorageに保存するため端末・ブラウザごとに別です。ログインの有無とは無関係です - 次回の訪問時、保存した一覧にないショートフォームが 1 つでもあれば再び虹色になります。削除されただけならグレーのままです
レンダー結果の確認 任意
0 件の円は静かに消えるので、どの条件が空だったかを知りたい場合は ON_SHORTS_STORY_RENDERED を購読してください。円ごとの結果が配列で届きます。
cloud.shoplive.addShortformEventListener(function (event) {
if (event.name !== 'ON_SHORTS_STORY_RENDERED') return;
event.payload.items.forEach(function (item) {
// { type: 'brand' | 'tag' | 'collection', identifier, success, label, shortsCount }
if (!item.success || item.shortsCount === 0) {
console.warn('円が描画されませんでした:', item.type, item.identifier);
}
});
});後片付け
SPA でページを離れるときに呼びます。引数を省略するとページ上のすべてのストーリーを削除します。grid モードで敷かれたコレクションも一緒に片付きます。
cloud.shoplive.destroyShortformStory('story-tray');知っておきたいこと — 同じページに同じ条件の円が 2 つあると、リングの色はすぐには同期しません（次回の読み込みで揃います）。また2 つのストーリーが同じ gridContainerId を指す場合は、後から描いた方が勝ちます。引数なしの destroyShortformCollection() は grid モードで敷かれたコレクションも削除します。
完了の確認
- 指定した
divの中に条件の数だけ円が描かれる（ショートフォームが 0 件の条件を除く） - 円の下のラベルがブランド名 · タグ · グループのタイトルで出る
- 円をタップするとプレイヤーが開く（
grid: trueなら下のコレクションが入れ替わる） - 一度タップした円は、再訪時にグレーのリングに変わる
前へ ← ミッション 1 · コレクション — 一覧として表示次へ → ミッション 3 · プレビュー — 画面の隅に浮かせる
ミッション 3 · プレビュー — 画面の隅に小さく浮かせる
initShortform() 済み · Shoplive Admin へのアクセス権限（ステップ 1 で使用）プレビューは画面の四隅のいずれかに浮かぶミュートされた小さなプレイヤーです。コンテナを用意する必要はなく SDK がページに直接追加します。視聴者が閉じたあと、一定時間再表示しないようにもできます。
ステップ 1 · Admin で商品 URL を紐づける
プレビューで実際に手間がかかるのはコードではなく Admin の設定です。呼び出しは showShortformPreview() の 1 行で済みますが、その 1 行が何を表示するかは Admin に登録された商品 URL が決めるからです。
SDK はプレビューを表示する際、現在のページのアドレスをサーバーに送り「このアドレスに紐づくショートフォーム」を探します。そのため Admin で次の 2 つができている必要があります。
- 商品に URL を登録します。 視聴者が実際に見る自社の商品詳細ページのアドレスをそのまま入れます。この値がプレビュー検索の基準になります。
- その商品をショートフォームに紐づけて公開します。 紐づく商品がない、またはショートフォームが非公開だと検索結果が 0 件となり、プレビューは表示されません。
?utm_source=…）や www の有無といった些細な違いでも検索は外れます。同じ商品が複数のアドレスで開くサイトでは、ステップ 2 の sku 方式を使ってください。ステップ 2 · 何を表示するかを決める
Admin の準備が終われば、呼び出しは 1 行です。以下の 3 つからページの性格に合うものを選んでください。
| 呼び出し | 表示するショートフォーム | 使いどころ |
|---|---|---|
showShortformPreview() | 現在のページ URL に紐づく関連ショートフォーム（デフォルト） | Admin でショートフォームの商品に登録した URL が現在のページと一致するとき |
showShortformPreview({ sku }) | 現在の URL に SKU のヒントを加えて関連ショートフォームを検索 | 同じ商品が複数の URL で開くサイト |
showShortformPreview({ tags | brands | skus | shortformCollectionId }) | 指定したフィルター条件で検索（URL は参照しません） | 「セールタグのショートフォームのどれか」のように、ページと無関係に表示したいとき |
<!-- 1. SDK の読み込み -->
<script src="https://static.shoplive.cloud/shoplive-shortform.js"></script>
<script>
// 2. 初期化
cloud.shoplive.initShortform({ accessKey: 'YOUR_ACCESS_KEY' });
// 3. プレビューの呼び出し — このページのアドレスに紐づくショートフォームを表示します
cloud.shoplive.showShortformPreview();
// 同じ商品が複数のアドレスで開く場合は SKU も併せて
// cloud.shoplive.showShortformPreview({ sku: 'PRODUCT_SKU' });
</script>ステップ 3 · 位置とサイズ 任意
このステップも飛ばせます。何も指定しなければ位置もサイズもアカウントのデフォルト値で表示されます。ページのレイアウトと重なる場合やサイズを調整したい場合にだけ、以下のオプションを使ってください。
position のキーと画面上の位置。キーを押してみてください — 上の画面と右側のプレビューで、その位置に移動します。指定しない場合はアカウントのデフォルト値が適用されます。
position と size はオブジェクトを入れ子にして渡します。以下の形をそのまま使えます。
cloud.shoplive.showShortformPreview({
// どの隅に表示するか — 4 つのキーのうち 1 つだけを true に
position: { 'bo-ri': true },
// 画面幅ごとのサイズ — 必要な区分だけ書けば十分です
size: {
desktop: { width: '160px' }, // 広い画面
tablet: { width: '18vw', maxWidth: '150px' }, // タブレット
mobile: { width: '28vw', maxWidth: '140px' } // モバイル
},
resizable: true // 視聴者が隅をドラッグしてサイズを変更できるように
});| フィールド | 入れる値 | 説明 |
|---|---|---|
position | { 'bo-ri': true } | 4 つの隅のうち1 つだけを true に。キーは上の図を参照（to=上 · bo=下 · le=左 · ri=右） |
size.desktop | { width, maxWidth, | 広い画面でのサイズ |
size.tablet | タブレット幅でのサイズ | |
size.mobile | モバイル幅でのサイズ | |
resizable | true | 視聴者が隅をドラッグしてサイズを調整（そのセッション中は維持） |
区分の基準 — どの幅で何が適用されるか
3 つのキーはブラウザーウィンドウの幅（ビューポート幅）で切り替わります。デバイスの種類を判定するのではなく幅だけを見るため、デスクトップでウィンドウを狭めると tablet · mobile の値が適用されます。
| キー | 適用されるウィンドウ幅 | 指定しない場合のサイズ |
|---|---|---|
size.desktop | 1025px 以上 | 幅 17vw（最大 200px） · 高さ 17vw × 15/9（最大 332px） |
size.tablet | 481 〜 1024px | 幅 26vw（最大 200px） · 高さ 26vw × 15/9（最大 332px） |
size.mobile | 480px 以下 | 幅 35vw（最大 200px） · 高さ 35vw × 3/2（最大 332px） |
どの区分でも最小サイズは幅 100px · 高さ 150px に固定されており、それより小さい値を指定しても縮みません。
'160px' · '20vw' のように単位を含む文字列で指定します。区分は必要なものだけ書けばよく、書かなかった区分は上の表のデフォルト値に従います。width だけを変えると縦がずれます
height を併せて指定しないと、高さはデフォルトの計算式のまま使われます。たとえばデスクトップで width: '160px' だけを指定すると、幅は 160px になりますが高さは依然 17vw × 15/9 で計算されるため、ウィンドウが広いほど縦長になります。サイズを調整するときは width と height をセットで指定してください。
// 推奨 — 幅と高さを併せて（ショートフォームは 9:16 の縦型動画）
size: {
desktop: { width: '160px', height: '284px' },
mobile: { width: '28vw', height: 'calc(28vw * 16 / 9)' }
}ステップ 4 · 閉じたあとの扱い
closePolicyExpiry | 視聴者が ✕ で閉じたあと |
|---|---|
| 未指定 | このブラウザーセッションの間は再表示しません |
0 | 未指定と同じ（セッション内は再表示なし） |
N（分） | N 分間は再表示しません。セッションが変わっても維持されます（ブラウザーのストレージに記録） |
iframe 内で開かれている ④ ブラウザーの PiP で再生していた状態から遷移してきたページ ⑤ 条件に合うショートフォームが 0 件 — これらの場合、SDK はプレビューを作成せず、エラーも出しません。開発中に表示されないときは、まずブラウザーの localStorage · sessionStorage を空にして再確認してください。視聴者がプレビューをドラッグしている間は ON_DRAG_START_PREVIEW / ON_DRAG_END_PREVIEW イベントが発生します（イベント処理）。プレビューが下部の購入バーなどを覆うときに一時的に隠す用途に活用できます。
全体のコード
ステップ 2 の最小構成に、位置と閉じたあとの扱いを加えた実践的な構成です。オプションを 1 つも指定しなければ、位置とサイズはアカウントのデフォルト値に従います。
<script src="https://static.shoplive.cloud/shoplive-shortform.js"></script>
<script>
cloud.shoplive.initShortform({ accessKey: 'YOUR_ACCESS_KEY' });
// 商品詳細ページで呼び出す — このページのアドレスに紐づくショートフォームが表示されます
cloud.shoplive.showShortformPreview({
position: { 'bo-ri': true }, // 右下
closePolicyExpiry: 60 // 閉じたら 60 分間は再表示しない
});
</script>SPA のルーティングで商品詳細を離れるときは cloud.shoplive.hideShortformPreview() で片付けてください。
完了の確認
- Admin に登録した商品 URL と同じアドレスのページでプレビューが表示される
- 商品詳細に入ると、指定した隅に小さなプレイヤーがミュートで自動再生される
- プレビューをタップすると全画面プレイヤーが開き、✕ を押すと消える
- 閉じたあとに再読み込みしても、設定どおり再表示されない
前へ ← ミッション 2 · ストーリー — ブランド · タグごとにまとめて見せる次へ → ミッション 4 · ショーケース — 商品ギャラリーの位置に
ミッション 4 · ショーケース — 商品ギャラリーの位置をショートフォームに
プレビューがページの上に浮かぶのに対し、ショーケースはページのレイアウトの中に入ります。既存のギャラリーの位置をそのまま占めるため、商品詳細の第一印象を動画に変える効果があります。
ステップ 1 · 商品詳細に適用する
<!-- 自社ページにすでにある商品画像ギャラリー -->
<div id="product-gallery">
<img src="product-1.jpg" alt="">
<img src="product-2.jpg" alt="">
</div>
<script>
// 現在のページ URL に紐づくショートフォームを取得し、ギャラリーの位置に描画
cloud.shoplive.setShortformShowcase('product-gallery');
</script>引数を省略すると現在のページ URL を基準に関連ショートフォームを探します。Admin でショートフォームに紐づけた商品の URL と現在のページ URL が一致している必要があるため、クエリパラメータが付きやすいページでは、下の url モードで正規化した URL を直接渡してください。
コンテナにはサイズが指定されている必要があります。 ほとんどの商品詳細ではギャラリー領域に幅や比率がすでに設定されているのでそのまま使えます。サイズのない空の div の場合は、width · height または aspect-ratio をページの CSS で指定してください。
ステップ 2 · 商品一覧に適用する — url · shortformId モード
| モード | 呼び出し | カードをタップすると | 活用先 |
|---|---|---|---|
| 現在の URL（デフォルト） | setShortformShowcase(id) | プレイヤー（モーダル）が開きます | 商品詳細 |
| URL を指定 | setShortformShowcase(id, { url }) | その URL へページ遷移 | 商品一覧で商品ごとのタイルにショートフォームを展示 |
| ショートフォーム ID を指定 | setShortformShowcase(id, { shortformId }) | プレイヤー（モーダル）が開きます | 1 ページに異なるショーケースを複数。url と併せて渡すと shortformId が優先されます |
ステップ 3 · 元のギャラリーとの関係
デフォルト（removeOriginalDOM: true）では、SDK は描画に成功したあとにのみコンテナの既存の子要素を削除します。それまでは元のギャラリーがそのまま表示され、取得失敗や設定オフなどで描画しない場合は元の内容に手を触れません。そのため、スケルトンやローディング処理を別途作る必要はありません。元の内容を残したまま重ねて描画したい場合は removeOriginalDOM: false を指定してください。
描画結果は ON_SHORTS_SHOWCASE_RENDERED イベントで通知されます — payload.success が true なら shortsId · shorts が、false なら reason が入ります。成功時にギャラリーのインジケーターを隠すなどの後処理に使ってください。
div:empty { display: none } というルールが SDK の透明なクリック領域を隠し、動画は見えるのにタップできないという問題が起きました。描画はされるのに反応しない場合は、開発者ツールでコンテナ内の .csl- で始まる要素にページの CSS が上書きしていないか確認してください。完了の確認
- 商品詳細に入るとギャラリーの位置にショートフォームカードが描画され、元の画像が消える（設定がオフの商品では元の画像がそのまま表示される）
- カードをタップするとプレイヤーが開く（
urlモードなら該当商品ページへ遷移） - カードが 2 枚以上なら下部にサムネイルストリップが表示され、左右スワイプが動作する
前へ ← ミッション 3 · プレビュー — 画面の隅に浮かせる次へ → ミッション 5 · プレイヤー — コードから直接開く
ミッション 5 · プレイヤー — コードから直接開く
initShortform() 済み · 再生するショートフォームの ID またはフィルター条件ステップ 1 · 開き方を選ぶ
| 区分 | 方法 A · ショートフォーム ID を指定 | 方法 B · フィルター条件を指定 |
|---|---|---|
| 呼び出し | showShortformPlayerModal({ ids: [...] }) | showShortformPlayerModal({ tags: [...] }) など |
| 再生リスト | 渡した ID の順序どおり。startIndex で開始位置を指定。ショートフォームを 1 本だけ開く場合も専用のオプションはなく、ids: ['SHORTFORM_ID'] のように ID を 1 つだけ渡します | 条件に合うショートフォームをサーバーから取得。shortsId で開始するショートフォームを指定 |
| 代表的な用途 | 特定の動画に直接入るバナー · イベントのランディング | 「セールタグの動画をすべて見る」のようなボタン |
<!-- 1. SDK の読み込み -->
<script src="https://static.shoplive.cloud/shoplive-shortform.js"></script>
<script>
// 2. 初期化
cloud.shoplive.initShortform({ accessKey: 'YOUR_ACCESS_KEY' });
</script>
<!-- 3. このボタンを押すとプレイヤーが開きます -->
<button id="open-shortform">おすすめ動画を見る</button>
<script>
document.getElementById('open-shortform').addEventListener('click', function () {
// 方法 A — ショートフォーム ID で直接指定（ID は Admin のショートフォーム詳細で確認）
cloud.shoplive.showShortformPlayerModal({
ids: ['SHORTFORM_ID_1', 'SHORTFORM_ID_2'], // 1 本だけなら ['SHORTFORM_ID']
startIndex: 0, // 2 番目から始めるには 1
muted: true // 初期状態でミュート（ブラウザーの自動再生ポリシー対策に有用）
});
// 方法 B — フィルター条件で一覧を作って再生
// cloud.shoplive.showShortformPlayerModal({
// tags: ['sale'],
// shortsId: 'SHORTFORM_ID_TO_START' // 任意 — 一覧のうちこのショートフォームから
// });
});
</script>ステップ 2 · （任意）再生リストに追加する
方法 A で開いた場合、視聴者が一覧の終わりに近づくと SDK が NEEDS_SHORTFORM_LIST_MORE イベントを送ります。このイベントを受け取り（イベント処理）、次のページの ID を shortformPlayerAppendList に渡すと途切れずに続きます。
<!-- 1. SDK の読み込み -->
<script src="https://static.shoplive.cloud/shoplive-shortform.js"></script>
<script>
// 2. 初期化
cloud.shoplive.initShortform({ accessKey: 'YOUR_ACCESS_KEY' });
// 3. 一覧の終わりに近づくと SDK がこのイベントを送ります
cloud.shoplive.addShortformEventListener(function (name, payload) {
if (name === 'NEEDS_SHORTFORM_LIST_MORE') {
fetchNextPageIds().then(function (ids) { // 自社サーバーから次の ID 一覧を取得
cloud.shoplive.shortformPlayerAppendList({ ids: ids });
});
}
});
</script>ステップ 3 · 閉じるとミュート 任意
プレイヤーは視聴者自身が閉じられ、ミュートも自分で操作できるため、以下の関数は自分のコードから制御する必要があるときだけ使います。たとえば SPA のルーティングでページを離れるときに閉じる、ページ内の別の動画と音が重ならないように合わせる、といった場合です。
<!-- 1. SDK の読み込み -->
<script src="https://static.shoplive.cloud/shoplive-shortform.js"></script>
<script>
// 2. 初期化
cloud.shoplive.initShortform({ accessKey: 'YOUR_ACCESS_KEY' });
</script>
<!-- 3. 自分のページのボタンから制御 -->
<button id="close-shortform">閉じる</button>
<button id="toggle-mute">音を オン / オフ</button>
<script>
// 開いているプレイヤーを閉じる
document.getElementById('close-shortform').addEventListener('click', function () {
cloud.shoplive.dismissShortformPlayerModal();
});
// ミュートの切り替え — 現在の状態を読んで反転します（ページ全体のプレイヤーに共通で適用）
document.getElementById('toggle-mute').addEventListener('click', function () {
var isMuted = cloud.shoplive.getShortformGlobalMuteState(); // true = ミュート中
cloud.shoplive.setShortformGlobalMuteState(!isMuted);
});
</script>setShortformGlobalMuteState を呼び直す必要はありません。完了の確認
- ボタンのクリックなど自分のコードから呼び出すと全画面プレイヤーが開き、指定したショートフォーム（または一覧の先頭）から再生される
- 一覧の終わりで
NEEDS_SHORTFORM_LIST_MOREが届き、追加した ID が続けて再生される dismissShortformPlayerModal()で閉じる
前へ ← ミッション 4 · ショーケース — 商品ギャラリーの位置に次へ → ミッション 6 · ディープリンク — 共有リンクから開く
ミッション 6 · ディープリンク — 共有リンクで特定のショートフォームを開く
ステップ 1 · URL のルール
SDK が読み込まれたページの URL に以下のパラメータがあると、ページが開いた直後にそのショートフォームのプレイヤーが自動的に開きます。広告のランディング · プッシュ · SNS の共有リンクにそのまま使えます。
https://my-shop.com/shorts?__sl_shorts_id=SHORTFORM_ID| パラメータ | 必須 | 説明 |
|---|---|---|
__sl_shorts_id | 必須 | 開くショートフォームの ID |
__sl_cq | 任意 | 再生リストを作るフィルター条件（JSON、URL エンコード）。例: {"tags":["sale"]}。指定しない場合は該当ショートフォームを基準に一覧を構成します |
ステップ 2 · SDK が URL に手を加える仕組み
どの経路であれプレイヤーが開くと、SDK は現在の URL に ?__sl_shorts_id=… を追加し（pushState）、閉じると元に戻します。これにより —
- 再生中にアドレスバーの URL をコピーして送ると、受け取った人も同じショートフォームが開いた状態でページが表示されます。
- モバイルで戻るを押すと、ページを離れずにプレイヤーだけが閉じます。
- プレイヤーの共有ボタンが生成する URL（イベント処理の
ON_CLICK_SHARE_BUTTONのpayload.url）もこのルールに従います。
ステップ 3 · 独自ルーターを持つ SPA の場合
disableQueryParamHistory: true を表示関数ごとに
React Router · Vue Router などが URL の変化を監視しているページでは、SDK の pushState がルーターを刺激し、画面が切り替わったりプレイヤーが閉じたりすることがあります。その場合はプレイヤーを開きうるすべての呼び出し — setShortformCollection · showShortformPreview · showShortformPlayerModal — に disableQueryParamHistory: true を指定して URL 履歴を無効にしてください。このときステップ 1 のディープリンクの自動オープンも併せて無効になるため、ディープリンクが必要な場合はページ表示時にルーターのクエリを読み取り、showShortformPlayerModal({ ids: [id] }) を直接呼び出します。完了の確認
?__sl_shorts_id=…を付けた URL を新しいタブに貼り付けると、該当のショートフォームが自動的に開く- プレイヤーが開いた状態でアドレスバーの URL が変わり、戻るでプレイヤーだけが閉じる
- （SPA）
disableQueryParamHistoryを有効にした場合、URL が変わらずルーターが反応しない
ミッション 7 · ユーザー情報の連携
initShortform() 済み · （JWT 認証の場合）バックエンドの署名処理（ステップ 5）ユーザー情報を連携しない場合、視聴者はゲストとして扱われます。ゲストでも視聴や商品クリックはできますが、コメントのようにアカウントが必要な機能を押すと LOGIN_REQUIRED イベントが発生します（イベント処理で処理）。ユーザー情報の関数はライブ SDK と共有します（ステップ 2）。
setUserObject()・setUserJWT() はユーザー情報を渡すもので、ユーザーを認証するものではありません ログイン（ID・パスワード、ソーシャルログインなど）はすべて自社サイト側で行います。これらの関数はいまの視聴者が誰かを Shoplive に伝えるだけで、コメント・いいね・ブックマークと視聴の統計がその会員に紐づきます。Shoplive はユーザーの資格情報を確認しません。JWT 認証では、その情報が自社サーバーが発行し改ざんされていないか（署名）を Shoplive が確認でき、簡易認証（userObject）ではその確認なしに情報をそのまま渡します。ステップ 1 · ログイン状態で選ぶ — 推奨の設定
| ユーザー | 推奨 | 理由 |
|---|---|---|
| 未ログイン | 何も呼び出さない（ゲスト） | SDK が匿名の識別子を自動発行してブラウザーに保存するため、視聴の統計はそのまま集計されます。コメントのようにアカウントが必要な機能を押すと LOGIN_REQUIRED イベントが発生します |
| ログイン （推奨） | setUserJWT() — サーバーが署名した JWT（JWT 認証） | 自社サーバーで署名するため、クライアントで偽造できません |
| ログイン（バックエンド作業が難しい場合） | setUserObject() — userId・名前などを直接渡す（簡易認証） | クライアントの値を署名なしでそのまま渡します。識別・統計には十分ですが、権限の検証には使わないでください |
| ログイン（Cafe24 · WISA · ゴドモール · Shopify のショップ） | プラットフォーム自動連携 | ショップがすでに持っているログイン状態を SDK が読み取ります。上の 2 つとはどちらか一方で、ユーザー情報を直接渡した場合はその値が優先されます |
| ログアウト・ユーザー情報のリセット | cloud.shoplive.logout() · または setUserObject(null) / setUserJWT(null) | 設定したユーザー情報を消去し、ゲスト状態に戻ります |
setUserJWT() を呼ぶ直前ごとに）バックエンドから新しく発行した JWT を受け取り initShortform({ userJWT }) または setUserJWT() → ログアウト時に logout()（または null を渡す）でユーザー情報をリセット。
未ログインのまま見せ、ゲストがコメントなどを押したときに LOGIN_REQUIRED でログインを促す使い方もできます（ミッション 8）。ステップ 2 · 選んだ方式で呼び出す
初期化の時点でログイン状態がすでに分かっている場合は initShortform() に含め、ログインが後から確定する場合（SPA など）は setUserObject() / setUserJWT() を別途呼び出します。ログアウト時のユーザー情報のリセットは logout() または setUserObject(null) · setUserJWT(null) です。ここで使う関数と値はライブ SDK と完全に同じです — ライブをすでに連携済みなら、そのときのコードをそのまま移せます。
<!-- 1. SDK の読み込み -->
<script src="https://static.shoplive.cloud/shoplive-shortform.js"></script>
<script>
// 2. ログインユーザーの情報 — 簡易認証では userId のみ必須
var userObject = {
userId: 'MEMBER_ID', // 必須 — ログインユーザーの一意な ID（ステップ 4 のハッシュ化を推奨）。空ならゲスト
userName: 'NICKNAME' // 任意 — コメントやプロフィールに表示される名前
};
// 3. 方法 1 — 初期化時点でログイン状態が分かっているなら initShortform() にそのまま含める
cloud.shoplive.initShortform({
accessKey: 'YOUR_ACCESS_KEY',
userObject: userObject
// JWT 認証なら userObject の代わりに: userJWT: 'USER_JWT' （ステップ 5 で発行）
});
</script>
<script>
// 3. 方法 2 — ログインが後から確定する場合（SPA など）は初期化後に別途呼び出す
// 上の initShortform() では accessKey だけを渡し、ログイン完了時に呼びます
// cloud.shoplive.setUserObject(userObject);
// cloud.shoplive.setUserJWT('USER_JWT'); // JWT 認証
// 4. ログアウト・ユーザー情報のリセット — 設定したユーザー情報を消去し、ゲスト状態に戻ります
// cloud.shoplive.logout();
// または渡した値を null に: cloud.shoplive.setUserObject(null) / cloud.shoplive.setUserJWT(null)
</script>ライブ SDK と同じ関数を共有します。 1 つのページにライブプラグイン（shoplive.js）も読み込んでいる場合、setUserObject · setUserJWT · logout は両 SDK が同じ値を参照します。どちら側から呼び出しても両方に反映され、最後に呼び出した値が残ります。2 回呼び出す必要はなく、ログイン · ログアウトのタイミングで 1 回だけ呼んでください。
initShortform({ guestUid }) で自社が管理する匿名 ID を直接渡して一貫性を保てます。ステップ 3 · ショップ構築プラットフォームを使っている場合 — 自動連携 任意
Cafe24 · WISA · ゴドモール · Shopify で構築したショップなら、setUserObject() を直接呼ぶ代わりに initShortform() に platform だけを渡し、ショップのログイン状態を読み取らせることができます。ステップ 2 の代替であり、ステップ 2 に追加する作業ではありません。
userObject · userJWT がないときにだけプラットフォーム自動連携を試みます。initShortform() にユーザー情報を併せて渡した場合はその値が使われ、platform は無視されます。どちらか一方だけを使ってください。platform の値 | どのように読み取るか | ページに用意するもの |
|---|---|---|
'CAFE24' | Cafe24 スキンのログイン状態モジュールが描画する会員情報を読み取ります。値が遅れて入るスキンでは、入るまで待ってから連携します | スキンにログイン状態モジュールがなければ、下の A を追加します |
'WISA' · 'GODOMALL' | ページ上の取り決められた id の要素から会員情報を読み取ります | 下の B の 2 つの要素を自分で出力する必要があります |
'SHOPIFY' | 上と同じ方法で読み取り、さらにプレイヤー内のカート機能が有効になります | B + shopify 設定（付録 C） |
いずれの場合も共通レイアウト（すべてのページが共有するヘッダー領域）に入れ、どのページから入ってもログイン状態を取得できるようにするのが安全です。
<!-- 1. SDK の読み込み -->
<script src="https://static.shoplive.cloud/shoplive-shortform.js"></script>
<!-- A. Cafe24 — スキンにログイン状態モジュールがない場合のみ追加します。
{$id} {$name} は Cafe24 がログイン会員の ID · 名前に置き換えます -->
<div module="Layout_stateLogon" style="display:none;">{$id} {$name}</div>
<!-- B. WISA · ゴドモール · Shopify — 会員情報をこの id で出力します。
波かっこの中は、各ショップソリューションが提供する会員変数に置き換えてください
· ゴドモール : {=gSess.memId} / {=gSess.memNm}
· WISA : {{$회원아이디}} / {{$회원명}}
未ログイン時は値が空になるため、ゲストとして動作します -->
<div style="display:none;">
<span id="cloud-shoplive-user-id">MEMBER_ID</span>
<span id="cloud-shoplive-user-name">NICKNAME</span>
</div>
<script>
// 2. platform だけを渡します — setUserObject は呼び出しません
cloud.shoplive.initShortform({
accessKey: 'YOUR_ACCESS_KEY',
platform: 'CAFE24' // 'CAFE24' | 'WISA' | 'GODOMALL' | 'SHOPIFY'
});
</script>visibility: hidden で隠すと値が空になります
会員情報の要素を画面に見せないようにする際、display: none や画面外へ追い出す方法では値の読み取りに問題はありませんが、visibility: hidden は空文字列として読まれ、ゲストになってしまいます。また Cafe24 以外は初期化時に 1 回だけ読み取るため、会員情報をスクリプトで後から埋める場合は initShortform() をそのあとに呼び出してください。連携できたかの確認方法。 ログイン状態でプレイヤーを開き、コメントに表示される名前を見てください。Cafe24 で会員情報の領域が見つからない場合はコンソールに Failed - Get Cafe24 account が出力され、その他のプラットフォームでは要素がないと静かにゲストのままになります。自動連携が難しい場合は、ステップ 2 のように setUserObject() を直接呼び出せば大丈夫です。
ステップ 4 · ID のハッシュ化 — 会員 ID の原文を渡さない
内部の会員 ID を原文のまま渡したくない場合は、自社サーバーでハッシュ化した値を userId として使ってください。Shoplive は元の ID を知ることができませんが、自社側では同じアルゴリズム · ソルトで再計算して元のユーザーと対応づけられます。同じユーザーからは常に同じ値が出るよう（再訪の識別 · 統計のため）、一貫した方法で処理してください。ライブ SDK と併用する場合は、両 SDK に同じハッシュ値を渡さないと 1 人のユーザーとして集計されません。
// Node.js — 自社サーバーでハッシュ化します（salt・アルゴリズムは常に同じに）
const crypto = require('crypto');
function hashUserId(raw) {
return crypto.createHash('sha256')
.update(raw + 'YOUR_SALT')
.digest('hex');
}
const userId = hashUserId('MEMBER_ID'); // userObject.userId または JWT の userId に使いますsetUserJWT()）を使用してください。salt のポリシーは Shoplive チームと合意した値を推奨します。ステップ 5 · JWT 認証用のトークンを作る（自社バックエンド）
JWT 認証に使う JWT は、Shoplive が発行した Secret Key で自社のバックエンドが署名します。ページはバックエンドから受け取った JWT を initShortform({ userJWT }) または setUserJWT() に渡すだけです。
- Shoplive の担当者から Secret Key を受け取ります — base64 でエンコードされた文字列です
- ログインしたユーザー情報で下記の payload を作り、HS256 で署名します
- ページから要求されるたびに（
setUserJWT()を呼ぶ直前ごとに）JWT を新しく発行して返します。ブラウザーに JWT を保存して使い回さないでください
exp まで使えてしまいます。ページを開くたびに、または setUserJWT() を呼ぶたびに、バックエンドから新しい JWT を受け取るようにしてください。exp は必須です
簡易認証の userObject にはないフィールドです。JWT ライブラリが提供する期限設定 API（下の例の setExpiration・expiresIn）で指定してください — ライブラリが exp を埋めてくれます。表示名は name・userName のどちらでもよく、両方ある場合は userName が優先されます。| claim | 必須 | 説明 | 例 |
|---|---|---|---|
exp | 必須 | 有効期限（Unix 秒）。ライブラリの期限設定で埋めます | 1516239022 |
userId | 必須 | ログインユーザーの一意な ID。ハッシュ値でも構いません（ステップ 4）。ない場合はコンソールに Invalid JWT - Empty userId が出力され、トークンは無視されます | MEMBER_ID |
iat | 任意 | 発行時刻（Unix 秒） | 1516195822 |
name または userName | 任意 | コメント・プロフィールに表示される名前。両方ある場合は userName が優先。禁止語は * に置き換えて表示 | NICKNAME |
gender | 任意 | 性別 — m · f · 空（未指定） | f |
age | 任意 | 年齢。統計では 5 歳単位でまとめて表示されます | 27 |
userScore | 任意 | ユーザーランク（-100〜100）。抽選対象の制限などの基準 | 10 |
userType | 任意 | 入場制限（Entry Type）設定時に参照される値 | VIP |
profile | 任意 | チャット一覧のプロフィール画像 URL、推奨 64x64px | https://…/profile.png |
custom | 任意 | 自由形式のデータ、最大 1KB | {"grade":"vip"} |
ショートフォーム SDK がトークンから直接読み取るのは userId・表示名・exp です。 そのほかのクレームはライブ SDK と同じ JWT の仕組みに従います。1 つのページでライブプレイヤーも使う場合、setUserJWT() で渡した 1 つのトークンを両 SDK が共有するため、ライブで使うクレーム（userScore・userType など）も同じトークンに入れてください。
署名する
署名の例です。2 つのコードは同じトークンを作ります — Secret Key が base64 文字列のため、ライブラリによってそのまま渡すかデコードして渡すかが異なる点だけ注意してください。
// Java — jjwt。signWith が base64 文字列を自動でデコードします
import io.jsonwebtoken.Jwts;
import io.jsonwebtoken.SignatureAlgorithm;
import java.util.Date;
String base64EncodedSecretKey = "YOUR_BASE64_SECRET_KEY"; // Shoplive 担当者から受け取った値
long expiration = System.currentTimeMillis() + 12 * 60 * 60 * 1000L; // 12 時間
String jwt = Jwts.builder()
.signWith(SignatureAlgorithm.HS256, base64EncodedSecretKey)
.setExpiration(new Date(expiration))
.setIssuedAt(new Date())
.claim("userId", "MEMBER_ID") // 必須
.claim("name", "NICKNAME") // 任意 — 表示名
.claim("userScore", 10) // 任意
.claim("userType", "VIP") // 任意
.compact();// Node.js — jsonwebtoken。secretKey を自分でデコードして渡す必要があります
const jwt = require('jsonwebtoken');
const base64EncodedSecretKey = 'YOUR_BASE64_SECRET_KEY'; // Shoplive 担当者から受け取った値
const secret = Buffer.from(base64EncodedSecretKey, 'base64'); // ← デコードが必要
const token = jwt.sign(
{
userId: 'MEMBER_ID', // 必須
name: 'NICKNAME', // 任意 — 表示名
userScore: 10, // 任意
userType: 'VIP' // 任意
},
secret,
{ algorithm: 'HS256', expiresIn: '12h' }
);userId で他のユーザーになりすましたトークンを作れてしまいます。ブラウザーにバンドルされるコードや公開リポジトリには置かず、必ず自社サーバーでのみ署名し、完成したトークンだけをフロントへ渡してください。簡易認証（setUserObject()）は署名がないため、権限の検証には使えません。完了の確認
- ログイン後にプレイヤーでコメントを書くと、指定した名前で表示される
- ゲスト状態でコメント入力を試みると
LOGIN_REQUIREDイベントが発生する（デフォルトの動作は案内のalert） logout()（またはnullを渡す）でユーザー情報をリセットすると、再びゲストとして動作する
前へ ← ミッション 6 · ディープリンク — 共有リンクから開く次へ → ミッション 8 · イベント · 商品クリック · データ収集
ミッション 8 · イベント · 商品クリック · データ収集
initShortform() 済み · 商品クリックを扱う場合は Admin でショートフォームに商品を紐づけ済みショートフォーム SDK のイベント処理は目的の異なる 2 つのチャネルに分かれています。何をしたいかに応じて、一方または両方を使います。
ステップ 1 · どちらのチャネルを使うか選ぶ
| 区分 | messageCallback — 動作を変える | addShortformEventListener — 観測する |
|---|---|---|
| 登録場所 | initShortform({ messageCallback: { イベント名: fn } }) | cloud.shoplive.addShortformEventListener(fn)（複数登録可） |
| 関数の形 | (payload) => void — イベントごとに 1 つの関数 | (eventName, payload) => void — すべてのイベントを 1 つの関数で |
| デフォルト動作 | 自分の関数がデフォルト動作を置き換えます。例: 商品クリック時に SDK のページ遷移ではなく自分のコードを実行 | デフォルト動作はそのまま実行され、通知だけを受け取ります |
| 代表的な用途 | ログインページへの誘導 · 商品クリックを SPA ルーターで処理 · 共有 UI のカスタマイズ | GA · Amplitude などへの送信 · 視聴時間の集計 |
ステップ 2 · デフォルト動作を変える — messageCallback
以下の 7 つのイベントには SDK のデフォルト動作があります。変えたいものだけ登録してください — 登録しなかったイベントはデフォルト動作がそのまま実行されます。
| イベント | タイミング | デフォルト動作 | payload の主なフィールド |
|---|---|---|---|
PLAY_SHORTFORM_DETAIL | ショートフォームを押して再生が始まる瞬間 | 全画面のプレイヤーモーダルを開きます | shorts · shortsId · muted · shortsCollection |
PLAY_SHORTFORM_DETAIL — モーダルではなく自社のページへ遷移させるなど、入口そのものを変えるときに使います。ショートフォーム ID はディープリンクからの流入なら shortsId、それ以外は shorts.shortsId に入るため、payload.shorts?.shortsId || payload.shortsId として読んでください。このイベントだけはリスナー（ステップ 3）には配信されないため、再生開始を観測するだけなら DETAIL_ON_PLAYER_SHOW を使ってください。 | |||
CLOSE_SHORTFORM_DETAIL | プレイヤーを閉じるとき — 閉じる（✕）ボタン · 下方向のスワイプ · ブラウザーの戻る | プレイヤーを閉じ、開くときに追加した URL クエリを元に戻します | triggeredBrowserBack |
CLOSE_SHORTFORM_DETAIL — プレイヤーを離れるときに自分の画面を戻す（SPA のルーティング）、閉じた回数を集計する、といった用途に使います。ブラウザーの戻るで閉じた場合にのみ payload.triggeredBrowserBack が true になり、このときはすでに履歴が移動したあとなので SDK も history.back() を呼びません。閉じたことを観測するだけなら DETAIL_ON_PLAYER_DISMISS を使ってください。 | |||
LOGIN_REQUIRED | ゲストがコメントなどログインの必要な機能を押したとき | 案内の alert | type（例: 'comment'） |
ON_CLICK_PRODUCT_ITEM | プレイヤーの商品カード · 商品一覧の項目をクリックしたとき | location.href = payload.product.url | product（商品） · shorts（ショートフォーム） |
ON_CLICK_PRODUCT_BANNER | 商品バナーをクリックしたとき | location.href = payload.scheme | scheme |
ON_CLICK_LINK_BUTTON | リンクボタンをクリックしたとき | location.href = payload.scheme | scheme |
ON_CLICK_SHARE_BUTTON | 共有ボタンをクリックしたとき | OS の共有シート（navigator.share）、なければ URL をクリップボードにコピー | url · shorts |
ON_CLICK_PRODUCT_ITEM の payload.product.url と、ON_CLICK_PRODUCT_BANNER · ON_CLICK_LINK_BUTTON の payload.scheme の末尾に csl_bp=1 が自動で付きます。次のページでも PIP を続けるための目印です。
この URL を自社のロジックで加工する場合は、見慣れないパラメータが混ざって来ることがある点にご注意ください — 削除すると遷移先で PIP が途切れます。今のページのアドレスに
csl_bp がある場合にだけ付くので、通常は元の URL のままです。cloud.shoplive.initShortform({
accessKey: 'YOUR_ACCESS_KEY',
messageCallback: {
// ゲストがログインの必要な機能を押したとき → 自社のログインページへ
LOGIN_REQUIRED: function (payload) {
location.href = '/login?returnTo=' + encodeURIComponent(location.href);
},
// 商品クリック → 新しいタブではなく SPA ルーターで遷移（デフォルトの location.href を置き換え）
ON_CLICK_PRODUCT_ITEM: function (payload) {
var product = payload.product; // productId, name, url, sku, discountPrice …
myRouter.push('/products/' + product.sku);
cloud.shoplive.dismissShortformPlayerModal();
},
// 共有 → 自社の共有 UI を使う
ON_CLICK_SHARE_BUTTON: function (payload) {
openMyShareSheet({ title: payload.shorts.shortsDetail.title, url: payload.url });
}
}
});この 7 つ以外のイベントを扱いたい場合。 上の表はSDK にデフォルト動作があり、置き換えられるイベントで、ショートフォームが送るイベントはこれよりはるかに多くあります。いいね · ブックマーク · コメント · タグのクリックのようにデフォルト動作がないイベントは置き換えるものがないため、ステップ 3 のリスナーで観測します。どのイベントが届くかはリファレンス · イベント辞典で全一覧をご確認ください。
ステップ 3 · 観測する — addShortformEventListener
登録した関数はイベント辞典のトラッキング · 通知イベントをすべて受け取ります。イベント名で分岐し、必要なものだけアナリティクスに送ってください。名前は 領域_動作 の規則なので、接頭辞でまとめて扱いやすくなっています。
cloud.shoplive.addShortformEventListener(function (eventName, payload) {
switch (eventName) {
case 'COLLECTION_CLICK_ITEM': // 一覧でカードをクリック
case 'DETAIL_CLICK_PRODUCT_CARD': // プレイヤーで商品カードをクリック
case 'DETAIL_CLICK_LIKE':
case 'DETAIL_CLICK_SHARE':
analytics.track('shoplive_' + eventName.toLowerCase(), payload);
break;
case 'VIDEO_TOTAL_VIEWING_TIME': // ショートフォーム 1 本を離れるときの累積視聴時間
analytics.track('shortform_watch', {
shortsId: payload.shortsId,
seconds: payload.totalViewingTime,
duration: payload.videoDuration
});
break;
}
});ステップ 4 · 視聴時間とセッション
| 手段 | 説明 |
|---|---|
VIDEO_TOTAL_VIEWING_TIME イベント | 視聴者がショートフォーム 1 本を離れるとき（次に送る、または閉じるとき）に累積視聴時間を通知 — shortsId · totalViewingTime（秒） · videoDuration · videoDurationText |
getShortformTotalViewingTime() | 現在再生中のショートフォームの累積視聴時間を即座に読み取ります（同じフィールド） |
setShortformSessionId(id) | 自社のセッション ID を視聴ログに併せて残し、自社の分析データと突き合わせます |
shoplive.js）の sendConversionEvent が担当します。組み込み方はミッション 9 · 購入コンバージョン計測に続きます。完了の確認
- 登録した
messageCallbackのイベントで、デフォルト動作ではなく自分の関数が実行される（例: 商品クリック時にページが再読み込みされずルーターで遷移する） - 登録しなかったイベント（例: 共有）はデフォルト動作がそのまま動く
- リスナーに
COLLECTION_CLICK_ITEM→DETAIL_ON_PLAYER_SHOW→VIDEO_TOTAL_VIEWING_TIMEの順でイベントが届く
前へ ← ミッション 7 · ユーザー情報の連携次へ → ミッション 9 · 購入コンバージョン計測
ミッション 9 · 購入コンバージョン計測 — 視聴が購入につながったか
userId視聴者が商品を押して商品ページへ移動した時点で、ショートフォーム SDK の追跡は終わります。そのあと決済が成立したかどうかは自社のページでしか分からないため、購入完了の時点で 1 回だけ知らせることで「このショートフォームがどれだけ売上を生んだか」が集計されます。
sendConversionEvent() は、ショートフォームのバンドルではなくライブプラグイン shoplive.js に含まれています。購入完了ページでショートフォームを表示することはないため shoplive-shortform.js は不要で、この 1 行だけで済みます。Access Key はショートフォームと同じキーです。ステップ 1 · どこに入れるか
注文が確定したあとに1 回だけ開くページ — 通常は注文完了 · 決済完了ページです。カートや決済の進行画面に入れると離脱した注文まで購入として集計され、再読み込みで何度も開くページに入れると同じ注文が重複して報告されます。
ステップ 2 · 購入完了を報告する
SDK の読み込み → 初期化 → ユーザー情報 → 報告 の順です。初期化が終わる前に sendConversionEvent() を呼び出しても SDK が待機させてから実行するため、順序が原因で失敗することはありません。
<!-- 1. ライブプラグインの読み込み — ショートフォームのバンドル（shoplive-shortform.js）ではありません -->
<script src="https://static.shoplive.cloud/shoplive.js"></script>
<script>
// 2. 初期化 — ショートフォームと同じ Access Key
cloud.shoplive.initPlugin({ accessKey: 'YOUR_ACCESS_KEY' });
// 3. ログインユーザーなら、視聴時と「同じ」 userId を渡します（ステップ 3 参照）
cloud.shoplive.setUserObject({ userId: 'MEMBER_ID' });
// 4. 購入完了の報告
cloud.shoplive.sendConversionEvent({
accessKey: 'YOUR_ACCESS_KEY', // 必須
eventType: 'purchase', // 必須
orderId: 'UNIQUE_ORDER_ID', // 注文番号 — 重複報告を判別するのに使われます
products: [
{ sku: 'PRODUCT_SKU_1', purchaseUnitPrice: 10000, purchaseQuantity: 1 },
{ sku: 'PRODUCT_SKU_2', purchaseUnitPrice: 15000, purchaseQuantity: 2 }
]
});
</script>| フィールド | 必須 | 説明 |
|---|---|---|
accessKey | 必須 | ショートフォームと同じキー。初期化で渡していても、このオブジェクトにもう一度入れる必要があります — ない場合はコンソールに Invalid request が出るだけで送信されません |
eventType | 必須 | 購入完了は 'purchase'。カート投入の時点を別途報告する 'cartIn' という値もありますが、集計にどう反映されるかは Shoplive 担当者にご確認ください |
orderId | 任意 | 自社の注文番号 |
products | 任意 | 購入した商品の配列。公式ガイドの例では sku · purchaseUnitPrice · purchaseQuantity を使用します。このほか productId · customerProductId · currency も併せて送れます |
timestamp | 任意 | 購入時刻。指定しない場合は呼び出し時刻が使われます |
custom | 任意 | 併せて残したい任意の値 |
以前の資料で init() を見かけた場合。 初期化を cloud.shoplive.init() と記載した例が残っています。この関数は initPlugin() の旧名（非推奨）で動作は同じですので、新規に書く場合は initPlugin() を使ってください。
ステップ 3 · 視聴履歴とつながる条件
報告した購入は視聴履歴と同一人物と認識されて初めてコンバージョンとして集計されます。条件はログインの有無で 2 つに分かれます。
| 区分 | つながる条件 | 合わせるべきこと |
|---|---|---|
| ログインユーザー | userId | ショートフォームを見るときにミッション 7 · ユーザー情報の連携で渡した値と完全に同じ値を購入完了ページでも渡します。ハッシュ化している場合は同じハッシュ値である必要があります |
| 未ログイン（ゲスト） | ブラウザーに保存された匿名の識別子 | 呼び出すものはありませんが、同じブラウザー · 同じドメインである必要があります（下の注意を参照） |
localStorage に保存され、localStorage はドメインごとに分離されます。ショートフォームを表示したページと購入完了ページのドメインが異なる場合（例: www.shop.com で見て order.shop.com で決済）、同一人物としてつながりません。ドメインを揃えるのが難しい場合は、ログインユーザー基準（userId）で集計するのが確実です。完了の確認
- 購入完了ページで、ネットワークタブに
/conversion/eventリクエストが 1 回記録される - 再読み込みや戻るで同じ注文が何度も報告されない
- （ログイン時）リクエスト送信時の
userIdが、ショートフォーム視聴時に渡した値と同じである - 集計結果は Shoplive Admin のコンバージョンレポートで確認します — 反映に時間がかかることがあるため、数値がすぐに見えない場合は担当者にお問い合わせください
前へ ← ミッション 8 · イベント · 商品クリック · データ収集次へ → 全体のサンプル
全体のサンプル — コレクション · プレイヤーを開く · ユーザー情報 · イベントを 1 ページに
ショートフォームのタブページ 1 枚に、一覧 · ボタンからの起動 · ユーザー認証 · イベント処理をすべて適用した形です。そのままコピーして YOUR_* の値だけ変えれば動作します。商品詳細ページなら、ここにプレビューまたはショーケースの呼び出しを 1 行加えてください。
<!doctype html>
<html>
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, viewport-fit=cover">
<!-- 1. SDK の読み込み — cloud.shoplive を使うコードより前に -->
<script src="https://static.shoplive.cloud/shoplive-shortform.js"></script>
<script>
// 2. 初期化 + デフォルト動作の上書き（イベント処理）
cloud.shoplive.initShortform({
accessKey: 'YOUR_ACCESS_KEY',
messageCallback: {
LOGIN_REQUIRED: function () {
location.href = '/login?returnTo=' + encodeURIComponent(location.href);
},
ON_CLICK_PRODUCT_ITEM: function (payload) {
location.href = payload.product.url; // デフォルトと同じ動作ですが、ここで UTM 付与などの加工ができます
}
}
});
// 3. ログインユーザーなら連携（ユーザー情報） — ゲストなら省略
var loginUserId = 'YOUR_HASHED_USER_ID';
if (loginUserId) {
cloud.shoplive.setUserObject({ userId: loginUserId, userName: 'YOUR_USER_NAME' });
}
// 4. アナリティクスへの送信（イベント処理）
cloud.shoplive.addShortformEventListener(function (eventName, payload) {
if (eventName === 'COLLECTION_CLICK_ITEM' || eventName === 'VIDEO_TOTAL_VIEWING_TIME') {
console.log('[shoplive]', eventName, payload); // → analytics.track(...)
}
});
</script>
</head>
<body>
<header>自社サイトのヘッダー</header>
<!-- 5. 一覧の表示（コレクション） -->
<div id="shoplive-shortform-area"></div>
<script>
cloud.shoplive.setShortformCollection('shoplive-shortform-area', {
template: 'GRID2',
hasMoreButton: false // 無限スクロール
});
</script>
<!-- 6. 特定のショートフォームを直接開く（プレイヤーを開く） -->
<button onclick="cloud.shoplive.showShortformPlayerModal({ ids: ['YOUR_SHORTFORM_ID'] })">
今週のおすすめ動画を見る
</button>
</body>
</html>前へ ← ミッション 9 · 購入コンバージョン計測次へ → 付録
付録 · 特定の状況でのみ
上記のミッションには含まれない、特定の状況でのみ必要になる機能です。
A. インラインプレイヤービュー — モーダルではなく自分の領域に
プレイヤーを全画面モーダルではなくページ内の特定の div に描画したい場合（例: デスクトップで左に一覧 · 右にプレイヤーというレイアウト）に使います。一度呼び出すと、以降のコレクションのクリックもモーダルではなくこの領域で再生されます。
// コンテナには width · height が必要です（ない場合 SDK が 100% で埋めます）
cloud.shoplive.setShortformPlayerView('my-player-area', { tags: ['sale'], muted: true });
// 同じ領域の内容だけを差し替える
cloud.shoplive.replaceShortformPlayerView({ ids: ['SHORTFORM_ID'] });
// 削除 — 使用していたコンテナ id を返します
var containerId = cloud.shoplive.destroyShortformPlayerViewAndGetContainerId();setShortformPlayerView は他の表示関数と違い、コンテナの存在を先に確認します。<head> で呼び出すとコンテナが見つからず静かに終了するため、コンテナの div より後に置くか、DOMContentLoaded のあとに呼び出してください。B. カスタムショートフォーム — 自社データでプレイヤーを構成する
Shoplive のショートフォーム ID に、自社が持つメタデータ（タイトル · クリエイター · いいね数 · 外部商品など）を重ねて再生します。独自のコミュニティやクリエイターの仕組みを持つ企業がインラインプレイヤービュー（A）と併せて使う高度な機能のため、導入前に Shoplive 担当者にご相談ください。
| 関数 | 説明 |
|---|---|
appendCustomShortforms({ customShortforms: [...] }) | 一覧が空なら新規作成し、あれば追加します |
setCustomShortform(customShortform) | 特定の shortsId のデータを更新します（いいねの切り替えなど） |
removeShortform({ shortsIds: [...] }) | 一覧から削除します |
オブジェクトのフィールドはフィールド辞典 · カスタムショートフォームオブジェクトをご覧ください。extra に入れた値はイベントの payload にそのまま返ってくるため、自社の識別子を載せて渡せます。
C. Shopify — プレイヤー内でカートに追加する
Shopify ストアでは platform: 'SHOPIFY' と shopify オプションを指定すると、商品カードのクリック時にページ遷移せずプレイヤー内でのバリエーション選択 → 数量 → カート追加まで処理されます。
cloud.shoplive.initShortform({
accessKey: 'YOUR_ACCESS_KEY',
platform: 'SHOPIFY',
shopify: {
cartLink: '/cart', // カートへのリンク
customUISections: ['shopify-section-cart-drawer'] // 追加後に再描画するテーマセクション id（任意）
}
});shopify のフィールド | 説明 |
|---|---|
cartLink | カートへ移動するリンク。指定しない場合はテーマのデフォルトのカート動作に従います |
customUISections | 追加成功後に再描画するテーマセクション id の配列。指定しない場合は cart-drawer · cart-icon-bubble · cart-notification · cart-drawer-items · cart-drawer-footer を更新します。テーマが別の名前を使っている場合はその id を入れてください — <section id="shopify-section-custom-bubble"> なら 'custom-bubble' のように shopify-section- の接頭辞を除いた値です |
tax | バリエーション選択 UI の価格に消費税を加えて表示します — { displayTaxIncluded: true, taxRate: 0.1 }（10%）。両方の値がそろって初めて適用され、taxRate が 0 の場合は無視されます |
// 税込価格で表示する必要があるストアの場合
cloud.shoplive.initShortform({
accessKey: 'YOUR_ACCESS_KEY',
platform: 'SHOPIFY',
shopify: {
tax: {
displayTaxIncluded: true, // 価格に消費税を加えて表示
taxRate: 0.1 // 消費税率 10%
}
}
});税を加えたあとの切り捨てルール。 小数を使わない通貨（KRW · JPY · THB · IDR · INR · CLP · MMK · VND · PKR）は整数に切り捨て、それ以外の通貨は小数点以下 2 桁まで残して切り捨てます。この値は表示専用であり、実際の決済金額は Shopify が計算します。
Shopify はコードを入れる場所がテーマファイルのため、手順が少し異なります。以下の順に進めてください。
Layout → theme.liquid に SDK の読み込みと initShortform() を入れます。すべてのページで 1 回だけ実行されるよう、テーマのレイアウトに置くことが重要です。
</>）に切り替え、コンテナの <div> とコレクションの呼び出しを入れます。テーマですでに初期化しているので、ここでは表示関数を呼ぶだけで済みます。D. SPA で使う
initShortform({ isSPA: true })— クライアントルーティングでページが変わっても SDK を維持します。initShortformは 1 ページのライフサイクルで1 回だけ動作し、2 回目以降は無視されます。- コンポーネントが破棄されるときは
destroyShortformCollection(id)/hideShortformPreview()を呼んで後片付けしてください。コンテナの DOM を削除しただけでは、SDK 内部にインスタンスが残ります。 - ルーターが URL の変化を監視している場合は、表示関数ごとに
disableQueryParamHistory: trueを指定してください（ディープリンク）。
E. ライブ SDK と同じページで使う
両方のスクリプトを読み込み、initPlugin · initShortform をそれぞれ呼び出します。読み込み順は問いません — あとから読み込まれた側が、既存の cloud.shoplive オブジェクトに自分の関数を追加します。setUserObject · setUserJWT · logout は共有の関数なので、1 回呼び出せば両 SDK に反映されます。ライブのミニプレビューとショートフォームのプレビューが同じ隅で重ならないよう、SDK が位置を調整します。
F. RequireJS / AMD 環境
ページを RequireJS でモジュール管理している場合は、initShortform({ useAMD: true, AMDLoader: require }) のようにローダーを渡し、SDK がそのローダーで内部モジュールを読み込むようにします。通常の <script> 読み込みの環境では不要です。
G. 自社アプリの WebView 内で表示する — 動画を再生させるために
ショートフォームを組み込んだ Web ページを自社アプリの WebView で開く場合（ハイブリッドアプリ）、WebView 側の設定を変えないと動画が再生されない、または全画面に飛び出します。 SDK は <video playsinline muted> でインライン自動再生を試みますが、WebView のデフォルト設定がこれを妨げるためです。以下はアプリのコードで 1 回設定すれば済みます。
| プラットフォーム | 設定 | 設定しないと |
|---|---|---|
iOS（WKWebView） | configuration.allowsInlineMediaPlayback = true | 再生が始まった瞬間にネイティブの全画面プレイヤーへ切り替わり、ショートフォームの UI が消えます |
Android（WebView） | settings.mediaPlaybackRequiresUserGesture = false | 視聴者が自分でタップするまで自動再生が始まりません — コレクションのカードやプレビューが静止画のように見えます |
// iOS — WKWebView を作成するとき
let configuration = WKWebViewConfiguration()
configuration.allowsInlineMediaPlayback = true
let webView = WKWebView(frame: rect, configuration: configuration)// Android — WebView の生成後
webView.settings.mediaPlaybackRequiresUserGesture = false関数インデックス
cloud.shoplive.* のうち Web 連携で使う関数を、導線ごとにまとめました。名前が分かっているときに、どのページを見ればよいかを探す用途です。
| グループ | 関数 | ガイド |
|---|---|---|
| 初期化 | initShortform(config) | クイックスタート · フィールド |
| 一覧 | setShortformCollection(containerId, config?) · destroyShortformCollection(containerId?) | コレクション |
| プレビュー | showShortformPreview(config?) · hideShortformPreview() | プレビュー |
| ショーケース | setShortformShowcase(containerId, config?) | ショーケース |
| ストーリー | setShortformStory(containerId, config?) · destroyShortformStory(containerId?) | ストーリー |
| プレイヤーの起動 · 制御 | showShortformPlayerModal(config?) · dismissShortformPlayerModal() · shortformPlayerAppendList({ ids | shortforms }) · setShortformGlobalMuteState(bool) · getShortformGlobalMuteState() | プレイヤーを開く |
| ユーザー | setUserObject(user | null) · setUserJWT(jwt | null) · logout() | ミッション 7 · ユーザー情報の連携 |
| イベント | addShortformEventListener(fn) · removeShortformEventListener(fn) · （init オプション）messageCallback | イベント処理 |
| 視聴データ | getShortformTotalViewingTime() · setShortformSessionId(id?) | イベント処理 · 視聴時間とセッション |
| インラインプレイヤー | setShortformPlayerView(containerId, config?) · replaceShortformPlayerView(config?) · destroyShortformPlayerViewAndGetContainerId() | 付録 A |
| カスタムショートフォーム | appendCustomShortforms({ customShortforms }) · setCustomShortform(obj) · removeShortform({ shortsIds }) | 付録 B |
この表にない名前が cloud.shoplive に見える場合は、モバイルアプリ SDK 連携用か、以前の名前です。Web 連携では使用しません。
前へ ← 付録次へ → 設定オブジェクト フィールド辞典
設定オブジェクト フィールド辞典
各関数に渡す設定オブジェクトにどんな値を入れられるかをまとめた一覧です。accessKey を除けばほとんどが任意項目なので、必要なものだけを指定し、残りは省略すればデフォルト値またはアカウントの設定値で動作します。
containerId はショートフォーム ID ではなく、自分のページの DOM 要素の id です
下のコレクション · ショーケース · インラインプレイヤービューの 3 つの関数は、あらかじめページに用意した空の要素の中に画面を描画します。そのため第 1 引数に渡す値は、描画場所となる <div> の id 属性の値です — Admin で見るショートフォーム ID ではありません。CSS セレクターではなく document.getElementById() で探すため、# は付けません。<!-- 1. ショートフォームを描画する空の要素を作り、id を付けます -->
<div id="shortform-area"></div>
<script>
// 2. その id の文字列を第 1 引数に渡します（'#shortform-area' ではありません）
cloud.shoplive.setShortformCollection('shortform-area');
</script>その id を持つ要素が見つからない場合、コンソールに Invalid containerId を出力し、何も描画しません。一方プレビューとプレイヤーモーダルは SDK が画面の上に直接表示するため、この引数はありません。
初期化 — initShortform(config)
| フィールド | 必須 | 説明 |
|---|---|---|
accessKey | 必須 | Shoplive が発行する企業識別キー |
userObject / userJWT | 任意 | ログインユーザーの情報。あとから setUserObject / setUserJWT で変更できます（ミッション 7 · ユーザー情報の連携） |
guestUid | 任意 | 未ログインユーザーの識別 ID。未設定の場合は SDK が発行してブラウザーに保存します |
messageCallback | 任意 | イベントごとにデフォルト動作を上書きする関数のマップ（イベント処理） |
platform | 任意 | ショップのログイン状態を SDK に読み取らせます — 'CAFE24' · 'WISA' · 'GODOMALL' · 'SHOPIFY'。値によってページに用意するものが異なるため、ユーザー情報の連携 · プラットフォーム自動連携も併せてご覧ください |
shopify | 任意 | Shopify 専用 — cartLink · customUISections[] |
isSPA | 任意 | true の場合、ページ遷移時に SDK を再初期化せず維持します（付録 D） |
useAMD / AMDLoader | 任意 | RequireJS 環境（付録 F） |
customerDeviceId | 任意 | 自社で使用する端末識別 ID。設定すると SDK が送るすべてのリクエストに同じ値が付与され、自社のログと Shoplive の記録を端末単位で突き合わせられます |
anonId | 任意 | 自社で管理する未ログイン識別子。購入コンバージョンの集計にも使われます。ページ URL に ?anonId= として渡しても同様に認識されます |
gaId | 任意 | Google Analytics のクライアント ID。設定しておくと、Shoplive の記録と GA のデータを同一ユーザーとして突き合わせられます。?gaId= クエリも同様です |
ceId | 任意 | コンバージョン集計に使う匿名識別子。指定しないのが基本で、SDK がブラウザーに自動生成 · 保存します。自社の識別子で上書きする必要がある場合にのみ指定してください（コンバージョン · つながる条件） |
useWebVideoPlayer | 任意 | true にすると HLS ではなくブラウザー標準の動画再生を使用します。特定の環境で再生できないときの対処策なので、通常は指定しないでください |
ここにない値をコードで見かけた場合。 モバイルアプリの WebView で SDK を表示する際にアプリが渡す値（広告識別子など）、特定の企業と個別に取り決めた値、または Shoplive の開発用の値です。Web ページに直接連携する場合には使用しません。
フィルター共通フィールド — どのショートフォームを取得するか
コレクション · プレイヤーモーダル · プレビュー · インラインプレイヤービューで共通して使えるフィールドです。以下の各関数の表には、このフィールドに加えてその関数だけにあるものを記載しています。
| フィールド | 型 | 説明 |
|---|---|---|
tags | string[] | タグフィルター |
tagSearchOperator | 'OR' | 'AND' | タグの一致方式 |
brands | string[] | ブランド識別子フィルター |
skus | string[] | 紐づく商品 SKU フィルター |
shortformCollectionId | string | Admin のグループ ID |
shuffle | boolean | ランダム順 |
sortProperty / sortDirection | string | 並び替えの基準 / 方向（'asc' | 'desc'）。値はコレクション · フィルターを参照。未指定の場合は Admin の並び順 |
コレクション — setShortformCollection(containerId, config)
フィルター共通フィールドに加えて、以下を指定できます。
| フィールド | デフォルト | 説明 |
|---|---|---|
template | 'GRID1' | 'GRID1' · 'GRID2' · 'HORIZONTAL' |
hasMoreButton | true | もっと見るボタン。false なら無限スクロール（コレクション · もっと読み込む方式） |
rows | 2 | 初期表示の行数 |
limit | — | ショートフォームの最大数 |
displayTags | — | 上部フィルタータブのタグ一覧 |
productLayout | 'CIRCLE' | 'CIRCLE' · 'CARD'。アカウント設定がある場合はその値が優先されます |
disablePreviewVideoPlay | false | カードのホバー時のプレビュー再生を無効化 |
previewVideoAutoPlayType | — | 'intersection' — ビューポート進入時に再生 |
horizontalOption | — | hasDirectionWhenHorizontal · lineItemCount · autoFlow · insideDescription（タイトル・説明をカード内に） · scrollIndicator（リスト下のスクロール進行バー） — コレクション · 表示オプション |
showProduct | false | カード下に紐付いた商品を最大 2 件 + 商品をもっと見る（コレクション · 表示オプション） |
enableGestureSlide | true | ドラッグ / スワイプを許可 |
disableQueryParamHistory | false | URL クエリの記録を無効化 |
プレイヤーモーダル — showShortformPlayerModal(config)
フィルター共通フィールドに加えて、以下を指定できます。ids または shortforms がある場合、フィルターのフィールドは無視されます。
| フィールド | 説明 |
|---|---|
ids | 再生するショートフォーム ID の配列（順序を保持） |
startIndex | ids のうち開始位置（0 から）。範囲を超える場合は 0 |
shortsId | フィルターモードで開始するショートフォーム ID |
muted | 初期状態でミュート |
disableQueryParamHistory | URL クエリの記録を無効化 |
プレビュー — showShortformPreview(config)
フィルター共通フィールドに加えて、以下を指定できます。フィルターのフィールドを 1 つも指定しない場合は、現在のページ URL を基準に関連ショートフォームを取得します。
| フィールド | 説明 |
|---|---|
sku · name | 現在の URL による取得に加える商品 SKU · 商品名のヒント |
position | { 'to-ri' | 'to-le' | 'bo-ri' | 'bo-le': true } |
size | 区分ごとのサイズ。{ desktop: { width: '160px' }, mobile: { width: '28vw' } } のように入れ子のオブジェクトで指定します。各区分は width · maxWidth · height · maxHeight を CSS 文字列で受け取り、すべて任意です（プレビュー · 位置とサイズ） |
closePolicyExpiry | 閉じたあと再表示しない時間（分）。未指定または 0 ならセッション内は再表示しません |
resizable | 視聴者によるサイズ変更を許可 |
disableQueryParamHistory | URL クエリの記録を無効化 |
ショーケース — setShortformShowcase(containerId, config)
| フィールド | デフォルト | 説明 |
|---|---|---|
shortformId | — | 直接指定するショートフォーム ID。url より優先されます |
url | 現在のページ URL | 関連ショートフォームの取得基準となる URL。指定するとカードのタップでこの URL に遷移します |
thumbnail | true | 下部のカードサムネイルストリップ（カードが 2 枚以上のときのみ表示） |
removeOriginalDOM | true | 描画成功後にコンテナの既存の子要素を削除 |
ストーリー — setShortformStory(containerId, config)
3 つの条件配列のうち少なくとも 1 つを渡さないと円は出ません。フィルター共通フィールドはここでは使いません。
| フィールド | デフォルト | 説明 |
|---|---|---|
brands | — | string[] ブランド識別子。1 つにつき円 1 つ |
tags | — | string[] タグ。1 つにつき円 1 つ |
shortformCollectionIds | — | string[] Admin のショートフォーム グループ ID。1 つにつき円 1 つ（ストーリー · ステップ 1） |
size | 72 | 円の直径（px） |
grid | false | true にするとストーリーの下に有効な条件のコレクションを GRID2 で描画（ストーリー · ステップ 2） |
gridContainerId | — | grid モードでコレクションを描く別コンテナの id。存在しない、またはストーリー自身・祖先を指す場合は警告のうえストーリーの下に戻します |
インラインプレイヤービュー — setShortformPlayerView(containerId, config)
フィルター共通フィールドとプレイヤーモーダルの ids · shortforms · startIndex · shortsId · muted をそのまま使え、これに customShortforms（カスタムショートフォームオブジェクトの配列）を加えられます。
カスタムショートフォームオブジェクト — appendCustomShortforms · setCustomShortform
| フィールド | 説明 |
|---|---|
shortsId | 必須。 Shoplive のショートフォーム ID |
customShortformId | 自社のショートフォーム固有 ID |
title · description · backButtonTitle | タイトル · 説明 · 戻るボタン横のタイトル |
creatorName · creatorImage · creatorLevel · levelImageUrl · creatorIsFollow | クリエイターの表示情報とフォロー状態 |
likeCount · likeCountText · isLike · commentsCount · commentCountText | いいね · コメントの数と表示テキスト |
linkButton { url, title } | 外部リンクボタン |
externalProducts[] | 外部商品 — productId · sku · name · brand · url · imageUrl · currency · originalPrice など |
extra | 自社の自由なデータ。イベントの payload にそのまま含まれて返ります |
イベントの payload — 商品 · ショートフォーム
| オブジェクト | 主なフィールド |
|---|---|
payload.product | productId · name · brand · url · sku · imageUrl · currency · originalPrice · discountPrice · discountRate |
payload.shorts | shortsId · shortsDetail.{title, description, tags, brand} · cards[] · shortsIndex · （カスタムショートフォームの場合）custom |
イベント辞典
addShortformEventListener で受け取れるイベントの全一覧です。デフォルト動作がある 7 種類だけ messageCallback で動作を変えられ（イベント処理 · デフォルト動作を変える）、それ以外は観測用です。
デフォルト動作があるイベント（7）
PLAY_SHORTFORM_DETAIL · CLOSE_SHORTFORM_DETAIL · LOGIN_REQUIRED · ON_CLICK_PRODUCT_ITEM · ON_CLICK_PRODUCT_BANNER · ON_CLICK_LINK_BUTTON · ON_CLICK_SHARE_BUTTON — 詳細はイベント処理の表をご覧ください。
通知イベント（6）
| イベント | タイミング | payload |
|---|---|---|
ON_SHORTFORM_DETAIL_READY | プレイヤーの準備が完了したとき | shorts |
VIDEO_TOTAL_VIEWING_TIME | ショートフォーム 1 本を離れるとき | shortsId · totalViewingTime · videoDuration · videoDurationText |
NEEDS_SHORTFORM_LIST_MORE | ID 指定の再生リストの終わりに近づいたとき | — |
ON_SHORTS_SHOWCASE_RENDERED | ショーケースの描画結果 | success · shortsId · shorts | reason |
ON_SHORTS_STORY_RENDERED | ストーリーの円ごとのレンダー結果 | items[] — type（brand|tag|collection）· identifier · success · label · shortsCount |
ON_DRAG_START_PREVIEW / ON_DRAG_END_PREVIEW | プレビューのドラッグ開始 · 終了 | — |
トラッキングイベント
| 領域 | イベント |
|---|---|
| 一覧（コレクション） | COLLECTION_SHOW · COLLECTION_SHOW_WHEN_VIDEO_PLAY · COLLECTION_CLICK_ITEM · COLLECTION_CLICK_VIEW_MORE |
| プレビュー | PREVIEW_SHOWN · PREVIEW_HIDDEN · PREVIEW_CLICK_SHOW · PREVIEW_CLICK_CLOSE |
| プレイヤー — 表示 · 再生 | DETAIL_ON_PLAYER_SHOW · DETAIL_ON_PLAYER_DISMISS · DETAIL_ACTIVE（ショートフォームの切り替え） · DETAIL_EMPTY · DETAIL_VIEWING_SECONDS · DETAIL_VIDEO_LOOP · DETAIL_SEEK_VIDEO · DETAIL_PAUSE_VIDEO · DETAIL_RESUME_VIDEO · DETAIL_CLICK_MUTE · DETAIL_CLICK_UNMUTE · DETAIL_CLICK_BACK_BUTTON · DETAIL_EXTERNAL_VIDEO_ON_ERROR · DETAIL_EXTERNAL_VIDEO_RECOVERED_FROM_ERROR |
| プレイヤー — 商品 · リンク | DETAIL_CLICK_PRODUCT_CARD · DETAIL_SWIPE_PRODUCT_CARD · DETAIL_EXPAND_PRODUCT_LIST · DETAIL_DISMISS_PRODUCT_LIST · DETAIL_CLICK_PRODUCT_LIST_ITEM · DETAIL_CLICK_PRODUCT_BANNER · DETAIL_CLICK_LINK_BUTTON · DETAIL_CLICK_BRAND · DETAIL_CLICK_LIVE_CAMPAIGN_LINK |
| プレイヤー — ソーシャル | DETAIL_CLICK_LIKE · DETAIL_CLICK_SHARE · DETAIL_CLICK_BOOKMARK · DETAIL_CLICK_CREATOR_PROFILE · DETAIL_CLICK_FOLLOW_BUTTON · DETAIL_CLICK_COMMENT · DETAIL_CLOSE_COMMENT · DETAIL_CREATE_COMMENT · DETAIL_UPDATE_COMMENT · DETAIL_DELETE_COMMENT · DETAIL_CLICK_REPLY · DETAIL_CLICK_COMMENT_LIKE · DETAIL_CLICK_MORE_OPTION_BUTTON |
| プレイヤー — 探索 · タグ | DETAIL_EXPAND_DESCRIPTION · DETAIL_COLLAPSE_DESCRIPTION · DETAIL_CLICK_TAG · DETAIL_CLICK_FILTER_TAG · DETAIL_CLICK_TAG_COLLECTION_ITEM · DETAIL_CLOSE_TAG_COLLECTION · DETAIL_CLICK_CREATOR_SHORTFORM_COLLECTION_ITEM · DETAIL_CLOSE_CREATOR_SHORTFORM_COLLECTION |
前へ ← フィールド辞典次へ → トラブルシューティングと FAQ
トラブルシューティングと FAQ
何も表示されません（コンソールにエラーもありません）
まずブラウザーのコンソールを確認してください。正常に初期化されていれば [shoplive shortform initShortform start] のログが出ます。そのあと、以下のどのメッセージが見えるかで原因が分かれます。
| コンソールのメッセージ | 原因 · 対処 |
|---|---|
Invalid Shorts settings | Access Key が誤っているか、設定の取得に失敗しています。この場合、それ以前に呼び出した表示関数もすべて失われるため、キーを修正して再読み込みしてください |
Invalid containerId | コンテナの div の id が渡した値と異なるか、呼び出し時点で DOM に存在していません |
"tags" property must be array | tags · brands を文字列で渡しています → 配列に修正してください（コレクション） |
| （警告が出たあと何も起こらない） | 契約状況などアカウント側の問題の可能性があります — Shoplive 担当者にお問い合わせください |
メッセージが 1 つも出ない場合は、<script src="…shoplive-shortform.js"> が cloud.shoplive.* の呼び出しより前にあるか、そして Admin にフィルター条件（タグ · SKU）に合う公開ショートフォームがあるかを確認してください。
プレビューやショーケースだけが表示されません
どちらも「条件が合わなければ静かに描画しない」のが正常な動作です。プレビューは表示されない 5 つのケース、ショーケースは事前準備（2 つの利用設定 + コンテナのサイズ）を順に確認してください。開発中であれば、ブラウザーのストレージを空にするのが最初の一歩です。
iOS で動画が自動再生されず、静止画のままです
SDK は iOS の自動再生ポリシーに合わせ、ミュート · インライン再生で開始します。それでも特定の端末だけ静止画のままなら、その端末の設定 → アクセシビリティ → 動作 → 「ビデオプレビューの自動再生」がオフになっていないか確認してください。低電力モードや低データモードでも同じ結果になります。ユーザーが意図的にオフにした設定のためコードで回避することはできず、タップすれば正常に再生されます。
ただし自社アプリの WebView で開いたページの場合は原因が異なります — WebView の設定によってインライン自動再生が妨げられているので、アプリのコードで修正できます。付録 G · 自社アプリの WebView 内で表示するをご覧ください。
プレイヤーが開くと自社の SPA ルーターが反応します / 戻るの挙動がおかしいです
SDK が URL に __sl_shorts_id を pushState するためです。表示関数の呼び出しに disableQueryParamHistory: true を指定してください（ディープリンク）。
商品をクリックするとページ全体が再読み込みされます
ON_CLICK_PRODUCT_ITEM のデフォルト動作が location.href = product.url だからです。messageCallback にこのイベントを登録し、ルーターによる遷移に変更してください（イベント処理）。新しいタブで開きたい場合は、その中で window.open(payload.product.url) を呼び出します。
ショーケースは描画されるのに、タップしても反応しません
ページのグローバル CSS が SDK の透明なクリック領域を隠しているケースです（例: div:empty { display: none }）。開発者ツールでコンテナ内の .csl- 要素にページの CSS が適用されていないか確認し、そのルールの適用範囲をコンテナの外に限定してください（ショーケース）。
プレイヤーの見た目が自社サイトでだけ崩れます
SDK は自社の DOM の中に描画されるため、ページのグローバルスタイルと衝突することがあります。SDK の要素は sl- · csl- の接頭辞を使いますが、ページに video · img などのタグ単位のグローバルスタイル（例: img { width: 100% !important }）があると影響を受けます。開発者ツールで崩れた要素にどのルールが適用されているかを確認し、ルールの範囲を狭めてください。解決が難しい場合は Shoplive 担当者にお問い合わせください。
初期化の前に呼び出してよい関数と、そうでない関数
表示関数（setShortformCollection · showShortformPreview · setShortformShowcase · showShortformPlayerModal）は、初期化前に呼び出すとキューに積まれ、自動的に実行されます。一方 destroy* · hideShortformPreview · shortformPlayerAppendList · get/setShortformGlobalMuteState · getShortformTotalViewingTime は即座に実行されるため、初期化が終わったあと（または表示関数が動作したあと）に呼び出してください。setShortformPlayerView については付録 A の注意事項をご覧ください。
CSP（Content-Security-Policy）を使用しています。どのドメインを許可すればよいですか？
| ディレクティブ | 許可するオリジン | 用途 |
|---|---|---|
script-src | https://static.shoplive.cloudhttps://cdnjs.cloudflare.com | SDK 本体と遅延読み込みチャンクは static、HLS 再生ライブラリ（hls.js）は cdnjs から読み込みます |
style-src | https://static.shoplive.cloud · 'unsafe-inline' | SDK のスタイルシート · アカウントのカスタムスタイル（インライン） |
connect-src | https://config.shoplive.cloud · https://api.shoplive.cloud · https://*.shoplive.cloud | 企業設定 · ショートフォーム API · 視聴ログ · 動画セグメント |
media-src · img-src | https://*.shoplive.cloud · blob: | 動画（HLS には blob: が必要） · サムネイル |
正確な API ホストはアカウントの設定によって異なる場合があるため、公開前にネットワークタブで確認してください。