wix-cli-embedded-script

Wix Embedded Script Builder

Wix CLI アプリケーション向けの埋め込みスクリプト拡張機能を作成します。埋め込みスクリプトは、Wix サイトの DOM に挿入される HTML コードフラグメントです。サードパーティサービスとの連携、分析トラッキング、広告、カスタム JavaScript 機能を実現できます。

クイックスタートチェックリスト

埋め込みスクリプトを作成する際は、次の手順に従ってください。

1. スクリプトフォルダーを作成します：src/extensions/site/embedded-scripts/<script-name>/
2. config 要素、スタイル、スクリプトロジックを含む embedded.html を作成します
3. extensions.embeddedScript() と一意の UUID を含む extensions.ts を作成します
4. ダッシュボード設定ページを作成します：src/extensions/dashboard/pages/<script-name>-settings/
5. @wix/app-management の embeddedScripts API を使って設定ページを実装します
6. src/extensions.ts を更新して、両方の拡張機能をインポートして使用します
7. Wix Dev Center で SCOPE.DC-APPS.MANAGE-EMBEDDED-SCRIPTS 権限を追加します（埋め込みスクリプト権限の有効化を参照）

スクリプトの種類

埋め込みスクリプトでは、同意管理のために種類を宣言する必要があります。

種類	説明	用途
ESSENTIAL	サイトの運用に不可欠な中核機能	認証、セキュリティ機能
FUNCTIONAL	ユーザーの選択を記憶して、エクスペリエンスを向上させる	言語設定、UI のカスタマイズ
ANALYTICS	訪問者によるサイトの利用状況に関する統計を提供する	Google Analytics、Hotjar、Mixpanel
ADVERTISING	マーケティング目的で訪問者データを提供する	Facebook Pixel、Google Ads、リターゲティング

選択ルール： スクリプトが複数の種類に該当する場合は、リストの下にある種類（より制限の厳しいもの）を選択してください。たとえば、分析と広告の両方の側面を持つスクリプトは、ADVERTISING として指定してください。

配置オプション

配置	説明	最適な用途
HEAD	<head> タグと </head> タグの間	分析、早期初期化
BODY_START	開始 <body> タグの直後	重要な機能、noscript
BODY_END	終了 </body> タグの直前	非ブロッキングスクリプト、パフォーマンス

選択のガイドライン：

• 分析／トラッキング → HEAD（早期に初期化）
• 広告ピクセル → BODY_END（非ブロッキング）
• 重要な機能 → HEAD または BODY_START
• 重要度の低い機能 → BODY_END（パフォーマンス向上）

動的パラメーターとダッシュボード設定

すべての埋め込みスクリプトには、パラメーターを設定するための対応するダッシュボードページが必要です。 サイト所有者はダッシュボードページの UI で値を設定し、その値がテンプレート変数として埋め込みスクリプトに渡されます。

アーキテクチャのフロー

Dashboard Page (React UI)
    │
    │  embeddedScripts.embedScript({ parameters: {...} })
    ▼
Wix App Management API
    │
    │  Stores parameters, injects as template variables
    ▼
Embedded Script (HTML)
    │
    │  {{parameterKey}} → actual value
    ▼
Site DOM

関連スキル： wix-cli-dashboard-page を使って、埋め込みスクリプトの設定 UI を作成してください。

パラメーターの種類

種類	説明	ダッシュボードコンポーネント
TEXT	1 行テキスト	Input
NUMBER	数値	Input type="number"
BOOLEAN	true／false の切り替え	ToggleSwitch、Checkbox
IMAGE	メディアマネージャーの画像	ImagePicker
DATE	日付のみ	DatePicker
DATETIME	日付と時刻	DatePicker + TimeInput
URL	検証機能付き URL	Input
SELECT	ドロップダウンの選択肢	Dropdown
COLOR	色の値	ColorPicker

テンプレート変数の構文

埋め込みスクリプトでは、テンプレート変数の構文 {{variableName}} を使用してパラメーターを設定できます。これらのパラメーターはダッシュボードから設定し、HTML／JavaScript コードで使用するテンプレート変数として渡します。

使用方法：

1. テンプレート変数の構文：

   • {{parameterKey}} の構文を使用して、パラメーター値を HTML に挿入します
   • テンプレート変数は HTML 属性で使用できます
   • スクリプトが挿入されると、実際の値に置き換えられます

