service-digital-engagement-messaging-site-integrate

Experience Cloud サイトにメッセージングウィジェットを埋め込む

既存の Embedded Messaging（MIAW）デプロイメントを Experience Cloud サイトに接続します。サイトのバンドル（LWR の DigitalExperienceBundle または Aura の ExperienceBundle）を取得し、ホームページの JSON を修正して experience_messaging:embeddedMessaging コンポーネントを配置し、バンドルをローカルプロジェクトにステージングしてデプロイし、サイトを公開した後、ゲストアクセスを確認します。

この操作は冪等です。コンポーネントがすでに存在する場合はその場で更新されます（id は保持されるため）。異なる ESD 座標を指定して再実行すると、問題なく更新されます。

範囲

• 対象範囲：LWR と Aura のバンドルタイプの検出、サイトテンプレートに必要な LWR テンプレートルートの不足分の生成（例：too-many-requests）、すべての sfdc_cms__themeLayout/*/content.json ファイルを修正してフッター領域に Embedded Messaging コンポーネントを挿入または更新（サイト全体への配置）、バンドルの force-app へのステージング、ポーリングを伴う非同期デプロイ、Network.Name の解決とサイトの公開、ゲスト URL のスモークテスト、ディープリンクを使った Experience Builder での手動代替手順。
• 対象外：EmbeddedServiceConfig（Embedded Service Deployment）自体の作成 — service-digital-engagement-deployment-configure を使用します。MessagingChannel の作成 — service-digital-engagement-channel-configure を使用します。Experience Cloud サイト自体の作成 — experience-lwr-site-generate を使用します。Experience Cloud 以外のウェブサイト用のスタンドアロン JS スニペットの生成。

---

確認事項

実行前に、まだ明確でない場合はユーザーに確認してください。

• サイト名は何ですか？ Experience Cloud サイトの DeveloperName です（digitalExperiences/site/<siteName>/ または experiences/<siteName>/ 配下のメタデータフォルダー名）。
• デプロイメントの座標は何ですか？ deploymentName（Embedded Service Deployment の DeveloperName）、scrtUrl、siteEndpoint（Experience サイトのベース URL）です。3 つとも公開済みの EmbeddedServiceConfig から取得できます。提供されていない場合は、service-digital-engagement-deployment-configure の出力から取得してください。
• 対象組織のエイリアスは何ですか？ sf コマンド用です。
• URL パスプレフィックスは何ですか？ サイトの UrlPathPrefix です（公開時の Network.Name の解決と、検証用のゲスト URL へのアクセスに必要です）。

---

必須入力

作業を進める前に、以下を収集するか推定してください。

• サイト名 — サイトの DeveloperName
• デプロイメント名 — EmbeddedServiceConfig の DeveloperName
• scrtUrl — デプロイメントの SCRT2 エンドポイント URL
• siteEndpoint — Experience サイトのベース URL
• 対象組織のエイリアス
• URL パスプレフィックス — サイトの公開 URL のパスセグメント（例：esw-site）

書き込み時にコンポーネントの属性に適用されるデフォルト値：

• isExpSiteAuthMode：false
• hideChatButtonOnLoad："Default"
• clientVersion："WebV1"

---

ワークフロー

手順は順番に実行します。自動化された手順のいずれかに失敗した場合は、手動の代替手順（フェーズ 6）に進み、ゲスト URL のスモークテストが 200 を返すか、ユーザーが手動での公開を確認するまでは、ウィジェットが「稼働中」とは主張しないでください。

フェーズ 1 — バンドルタイプの検出

1. 候補となる両方のバンドルを <retrieve-dir> に取得します。 スクリプトは決定的なパスチェックのみを行うため、先に取得コマンドを実行する必要があります。

   sf project retrieve start --metadata "DigitalExperienceBundle:site/<siteName>" \
     --target-org <org-alias> --target-metadata-dir <retrieve-dir>
   sf project retrieve start --metadata "ExperienceBundle:<siteName>" \
     --target-org <org-alias> --target-metadata-dir <retrieve-dir>
   

   どちらのコマンドも「メタデータが見つからない」を返す場合がありますが、これは想定内です。不足しているバンドルは、サイトがもう一方のタイプであることを意味します。

2. scripts/detect_bundle_type.sh <retrieve-dir> <siteName> を実行します。 標準出力には、次のトークンが 1 つだけ出力されます。

   • LWR → LWR マーカーファイルが存在します（digitalExperiences/site/<siteName>/sfdc_cms__view/home/content.json）。フェーズ 2 に進みます。
   • AURA → Aura マーカーファイルが存在します（experiences/<siteName>/views/homeGuestLayout.json）。フェーズ 3 に進みます。
   • UNKNOWN（終了コード 1）→ どちらのマーカーも存在しません。フェーズ 6 の手動の代替手順に進みます。

取得コマンドの形式とトラブルシューティングについては、references/bundle_detection.md を参照してください。

フェーズ 2 — LWR バンドルにパッチを適用する

3. パッチを適用する前に、不足している LWR テンプレートルート（一般的には too-many-requests）をスキャフォールドします。ルートが不足しているとデプロイに失敗します。ルートとビューのスキャフォールドは experience-lwr-site-generate が担当します（configure-content-route.md、configure-content-view.md、handle-component-and-region-ids.md を参照）。実際のスキャフォールドはそのスキルに委任してください。このスキルでは、メッセージング固有のコンテキスト（デプロイで問題として報告されているルートと、スキャフォールドされたペアによってその特定のデプロイエラーが解消されることの確認）のみを提供します。委任先については references/lwr_route_scaffolding.md を参照してください。

4. すべての themeLayout ファイルにパッチを適用します。次を実行してください。

   scripts/patch_lwr_bundle.sh \
     <retrieve-dir>/digitalExperiences/site/<siteName> \
     <deploymentName> <scrtUrl> <siteEndpoint>
   

   このスクリプトは、すべての sfdc_cms__themeLayout/*/content.json ファイルを反復処理します。各ファイルで、.contentBody.component.children[] にある footer リージョンを特定し、既存の community_layout:section ラッパー内のスロットリージョンをたどって、既存の experience_messaging:embeddedMessaging コンポーネントがあればその場で更新（id を保持）し、なければ新しいコンポーネントノードを追加します。themeLayout のフッターを対象にすることで、Aura の themeFooter への配置と同様に、ウィジェットをサイト内のすべてのページに表示されるフローティングオーバーレイとして配置します。JSON の形式と確認方法については references/lwr_patch.md を参照してください。

