salla-snippets

Salla ストアフロントスニペットのフロー

アクションを実行して Salla ストアフロントのイベントと連携します。デバイスモードの スニペットは Salla Partners MCP の salla_snippets ツールで挿入し、クラウドモードは App Function で実行します。手順に沿って進め、次に進む前に各ゲートを完了してください。

ツール

ツール	アクション	機能
salla_snippets	list / parameters / create / update / delete	アプリのストアフロントスニペットを管理します

前提条件： Salla Partners MCP サーバーに接続されており、アプリの app_id が必要です。クラウドモードは App Function として実行されます。作成とデプロイ → salla-app-functions。

---

ステップ 0 — 確認

開始前に質問します。

1. 処理したいストアフロントイベントは何ですか？ （例：cart::item.added、cart::updated、product::price.updated — Twilight イベントは :: で名前空間が区切られています。名前はカタログで確認してください。 references/device-mode.md）
2. イベント発生時に何を実行しますか？ （アナリティクスの記録、データの同期、自動化のトリガー、コンテンツのパーソナライズ）

回答をもとに、ステップ 1 で適切なモードを判断します。

---

ステップ 0.5 — レガシーコンテンツを検出する（デバイスモードのみ）

ひな形を作成する前に、渡されたスニペットの内容（貼り付けられたもの、Portal からエクスポートされたもの、 または既存のスニペットから読み戻したもの）を確認します。

• HTML タグ（<script、<style、<div、<link、<iframe、…）が含まれていますか？
• {{namespace.key}} トークン（Twig 形式の二重波括弧）が含まれていますか？

どちらかに該当する場合、これは旧サーバーサイドテンプレートパイプラインのレガシーコンテンツです — ここで作業を止めてください。salla-snippets-migration に引き継ぎ、まず純粋な JS に変換してから、変換後の出力を使って以下のステップ 2 から再開してください。 HTML/Twig コンテンツを、解析できそうに見えるだけの状態へ手作業で修正しようとしないでください — 変換には実際のルール（パラメータモデル、salla.onReady のタイミング）があり、それは このスキルの担当範囲です。

ゲート： ステップ 2 に進む前に、コンテンツに HTML タグと裸の {{...}} トークンが含まれていないことを確認します。

---

ステップ 1 — 連携モードを選択する

モード	実行場所	最適な用途
デバイスモード	ブラウザー（tracker.js + Twilight SDK）	アナリティクス、パーソナライズ、マーケティングアトリビューション
クラウドモード	サーバー（App Functions）	自動化、データ同期、信頼性の高いバックエンド配信

判断基準：

• リアルタイムのブラウザーデータやマーケティングピクセルが必要 → デバイスモード
• 確実な配信、バックエンドロジック、または API 呼び出しが必要 → クラウドモード

まだ不明な場合は、次のように質問してください。 「ブラウザーとサーバーのどちらで実行しますか？」

ゲート： 「モードを確認しました。ひな形の作成に進みます。」

---

ステップ 2 — 実装のひな形を作成する

デバイスモード

スニペットの本体は、Twilight SDK 経由でストアフロントのブラウザー上で実行されます。リスナーを記述し、ツールを使ってストアフロントのスニペットとして挿入します。

1. スニペットの本体をプレーンな JavaScript で記述します。スニペットは、Salla が CDN から配信する純粋な JavaScript ファイルで、<script src> 経由ですべてのストアフロントページに読み込まれます。salla、salla.onReady、salla.event、salla.config.get(...) を直接使用します。（すべてのルール — Twig／HTML ラッパー、ブートストラップのタイミング、デプロイガード → references/device-mode.md。）

   スニペットには異なる役割が2つあります。分けて扱ってください。

   • ストアフロントイベントをリッスンする（名前空間は ::。ペイロードは e.data 内）。初期化時のイベントを逃さないよう、リスナーはモジュールのトップレベルで登録します。

     salla.event.on("cart::item.added", (e) => {
       var productId = e.data.product_id; // ペイロードは e.data 内
     });
     

     イベント一覧とペイロードの形式 → references/device-mode.md。

   • アプリの設定を読み取るには salla.config.get("app.<key>") を使います。これが、ストアフロントのスニペットからマーチャントのアプリ設定を読み取る唯一の方法です。そこで参照できるのは、public: true に設定された項目だけです。ストアの状態を読み取る処理は salla.onReady の中で実行します。

     salla.onReady(function () {
       var rewardsOn = salla.config.get("app.rewards_enabled") || false;
       var pointValue = salla.config.get("app.point_value_halalah") || 0;
     });
     

     設定はマーチャントがアプリをどのように構成したかを示し、イベントは購入者が何をしているかを示します。キーと public にする項目は salla-app-settings で定義します。ストア／セッション設定（user.id、user.email — 購入者の情報、store.username、store／user オブジェクト全体）と防御的な読み取りパターン → references/device-mode.md の ストアコンテキストと言語。customer.* と store.domain は使用禁止です。非推奨／削除済みのため、決して使用しないでください（詳細なルールは references/device-mode.md）。