2. HTML 属性（必須）：

   • すべてのパラメーター値を、設定要素の data 属性に格納します
   • テンプレート変数を使用できるのはここだけです。JavaScript 内に直接記述することはできません
   • 例：<div id="config" data-headline="{{headline}}" data-text="{{text}}"></div>

3. JavaScript からのアクセス：

   • JavaScript では、data 属性からパラメーター値を読み取る必要があります
   • getAttribute() または dataset プロパティを使用します
   • 例：

     const config = document.getElementById("config");
     const headline = config?.getAttribute("data-headline");
     // または dataset を使用：
     const { headline, text } = config.dataset;
     

4. 型安全性：

   • JavaScript で使用するときは、パラメーターの型に注意してください
   • NUMBER 型：Number() または parseInt() で変換します
   • BOOLEAN 型：'true' または 'false' の文字列と比較します
   • DATE／DATETIME：new Date() で解析します

5. 必須と任意：

   • 必須パラメーターには常に値が設定されます
   • 任意のパラメーターは空の場合があるため、適切に処理してください
   • 任意のパラメーターにはフォールバック値を指定してください

6. 関連するパラメーターの使用：

   • 現在のユースケースに関連する動的パラメーターのみを使用してください
   • 実装する機能に関係のないパラメーターは無視してください
   • 使用する各パラメーターは、スクリプトの機能において明確な目的を持つ必要があります
   • 該当しないパラメーターをすべて使用する必要はありません

使用例：

パターン 1 - data 属性での設定：

<div
  id="script-config"
  data-api-key="{{apiKey}}"
  data-enabled="{{enabled}}"
  data-color="{{primaryColor}}"
></div>
<script>
  const config = document.getElementById("script-config");
  const apiKey = config.getAttribute("data-api-key");
  const enabled = config.getAttribute("data-enabled") === "true";
  const color = config.getAttribute("data-color");

  if (enabled && apiKey) {
    // Initialize with configuration
  }
</script>

パターン 2 - dataset プロパティの使用：

<div
  id="script-config"
  data-headline="{{headline}}"
  data-message="{{message}}"
  data-image-url="{{imageUrl}}"
></div>
<script>
  const config = document.getElementById("script-config");
  const { headline, message, imageUrl } = config.dataset;

  // Use the variables in your script logic
  if (headline) {
    document.querySelector("#headline").textContent = headline;
  }
</script>

パターン 3 - 条件分岐：

<div
  id="config"
  data-mode="{{activationMode}}"
  data-start="{{startDate}}"
  data-end="{{endDate}}"
></div>
<script>
  const config = document.getElementById("config");
  const mode = config.getAttribute("data-mode");

  if (mode === "timed") {
    const startDate = new Date(config.getAttribute("data-start"));
    const endDate = new Date(config.getAttribute("data-end"));
    const now = new Date();

    if (now >= startDate && now <= endDate) {
      // Show content
    }
  } else if (mode === "active") {
    // Show content immediately
  }
</script>

検証要件：

• 特定のユースケースに関連する動的パラメーターのみを使用してください
• 実装する機能に関係のないパラメーターは無視してください
• テンプレート変数 {{parameterKey}} は、パラメーター定義のキー名と完全に一致する必要があります
• 必須パラメーターと任意のパラメーターを適切に処理してください
• 任意のパラメーターが設定されていない場合に、妥当なデフォルトの動作を指定してください
• 型に適した方法で使用してください（NUMBER 型のパラメーターを変換せずに文字列として使用しないでください）

共通パラメーター

すべての埋め込みスクリプトには、最低限、有効／無効の切り替えパラメーターが必要です。

パラメーター	型	用途
enabled	BOOLEAN	サイト所有者が有効／無効を切り替える
apiKey	TEXT	サードパーティサービスの認証情報
trackingId	TEXT	分析／ピクセルの識別子
headline	TEXT	カスタマイズ可能な表示テキスト
color	COLOR	UI のカスタマイズ

出力構成

完全な埋め込みスクリプトの実装には、2 つの部分が必要です。

1. 埋め込みスクリプト拡張機能