5. フェーズ 4 に進みます。

フェーズ 3 — Aura バンドルにパッチを適用する

6. ホームのゲストレイアウトにパッチを適用します。次を実行してください。

   scripts/patch_aura_bundle.sh \
     <retrieve-dir>/experiences/<siteName>/views/homeGuestLayout.json \
     <deploymentName> <scrtUrl> <siteEndpoint>
   

   このスクリプトは .regions[] を反復処理し、.components[] が空でない最初のリージョンを選択して、forceCommunity:section ラッパーがあれば再帰的にたどります。既存の .componentName == "experience_messaging:embeddedMessaging" コンポーネントがあればその場で更新（id を保持）し、なければ新しい forceCommunity:section ラッパーを追加します。Aura では definition / attributes ではなく componentName / componentAttributes を使用し、dxpStyle はありません。JSON の形式と確認手順については references/aura_patch.md を参照してください。

7. フェーズ 4 に進みます。

フェーズ 4 — ステージングとデプロイ

8. 変更したバンドルをプロジェクトのデフォルトパッケージにコピーします。変更していないファイルも含めてコピーするため、cp -R を使用してください。

   • LWR：cp -R <retrieve-dir>/digitalExperiences force-app/main/default/
   • Aura：cp -R <retrieve-dir>/experiences force-app/main/default/ に加えて、隣接する <siteName>.site-meta.xml ファイルもコピーします。これがないと Aura のデプロイは拒否されます。

9. 非同期でデプロイし、状況をポーリングします。

   sf project deploy start --source-dir force-app/main/default \
     --target-org <org-alias> --async
   

   10 分間、15 秒ごとにポーリングします。

   sf project deploy report --job-id <job-id> --target-org <org-alias>
   

   ステータスが Succeeded、Failed、SucceededPartial、または Canceled になったら停止します。失敗した場合は、デプロイレポートを提示し、公開には進まないでください。ポーリングの全手順と一般的な失敗原因については references/deploy_and_publish.md を参照してください。

フェーズ 5 — 公開と確認

10. Network.Name を解決します。Network.Name はサイトの DeveloperName と異なることがよくあります。そのため、推測せずに URL パスのプレフィックスでクエリします。

    sf data query --query \
      "SELECT Name FROM Network WHERE UrlPathPrefix='<urlPath>' LIMIT 1" \
      --target-org <org-alias>
    

11. 解決した名前を使用してコミュニティを公開します。

    sf community publish --name "<resolved-Name>" --target-org <org-alias>
    