2. （任意）利用可能なテンプレート変数を確認します：salla_snippets action=parameters、 app_id。

3. スニペットを挿入します：salla_snippets action=create、app_id、name（必須）、place （"before" — 使用可能な値はこれのみ）、tag（"body" のみ — スニペットは </body> の前に描画されます）、content（純粋な JS）。先に重複を確認してください： salla_snippets action=list を呼び出し、このアプリの既存スニペットがあれば、作成前に update／delete します。重複したスニペットが積み重なると、UI が二重に描画され、イベントも二重に発火します。salla_snippets action=list／get で読み戻すと、CDN の url（.js ファイル）と path を含むスニペットのメタデータが返されます。update はスニペット全体を再検証するため、name、place、tag、content をまとめて再送してください（部分的なパッチではありません）。action=update は確認情報（{ snippet: { id, name, updated } }）を返します。CDN の最新の url を取得するには action=list を使用してください。

   スニペットの管理には salla_snippets MCP ツールのみを使用してください — このツールがフィールドのマッピングと検証を担います（content を内部フィールドにマッピングします）。スニペットに関するすべての操作は、このツールのいずれかのアクションを通じて行ってください。

デバイスモードのセットアップ、イベント一覧、ペイロードの形式 → references/device-mode.md

すべての作成／更新で検証する（クローズドループ）

salla_snippets create／update の成功は、検証の始まりであり、終わりではありません — 200 はファイルがデプロイされたことを確認するだけで、実行できることを確認するものではありません。すべての create／update を1回のループの開始として扱い、問題がなくなるまで繰り返します。