src/extensions/site/embedded-scripts/
└── {script-name}/
    ├── embedded.html     # HTML/JavaScript code to inject
    └── extensions.ts     # Metadata (scriptType, placement)

2. ダッシュボード設定ページ（必須）

src/extensions/dashboard/
├── withProviders.tsx     # WDS provider wrapper (required)
└── pages/
    └── {script-name}-settings/
        ├── extensions.ts  # Extension registration (REQUIRED)
        └── page.tsx       # Configuration UI using embeddedScripts API

注： ダッシュボードページには、専用の extensions.ts ファイルが必要です。このファイルがないと、ダッシュボードページは Wix ダッシュボードに表示されません。

警告： ダッシュボードページでは、埋め込みスクリプトとは異なるフィールド名を使用します。

• ダッシュボードページでは title、routePath、component を使用します
• 埋め込みスクリプトでは name、source、placement、scriptType を使用します

ダッシュボードページの登録に埋め込みスクリプトのフィールド名を使用しないでください。

ダッシュボードページの実装の詳細と拡張機能の登録パターンについては、wix-cli-dashboard-page スキルを参照してください。

実装パターン

<div id="my-config" data-api-key="{{apiKey}}" data-enabled="{{enabled}}"></div>


<div id="my-container"></div>

<style>
  /* Scoped styles for the embedded content */
  #my-container {
    /* styles */
  }
</style>

<script type="module">
  // Get configuration from data attributes
  const config = document.getElementById("my-config");
  if (!config) throw new Error("Config element not found");

  const { apiKey, enabled } = config.dataset;

  // Exit early if disabled (use throw at module scope, not return)
  if (enabled !== "true") {
    throw new Error("Script disabled");
  }

  // Implement functionality in a named function (return is allowed here)
  async function initialize() {
    try {
      // Your implementation
    } catch (error) {
      console.error("Script error:", error);
    }
  }

  // Initialize when DOM is ready
  if (document.readyState === "loading") {
    document.addEventListener("DOMContentLoaded", initialize);
  } else {
    initialize();
  }
</script>

例

分析トラッキング

リクエスト：「サイトに Google Analytics のトラッキングを追加してください」

出力：

• スクリプトタイプ：ANALYTICS
• 配置場所：HEAD
• テンプレート変数：{{trackingId}}
• 実装内容：gtag.js の初期化、ページビューのトラッキング

ポップアップ／モーダル

リクエスト：「カートの金額が $50 を超えたときに表示されるクーポンのポップアップを作成してください」

出力：

• スクリプトタイプ：FUNCTIONAL
• 配置場所：BODY_END
• テンプレート変数：{{couponCode}}、{{minimumCartValue}}、{{enablePopup}}
• 実装内容：カート金額の検出、ポップアップの表示ロジック、「今後表示しない」を実現する localStorage の使用

サードパーティーのチャットウィジェット

リクエスト：「Intercom のチャットウィジェットを統合してください」

出力：

• スクリプトタイプ：FUNCTIONAL
• 配置場所：BODY_END
• テンプレート変数：{{appId}}、{{userEmail}}、{{userName}}
• 実装内容：Intercom SDK の初期化、ユーザーの識別

ベストプラクティス