12. 公開 URL にアクセスして、ゲストアクセスをスモークテストします。

    curl -sL -o /dev/null -w "%{http_code}" \
      https://<domainHostname>/<urlPath>
    

    応答が 200 の場合にのみ、成功と報告してください。

フェーズ 6 — 手動フォールバック

13. 自動処理のいずれかのステップが失敗した場合（バンドルを検出できない、パッチの書き込みがブロックされる、デプロイに失敗する、公開に失敗する、またはゲスト URL が 200 ではない場合）は、Experience Builder のディープリンクと、references/manual_fallback.md に記載された手順を一字一句そのまま表示してください。ユーザーが確認するまで、ウィジェットが公開されていると主張してはいけません。

    ディープリンクは次のとおりです。

    https://<MyDomain>.lightning.force.com/sfsites/picasso/core/config/commeditor.apexp?...networkId=<Network.Id>
    

    sf org display --target-org <org-alias> で <MyDomain> を解決し、次のコマンドで <Network.Id> を解決します。

    sf data query --query \
      "SELECT Id FROM Network WHERE UrlPathPrefix='<urlPath>' LIMIT 1" \
      --target-org <org-alias>
    

    どちらの値もハードコードしてはいけません。 Experience Builder を開き、Embedded Messaging コンポーネントを対象ページにドラッグし、プロパティパネルからデプロイを選択して、［公開］をクリックするようユーザーに案内してください。

---

ルール／制約

制約	理由
取得結果からバンドルの種類を検出し、決めつけない	LWR サイトと Aura サイトでは、異なるキー名を使って異なるファイルにパッチを適用する必要があります
既存コンポーネントをインプレースで更新する場合は、既存の id を保持する	冪等性を確保します。Experience ランタイムは id を基準に処理します
新しい id はすべて新しい UUID にする	ID が重複するとレイアウトが破損し、レンダリングに失敗することがあります
LWR では definition／attributes、Aura では componentName／componentAttributes を使用する	誤ったキー名を使うと、コンポーネントはエラーなしでレンダリングから除外されます
LWR の community_layout:section の sectionConfig は、.attributes 内に JSON 文字列として配置する（トップレベルのプロパティでも、ネストされたオブジェクトでもない）	トップレベルに配置すると、スキーマの additionalProperties: false 制約に違反します。また、シリアライザーはオブジェクトではなく文字列を想定しています
Aura の同階層にある <siteName>.site-meta.xml をバンドルとともにコピーする	これがないとデプロイは拒否されます
非同期デプロイの完了をポーリングする。完了を待たずに処理を進めない	公開はデプロイの成功後にのみ実行する必要があります
DeveloperName を再利用せず、UrlPathPrefix から Network.Name を解決する	これらの値は異なることがよくあります
ゲスト URL が 200 を返すか、ユーザーが確認するまで、「サイトで公開済み」と主張しない	公開は非同期です。成功を早まって報告すると、誤解を招きます
手動フォールバックのリンクに MyDomain または Network.Id をハードコードしない	値は組織ごとに異なるため、クエリで取得する必要があります
冪等性：新しい ESD 座標で再実行した場合はインプレースで更新する	ユーザーは設定中に deploymentName、scrtUrl、siteEndpoint を繰り返し変更します

---

注意事項

問題	解決方法
LWR デプロイ中に too-many-requests ルートが見つからない	references/lwr_route_scaffolding.md に従って、不足しているルートとビューのペアを作成します
Aura デプロイがサイトメタデータ不足で拒否される	取得ディレクトリから同階層の <siteName>.site-meta.xml をコピーします
コンポーネントは追加されたがレンダリングされない	リージョンラッパーで正しい type: "region" キーを使用していること、および Aura コンポーネントで componentName（definition ではない）を使用していることを確認します
sf community publish が "community not found" で失敗する	Network.Name はサイトの DeveloperName と異なります。UrlPathPrefix のクエリで解決します
公開後、ゲスト URL が 403 または 503 を返す	公開は非同期です。手動フォールバックに切り替える前に、60 秒後にスモークテストを再試行します
再実行すると 2 つ目のメッセージングコンポーネントが追加される	再帰検索で誤ったキー名に一致しています。コンポーネントの検出には definition（LWR）または componentName（Aura）を使用する必要があります
デプロイは成功したが、ウィジェットがすべてのページに表示されない	LWR の場合、コンポーネントが sfdc_cms__view/home/content.json（ページ固有）ではなく、sfdc_cms__themeLayout/*/content.json のフッターに挿入されていることを確認します。Aura の場合は、homeGuestLayout.json（themeFooter リージョン）にパッチが適用されていることを確認します。
sectionConfig がオブジェクトとして書き込まれる	JSON 文字列としてシリアライズします。CMS パーサーはオブジェクトを受け付けません

---

検証チェックリスト

バンドルの検出

• sfdc_cms__view/home/content.json（LWR）またはviews/homeGuestLayout.json（Aura）のどちらか一方だけが見つかりましたか？
• どちらも見つからなかった場合、ワークフローは手動での代替手順に進みましたか？

パッチの正確性

• LWR の場合、メッセージングコンポーネントのキーはdefinitionとattributesですか？
• Aura の場合、キーはcomponentNameとcomponentAttributesですか？
• 既存のデータをその場で更新した場合、既存のidは保持されましたか？
• 追加した場合、新しいidの値はすべて未使用の UUID ですか？
• LWR の場合、スクリプトはすべてのsfdc_cms__themeLayout/*/content.jsonにパッチを適用しましたか（home/content.jsonだけではありませんか）？
• LWR の場合、各 themeLayout のfooterリージョンのサブツリー内にメッセージングノードがありますか？
• LWR の場合、メッセージングノードの属性でclientVersionは"WebV2"に設定されていますか？