1. JavaScript としての解析チェック（create／update の前に実施） — content が有効な JavaScript として解析できることを確認します。これは、Portal エディターで保存前に実行されるチェックと同じです。例：node --check snippet.js、または try/catch 内で new Function(code) を実行します。パターンマッチングではなく、実際に解析してください — <script> タグ、HTML、Twig（{{ … }}／{% … %}）はすべて JavaScript として解析できず、スニペットは .js ファイルとして配信されるため、自動的に検出されます。保存前に構文エラーを修正してください。MCP は content の形式を検証しなくなったため、本文を正しく解析できるようにする責任は作成者にあります。→ references/device-mode.md。
2. 禁止パラメーターのチェック — content 内で salla.config.get("customer／salla.config.get('customer および salla.config.get("store.domain／salla.config.get('store.domain を grep します。一致があれば例外なく拒否してください — customer.* と store.domain は非推奨または削除済みで、機械的な置き換え先はありません（一覧は references/device-mode.md の Store context & language を参照）。user.* は別の概念（購入者）であり、1 対 1 の名前変更先ではありません — 書き換える前に、スニペットが実際に必要とするデータを一覧と照らし合わせてください。必要なデータが、ドキュメントに記載された user.*／store.* から取得できない場合、クライアント側では利用できません。パスを捏造しないでください。
3. 設定キーのチェック — スニペットが読み取るすべての salla.config.get("app.<key>") について、<key> がアプリの設定で定義され、public: true とマークされていることを確認します。キーが存在しない場合、または public でない場合、ストアフロントでは undefined が返されます。設定が契約を定めます → salla-app-settings と照合してください。
4. ブラウザーテスト — 以下の DevTools コンソール手順を実行します（ロードマーカー、エラーがないこと、想定される e.data と設定値）。
5. 修正 → ツールで再度 update → 再検証 — 4 つすべてに合格するまで繰り返します。

ブラウザーでスニペットをテストする

スニペットは購入者のブラウザーで実行されるため、salla_snippets の 200 はデプロイされたことを確認できるだけです。DevTools Console を使い、実際のブラウザーで実行されることを確認してください。

1. ストアフロントを開きます。 先にデモストアにアプリをインストールし（→ salla-live-testing）、そのストアの url を開いて、 スニペットが実行されるページに移動します。利用可能であればヘッドレスブラウザー （Playwright／Puppeteer）で操作し、そうでなければユーザーに手順を案内してページと DevTools Console（および Network タブ）を開いてもらいます。

2. デバッグログを追加します。 実行内容とデータがわかるようにスニペットに計測コードを追加します。読み込みマーカー、読み取った設定値、各イベントのペイロードを出力します。

   (function () {
     console.log("[myapp] snippet loaded");
     salla.event.on("cart::item.added", function (e) {
       console.log("[myapp] cart::item.added", e.data); // real payload shape
     });
     salla.onReady(function () {
       console.log(
         "[myapp] rewards_on",
         salla.config.get("app.rewards_enabled"),
       );
     });
   })();
   

3. 操作を実行して確認します。 商品をカートに追加するなどの操作を行い、コンソールで次の内容を確認します。読み込みマーカーが記録されていること、赤いエラーがないこと、ハンドラーに期待どおりの e.data が記録されていること、salla.config.get("app.<key>") の値が期待どおりであること。

4. コンソールから原因を特定します。

   表示される内容	意味	対処
   何も記録されない	このストアにスニペットがない／ページが再読み込みされていない／SDK がページにない	このストアにデプロイされていることを確認し、再読み込みして、salla.onReady が発火するページで実行します
   salla.config.get("app.<key>") が undefined	設定が public ではない、またはキーが間違っている	public: true に設定します（salla-app-settings）／キーを修正します
   ハンドラーが一度も発火しない	イベント名が間違っている	references/device-mode.md の :: カタログを確認します

5. 公開前に: デバッグ用の console.log を削除するか、実行されないようにし、ログにシークレットや個人を特定できる情報を含めないでください（このファイルはすべての購入者に配信されます）。

Twilight JS SDK（アプリのスニペット向け）

Twilight テーマエンジンは、Twilight Storefront JS SDK（window.salla）をすべてのストアフロントページに自動で挿入します（body:end フック）。スニペットは同じページで実行されるため、認証、カート、ウィッシュリスト、商品、注文、評価、通貨、ロイヤルティ、コメント、プロフィール、予約、salla.api.component.*、salla.config、salla.event、salla.storage、salla.notify、salla.lang、salla.helpers、メタデータなど、同じランタイム API を呼び出せます。

メソッドカタログ（シグネチャ、モジュール別ドキュメントリンク、アプリのスニペットとテーマの境界、salla.init() のルール）→ references/twilight-js-sdk.md。 イベント（:: カタログ、product::fetch.succeeded の落とし穴、価格のエンコーディング）→ references/device-mode.md。

使い分け: このスキルは購入者のブラウザーを対象とします（スニペットによる顧客側の操作／イベント）。同じアクティビティに対するサーバー側の処理には、フック可能なルールが適用されます。App Function トリガーを持つサーバーイベントの場合は → App Function (salla-app-functions、サーバー側の V8 分離環境で実行、推奨)。それ以外の場合は → webhook (salla-webhooks)。ネイティブの可視 UI については → salla-storefront-ui。

Storefront UI の準拠（スニペットが表示される UI を描画する場合）

スニペットがページに描画される場合は、手作りの HTML ではなく、Storefront JS SDK で動作する Salla ネイティブの UI Components （Twilight <salla-*> Web コンポーネント）で UI を構築してください。ネイティブコンポーネントはテーマのトークン、RTL、ロケールをそのまま継承するため、単独の SaaS バッジではなく、ストアの一部として自然になじみます。

• <salla-*> コンポーネントで描画します。 ドキュメントに記載されたタグを挿入し、その属性 /プロパティを設定します。例：<salla-button>、<salla-modal>、<salla-rating-stars>、 <salla-quantity-input>、<salla-products-slider>。正確なタグと props は UI Components カタログ（以下のコンポーネントファミリー）で確認してください。テーマはすべてのストアフロントページでこれらのコンポーネントを登録します。対象のストアにコンポーネントがない場合は、使用前に CDN からローダー（@salla.sa/twilight-components ESM ローダー）を実行時に読み込んでください。
• 動作は SDK 経由で接続します — salla.config.get(...) で状態を読み取り、salla.event.on(...) で反応し、salla.cart.* / salla.product.* などを呼び出します（メソッドカタログ → references/twilight-js-sdk.md）。
• 独自のマークアップを記述する場合は、Twilight CSS 変数 （--color-primary、--color-text、--font-main、スペーシング／角丸）を継承し、Salla Icons （sicon-* クラス）を使用して、周囲のスペーシング／密度に合わせ、dir／lang（アラビア語／RTL を優先）に従ってください。ハードコードしたフォント／色／ボーダー／影は、フォールバックとしてのみ使用してください。
• 実際に検証します — インストール済みのデモストア（salla_apps action=demo_stores → url）を開き、商品ページのスクリーンショットを撮影してください。コード上で「動作する」ことは、見た目が正しい証拠にはなりません。

「ネイティブコンポーネントを使用し、ネイティブの見た目と操作感に合わせる」というルールと実際の検証ゲートは、salla-storefront-ui が管理しています。詳しいガイダンスについては、これに従ってください： salla-storefront-ui。

UI コンポーネントファミリー（すべて <salla-*>。カタログ全体はドキュメントを参照）：

ファミリー	例
商品	salla-product-card、salla-products-slider、salla-add-product-button
ショッピング／カート	salla-quantity-input、salla-quick-buy、salla-cart-summary
ユーザー／認証	salla-login-modal、salla-userprofile、salla-verify
フォーム／入力	salla-tel-input、salla-datetime-picker、salla-file-upload
要素／レイアウト	salla-button、salla-modal、salla-rating-stars、salla-tabs

ドキュメント：UI Components Overview https://docs.salla.dev/422688m0.md · Usage https://docs.salla.dev/422689m0.md · Customization https://docs.salla.dev/422690m0.md · Storefront JS SDK https://docs.salla.dev/422610m0.md · theme https://docs.salla.dev/421877m0.md · CSS variables https://docs.salla.dev/421945m0.md · Salla Icons https://docs.salla.dev/422550m0.md · single product page https://docs.salla.dev/422561m0.md.

Cloud Mode

Cloud Mode は App Function です — ストアフロントイベントをトリガーとしてハンドラーを記述し、salla-app-functions スキルに最初から最後まで従ってください（テンプレート、Resp API、型付きコンテキスト、デプロイ）。ここでテンプレートを重複して記載しないでください。

ゲート：「イベントをテストします。デモストアからイベントをトリガーし、ハンドラーが正しく実行されることを確認してください。」

注意すべき誤り

ついやってしまいがちな考え	それが誤りである理由
「HTML タグを削除してそのまま進めればいい。ほとんどはすでに JS だ」	レガシーコンテンツには実際の変換ルール（パラメーターモデル、salla.onReady のタイミング）があります。手作業で修正するとこれらが省略され、読み取りエラーや未定義の読み取りが発生した状態でリリースされます。salla-snippets-migration に引き継いでください。
「テストでは customer.email を問題なく読み取れたから、このままリリースしよう」	呼び出しがたまたま解決するかどうかにかかわらず、customer.* は禁止されています。これは非推奨または削除済みであり、スタイルの選択ではありません。買い物客を表す user.* を使用してください。
「レガシーの {{store.id}} トークンが1つだけあるけれど、それは残して残りを修正しよう」	デプロイするにはコンテンツを有効な JS として解析できなければなりません。{{ }} はリテラルテキストとして配信され、スクリプト（または salla_snippets 自体の保存）を壊します。保存する前にすべてのトークンを変換してください。

---

リソース

トピック	リンク
デバイスモードの使用	https://docs.salla.dev/1724504m0.md
クラウドモードの使用	https://docs.salla.dev/1724667m0.md
アプリ関数の概要	https://docs.salla.dev/1726814m0.md
アプリ関数のイベント	https://docs.salla.dev/1726818m0.md
アプリスニペットの概要	https://docs.salla.dev/2220706m0.md
HTML→JS 移行ガイド	https://docs.salla.dev/2247590m0.md