• 必ずダッシュボードページを作成する： 埋め込みスクリプトにはすべて、設定用 UI が必要です
• 有効／無効の切り替えを含める： スクリプトを削除せずに、サイト所有者が有効化を制御できるようにします
• パフォーマンス： 影響を最小限に抑えます。スクリプトは軽量で、読み込みを妨げないようにします
• セキュリティ： インラインイベントハンドラーを避け、データを検証し、ユーザー入力をエスケープします
• エラー処理： 適切な場合はエラーを無視し、サイトの動作を妨げないようにします
• モジュールスコープでの早期終了： モジュールスコープで早期終了する場合は、return ではなく throw new Error() を使用します。Astro が使用する Rollup では、モジュールスコープの return 文は使用できません。return が有効な名前付き async 関数で、メインのロジックを囲みます
• 型変換： パラメーターは常に文字列です。必要に応じて JavaScript で変換します
• API 呼び出し： API 仕様に存在する /api/* エンドポイントにのみ fetch() 呼び出しを作成します
• スコープ設定： サイトのスタイルとの競合を避けるため、CSS クラスと ID にプレフィックスを付けます
• クリーンアップ： 適切な場合は、イベントリスナーとインターバルを削除します

完全な例：クーポンのポップアップ

1. パラメーターを定義する

Parameters for "cart-coupon-popup":
- couponCode (TEXT, required) - The coupon code to display
- popupHeadline (TEXT, required) - Headline text
- popupDescription (TEXT, required) - Description text
- minimumCartValue (NUMBER) - Minimum cart value to show popup
- enablePopup (BOOLEAN, required) - Enable/disable toggle

2. 埋め込みスクリプト（embedded.html）

<div
  id="popup-config"
  data-coupon-code="{{couponCode}}"
  data-popup-headline="{{popupHeadline}}"
  data-minimum-cart-value="{{minimumCartValue}}"
  data-enable-popup="{{enablePopup}}"
></div>
<div id="popup-container"></div>

<script type="module">
  // Get configuration from data attributes
  const config = document.getElementById("popup-config");
  if (!config) throw new Error("Config element not found");

  const { couponCode, popupHeadline, minimumCartValue, enablePopup } =
    config.dataset;

  // Exit early if disabled (use throw at module scope, not return)
  if (enablePopup !== "true") {
    throw new Error("Popup disabled");
  }

  // Main logic in a function (return is allowed here)
  async function initializePopup() {
    const minValue = Number(minimumCartValue) || 0;
    // ... popup implementation
  }

  // Initialize when DOM is ready
  if (document.readyState === "loading") {
    document.addEventListener("DOMContentLoaded", initializePopup);
  } else {
    initializePopup();
  }
</script>

3. ダッシュボードページ（wix-cli-dashboard-page スキルを参照）

@wix/app-management の embeddedScripts API を使用します：

import { embeddedScripts } from "@wix/app-management";

// Load parameters
const script = await embeddedScripts.getEmbeddedScript();
const params = script.parameters; // { couponCode: "...", ... }

// Save parameters (all values must be strings)
await embeddedScripts.embedScript({
  parameters: {
    couponCode: "SAVE20",
    minimumCartValue: "50", // Number as string
    enablePopup: "true", // Boolean as string
  },
});

拡張機能の登録

拡張機能の登録は必須で、2 つの手順が必要です。

手順 1：スクリプト専用の拡張機能ファイルを作成する

埋め込みスクリプトごとに、そのフォルダー内に extensions.ts ファイルが必要です。

import { extensions } from "@wix/astro/builders";

export const embeddedscriptMyScript = extensions.embeddedScript({
  id: "{{GENERATE_UUID}}",
  name: "My Script",
  source: "./extensions/site/embedded-scripts/my-script/embedded.html",
  placement: "BODY_END",
  scriptType: "FUNCTIONAL",
});

重要：UUID の生成

id は一意で固定の UUID v4 文字列である必要があります。拡張機能ごとに新しい UUID を生成してください。randomUUID() を使用したり、例から UUID をコピーしたりしないでください。{{GENERATE_UUID}} を、"a1b2c3d4-e5f6-7890-abcd-ef1234567890" のような新しく生成した UUID に置き換えます。

プロパティ	型	説明
id	string	一意で固定の UUID v4（新しく生成）
name	string	スクリプトの表示名
source	string	HTML ファイルへの相対パス
placement	enum	HEAD、BODY_START、または BODY_END
scriptType	enum	ESSENTIAL、FUNCTIONAL、ANALYTICS、ADVERTISING

手順 2：メインの拡張機能ファイルに登録する

重要： スクリプト専用の拡張機能ファイルを作成したら、必ず wix-cli-extension-registration を読み、「App Registration」セクションに従って src/extensions.ts を更新してください。

手順 2 を完了しないと、埋め込みスクリプトはサイトにデプロイされません。

埋め込みスクリプトの権限を有効にする

実装後、アプリの開発者は埋め込みスクリプトの権限を手動で有効にする必要があります。

1. https://manage.wix.com/apps/{app-id}/dev-center-permissions にアクセスします（{app-id} を実際のアプリ ID に置き換えてください）
2. SCOPE.DC-APPS.MANAGE-EMBEDDED-SCRIPTS 権限を追加します
3. 変更を保存します

注： これは Wix Dev Center で手動で行う手順です。この権限がないと、サイトで埋め込みスクリプトは機能しません。