デプロイ

• Aura の場合、<siteName>.site-meta.xmlはバンドルと一緒にコピーされましたか？
• 非同期デプロイは、終端ステータスになるまでポーリングされましたか？
• 公開に進む前に、終端ステータスがSucceededまたはSucceededPartialになりましたか？

公開

• Network.Nameは、サイトのDeveloperNameを再利用せず、UrlPathPrefixを使って解決されましたか？
• sf community publishはエラーなく完了しましたか？

検証

• ゲスト URL への curl は200を返しましたか？
• 200が確認されるか、ユーザーが手動で公開したことを確認するまで、ワークフローは成功を宣言しませんでしたか？

---

出力要件

成果物：

• 変更済みのsfdc_cms__themeLayout/*/content.jsonファイル（themeLayout ごとに 1 つ）を取得ディレクトリとforce-app/main/default/...（LWR）の両方に配置、または変更済みのhomeGuestLayout.json（Aura）
• （LWR のみ、必要な場合）スキャフォールディングで作成した不足ルート用のsfdc_cms__route/<RouteApiName>/とsfdc_cms__view/<viewId>/のペア
• デプロイのjob-idと最終デプロイレポート
• 公開の確認
• ゲスト URL のスモークテスト HTTP ステータス
• 失敗時：Experience Builder のディープリンクと手動での操作手順

EmbeddedServiceConfigまたはMessagingChannelメタデータは作成しないでください。これらは、以下のデプロイおよびチャネルのスキルが担当します。

---

スキル間の連携

必要な作業	委任先
Embedded Service Deployment の作成または更新	service-digital-engagement-deployment-configure
基盤となる MIAW メッセージングチャネルの作成	service-digital-engagement-channel-configure
Experience Cloud LWR サイト自体の作成	experience-lwr-site-generate
不足している LWR ルートとビューのペアのスキャフォールディング（例：too-many-requests）	experience-lwr-site-generate（ルート／ビューの作成、ID の処理）

---

参照ファイル一覧

ファイル	読むタイミング
references/bundle_detection.md	フェーズ 1 — LWR と Aura の取得および判別
references/lwr_route_scaffolding.md	フェーズ 2 — 不足している LWR テンプレートルートのスキャフォールディングを委任する際に参照（experience-lwr-site-generateが担当）
references/lwr_patch.md	フェーズ 2 — patch_lwr_bundle.shの処理内容と出力の検証方法
references/aura_patch.md	フェーズ 3 — patch_aura_bundle.shの処理内容と出力の検証方法
references/deploy_and_publish.md	フェーズ 4～5 — force-appへのステージング、非同期デプロイのポーリング、公開、ゲスト URL のスモークテスト
references/manual_fallback.md	フェーズ 6 — Experience Builder のディープリンクと、ドラッグ、ドロップ、公開の手動手順
scripts/detect_bundle_type.sh	フェーズ 1 — 取得したバンドル内の LWR／Aura／UNKNOWN を確定的に検出
scripts/patch_lwr_bundle.sh	フェーズ 2 — 冪等性のある LWR content.jsonへのパッチ適用（挿入またはその場で更新）
scripts/patch_aura_bundle.sh	フェーズ 3 — 冪等性のある Aura homeGuestLayout.jsonへのパッチ適用（挿入またはその場で更新）