# Engage Studio — Web Message Previewer

**Engage Studio — Web Message Previewer**は、マーケターが実際のWebサイト上で直接操作して以下を行うためのオーサリング補助ツールです。

1. **ターゲット要素の選択** — ページ上の任意の要素をクリックして、Inlineキャンペーン用の安定したCSSセレクター（Zone ID）を自動生成します。
2. **キャンペーンコンテンツのプレビュー** — 差し替え用HTMLが実際のページ上でどのようにレンダリングされるか、公開前に確認します。


オーサリング補助ツールについて
Chrome Extensionはオーサリング用のツールであり、**キャンペーンの配信アーキテクチャには含まれません**。キャンペーンはTD Web SDKを通じてエンドユーザーへ配信されており、SDKはExtensionとは独立して動作します。Extensionをインストールできないマーケターも、ブラウザのDevToolsを使用してCSSセレクターを手動入力することでキャンペーンを作成・配信できます。

## 動作要件

- Google Chrome（バージョン114以降）
- Treasure AIアカウントでEngage Studioへのアクセス権
- ターゲットWebサイトがブラウザからアクセス可能であること（ExtensionはHTTP/HTTPSページであれば、すでにログイン済みの認証ページを含むすべてのページで動作します）


## Extensionのインストール

ExtensionはChrome Web Storeで公開されています。Chrome Web Storeで **"Engage Studio — Web Message Previewer"** by Treasure AI を検索するか、カスタマーサクセス担当に直接リンクをお問い合わせください。

1. Chrome Web Storeで **Engage Studio — Web Message Previewer** のページを開きます。
2. **Chromeに追加**をクリックし、ダイアログで**拡張機能を追加**を確認してクリックします。
3. 拡張機能一覧に **Engage Studio — Web Message Previewer** がTreasure AIアイコンとともに表示されます。


Extensionのピン留め
Chromeツールバーのパズルピースアイコン（拡張機能）をクリックして、Engage Studio Extensionをピン留めすると素早くアクセスできます。

## Extensionを開く

1. In-Browser Messageを設定またはプレビューしたいWebサイトのページに移動します。
2. Chromeツールバーのアイコン（Treasure AI）をクリックします。
3. ブラウザウィンドウの右側に**サイドパネル**が開きます。


制限のあるページ
ExtensionはChromeのシステムページ（`chrome://…`）、Chrome Web Store、ブラウザ拡張機能のページでは動作しません。通常のHTTP/HTTPSのWebサイトに移動してから使用してください。

## Extension UIの概要

サイドパネルには2つのタブがあります。

- **1 Select** — ページ上のDOM要素を選択し、差し替えるHTMLを編集します。
- **2 Preview** — 差し替え用HTMLをページに注入し、Original（元の表示）とModified（差し替え後の表示）を比較します。


Engage Studio Chrome ExtensionのサイドパネルのPreviewタブ。CSS Selector、Replacement HTMLフィールド、Compare Versionsトグルが表示されている。
## ステップ1：Select — ターゲット要素の特定

**Select**タブで、差し替えたいDOM要素を選択してCSSセレクターを生成します。

1. サイドパネルで **Select Element** をクリックしてセレクターモードに入ります。
2. ページ上でカーソルを移動します。要素が青いボーダーでハイライトされ、生成されたCSSセレクターがツールチップで表示されます。
3. ターゲットにしたい要素をクリックします。サイドパネルに以下が入力されます。
  - **CSS Selector** — 自動生成されたセレクター（例：`div[data-src="drDpRe"] > div:nth-of-type(2) > div`）。フィールド下部にページ上でのマッチ数が表示されます。
  - **Replacement HTML** — 注入するHTMLコンテンツを入力する編集可能フィールド。
4. **Replacement HTML** を必要に応じて編集します。
5. **CSS Selector** および **Replacement HTML** フィールドの横にあるコピーボタンを使って各値をコピーし、Engage StudioのIn-Browser Messageエディターに貼り付けます。


別の要素を選び直すには **Reselect Element** をクリックします。
要素を選択せずにキャンセルするには **Escape** キーを押します。

### セレクターの生成ロジック

Extensionはターゲット要素とその親要素を分析して、**安定したCSSセレクター**（ページ更新後も壊れにくいセレクター）を生成します。生成の優先順位は以下のとおりです。

1. **`id`属性** — 自動生成またはUUID的な値でない場合（例：`#product-banner-area`）
2. **`data-*`テスト属性** — `data-testid`、`data-qa`、`data-cy`など
3. **安定した`data-*`属性** — ハッシュやセッショントークンに見えない値を持つその他の`data-*`属性
4. **クラス名** — 動的に生成されたクラス名（CSS-in-JS、ハッシュサフィックス）を除外してフィルタリング
5. **構造的パス** — 最も近い安定した祖先要素からの`tag > tag:nth-of-type(n)`パス


動的クラス名について
ページがCSS-in-JSライブラリ（styled-components、Emotionなど）を使用している場合、自動生成されたクラス名は自動的に除外されます。このような場合、より正確なセレクターを得るために、ターゲット要素に安定した`data-testid`または`id`属性を追加してください。

## ステップ2：Preview — レンダリングの確認

**Preview**タブで、差し替え用HTMLを実際のページに注入してレンダリングを確認します。

1. サイドパネルで **Preview** タブに切り替えます。
2. **Preview Mode Active**（緑のバナー）が表示されると、差し替え用HTMLがページに注入されています。
3. **Compare Versions** トグルで以下を切り替えて確認します。
  - **Original** — 通常のページ表示。
  - **Modified** — 差し替え用HTMLが注入されたページ表示。
4. ページ上でレンダリング結果を確認します。
5. 注入したコンテンツを削除するには、ページを再読み込み（`Cmd/Ctrl + R`）するか、ページを離れます。


プレビューはローカルのみ
Extensionはあなたのブラウザセッション内にのみコンテンツを注入します。実際のWebサイトやEngage Studioのキャンペーン設定には一切変更は加えられません。エンドユーザーへの影響もありません。

## トラブルシューティング

| **問題**  | **対処法**  |
|  --- | --- |
| サイドパネルに「このページでは拡張機能を使用できません」と表示される | 通常のHTTP/HTTPSのWebサイトに移動してください。`chrome://`、`chrome-extension://`、view-source:、devtools://、Chrome Web Storeのページでは動作しません。 |
| アイコンをクリックしてもサイドパネルが開かない | `chrome://extensions` でExtensionが有効になっているか確認してください。一度無効にしてから再度有効化し、ページを再読み込みしてみてください。 |
| サイドパネルに「The previewer has not been loaded on this page. Reload the page (Cmd/Ctrl+R) and try again.」というエラーが表示される | コンテンツスクリプトが現在のタブで読み込まれていない可能性があります。`Cmd/Ctrl + R`でページを再読み込みしてからサイドパネルを再度開いてください。 |
| 要素セレクターが何もハイライトしない | ページがShadow DOMやクロスオリジンのiframeを使用している可能性があります。この場合は、シャドウルートの外側にあるラッパーコンテナ要素を選択してください。 |
| CSSセレクターが複数の要素にマッチする（マッチ数 > 1） | その要素に安定した`id`または`data-*`属性がありません。より正確なセレクターを得るために、開発者にターゲット要素へ`data-testid`属性を追加するよう依頼してください。 |
| プレビューコンテンツが注入直後に消える | ページ上のJavaScriptフレームワークがDOMを再レンダリングしている可能性があります。フレームワークが管理していないコンテナ要素を選択するか、開発者に安定した挿入ポイントの追加を依頼してください。 |


## 既知の制限事項

- ブラウザウィンドウあたりアクティブなサイドパネルは1つのみサポートされています。
- ExtensionはChromeのSide Panel API（Chrome 114以降）を使用しています。古いChromiumベースのブラウザでは動作しない場合があります。
- デバイス管理（MDM）ポリシーによって拡張機能のインストールが制限されている組織では、ブラウザのDevToolsを使用したCSSセレクターの手動入力を代替手段として使用してください。