Storefront Preview

Storefront Preview (ストアフロントプレビュー) を使用すると、指定したソースコード、顧客グループ、特定の日時などのコンテキストに基づいて、Progressive Web App (PWA) Kit サイトがどのように表示されるかを確認できます。たとえば、次回のセール中にサイトがどのように表示されるかをプレビューする場合は、この機能を使用できます。

ブラックフライデーやサイバーマンデーなどのセールが近づいている場合に、ステージング環境でサイトの変更をプレビューします。次に、商品、価格設定、マーケティング戦略などの変更が期待どおりに機能することを確認してから、変更を Production (本番) 環境にデプロイします。

また、Storefront Preview をサードパーティのコンテンツ管理システム (CMS) と統合できます。たとえば、CMS で管理しているホリデーセールのバナーがあるとします。有効日時などの現在のコンテキストを CMS に認識させることで、サイトのプレビューに、指定した期間のホリデーセールのバナーなど、正しいコンテンツを表示することができます。

Storefront Preview は Runtime Admin で使用できます。このガイドでは、Storefront Preview の設定、使用、トラブルシューティングの方法について説明します。

Storefront Preview を使用するには、まず次の操作を行う必要があります。

  • PWA Kit のバージョン 2.8.3 以降、あるいは 3.2.x と @salesforce/commerce-sdk-react@1.4.0 または@salesforce/retail-react-app@2.4.0 を使用してサイトを構築します。Storefront Preview は、2.8.3 または 3.2.x より前のバージョンの PWA Kit では使用できません。現在のメジャーバージョンに応じて、PWA Kit 2.8.3 または 3.2.x を使用するようにプロジェクトをアップグレードします。
  • Runtime Admin で読み取り専用以外の任意の役割でプロジェクトにアクセスできる必要があります。アクセス権がない場合は、Managed Runtime (MRT) 管理者役割のユーザーに支援を依頼してください。
  • Business Manager で買い物客のコンテキストを有効にします。
  • Storefront Preview で検証する機能に基づいてサイトを設定します。以下に例を示します。
    • Business Manager で顧客グループを使用してカスタム限定子と顧客グループ ID を設定し、パーソナライズされた価格設定、商品、またはプロモーションにルールを適用します。
    • パーソナライズされた買い物客の体験を表示するには、買い物客のコンテキストのエンドポイントを呼び出すソースコードを設定します。Storefront Preview はパーソナライゼーションにコンテキスト情報を使用するため、この操作が必要です。
    • 特定の日付に提供する価格を設定します。これにより、Storefront Preview でその日付を選択したときに、指定した価格設定が表示されます。
  • Storefront Preview の構成セクションで説明されている構成手順に従います。
  • https://runtime.commercecloud.com でサードパーティの Cookie を許可するようにブラウザーを設定します。

オプションで、Storefront Preview をサードパーティの CMS と統合する場合に関数を記述できます。ストアフロントへの StorefrontPreview コンポーネントの追加およびサードパーティ CMS との統合を参照してください。

サードパーティの CMS と統合するために記述する関数は非同期である必要があります。これにより、サイトをプレビューするときに予期しない結果を回避できます。

Storefront Preview は、最新バージョンの Chrome または Safari で使用できます。お使いのブラウザーは https://runtime.commercecloud.com がサードパーティの Cookie にアクセスできるようにする 必要があります。サードパーティーの Cookie を有効にしないと、Storefront Preview は 機能しません。

詳しくは、Chrome と Safari でサードパーティの Cookie を有効にする方法をご覧ください。
  • Storefront Preview に表示されるデータや体験は、必ずしも買い物客の体験を反映しているわけではありません。買い物客のパーソナライゼーションでは、PWA Kit プロジェクト内で Shopper Context API を使用する必要があります。詳しくは、買い物客のコンテキストをご覧ください。
  • Storefront Preview に表示されるストアフロントページは、サイトのゲストユーザーにどのように表示されるかを表すものです。たとえば、ゲストユーザーは、商品またはマーケティングコンテンツ、価格設定、プロモーション、商品リスト、または商品表示ページを表示できます。アカウント情報や買い物カゴなど、ログインしているユーザーに表示されるコンテンツは表示されません。
  • Storefront Preview は PWA Kit ページで機能しますが、Storefront Reference Architecture (SFRA) ページでは機能しません。ただし、B2C Commerce の Storefront Toolkit サイトプレビューツールを使用して SFRA ページをプレビューすることはできます。

Storefront Preview を使用する各サイトで必要な、以下の 1 回限りの構成手順に従います。

ストアフロントで使用する B2C Commerce インスタンスに対し、スコープが sfcc.shopper-context.rw と sfcc.ts_ext_on_behalf_of の Shopper Login and API Access Service (SLAS) プライベートクライアントを作成する必要があります。Storefront Preview では、SLAS プライベートクライアントを使用してストアフロントのコンテキストを設定します。SLAS プライベートクライアントは、SLAS Admin UI を使用して簡単に作成できます。

Shopper API の認可ガイドの手順に従って、Storefront Preview を使用する各 B2C Commerce インスタンスに SLAS プライベートクライアントを作成します。

  • Which App Type will be used? (使用するアプリのタイプ) フィールドでアプリのタイプに BFF or Web App (BFF または Web アプリ) を選択して、プライベートクライアントを作成します。
  • Enter the shopper scopes (買い物客のスコープを入力) フィールドで、スコープを空白で区切って指定します: sfcc.shopper-context.rw sfcc.ts_ext_on_behalf_of

結果ページの上部に表示される自動生成されたクライアントシークレットとクライアント ID をコピーして、次の手順で使用できるようにします。

MRT 環境変数を作成するには、MRT API エンドポイント projects_target_env_var_partial_update を呼び出します。 $SLAS_PRIVATE_CLIENT_ID と $SLAS_PRIVATE_CLIENT_SECRET を、手順 1 でコピーした値に置き換えます。$CC_SHORT_CODE を Business Manager のショートコード構成値に置き換えます。また、Runtime Admin を使用して環境変数を管理することもできます。環境変数を参照してください。

この API を呼び出すと、現在デプロイされているバンドルが再デプロイされます。ストアフロントをプレビューする前に、再デプロイが完了するのを待つ必要があります。再デプロイが正常に完了すると、プロジェクトディレクトリの Deployed Bundle という見出しの下にバンドルが表示されます。

B2C Commerce インスタンスに接続されたストアフロントで Storefront Preview を使用するには、Business Manager 管理者または Business Manager ユーザーのいずれかの Account Manager ユーザー役割が必要です。これらの役割のいずれかに属しているかどうかを確認するには、Account Manager で自分の役割を確認します。

必要な役割のいずれにも属していない場合は、権限の付与の手順に従って、Account Manager ユーザーに役割を追加します。

  • この手順は、PWA Kit バージョン 2.8.0 および 3.2.0 のリリース前に生成されたプロジェクトにのみ必要です。
  • PWA Kit のどのバージョンでも、Storefront Preview をサードパーティの CMS と統合する場合は、onContextChange prop を StorefrontPreview コンポーネントに追加する必要があります。ストアフロントに StorefrontPreview コンポーネントをすでに追加している場合は、サードパーティ CMS とのインテグレーションを参照してください。

Runtime Admin とストアフロント間の通信を機能させるには、通信チャネルを確立します。これには、次の 2 つの手順が含まれます。

  • 通信を有効にするには、PWA Kit React SDK の StorefrontPreview コンポーネントをストアフロントでレンダリングします。StorefrontPreview コンポーネントは、Runtime Admin との通信を確立するスクリプトを挿入します。このスクリプトはストアフロントが Storefront Preview で実行されている場合にのみ読み込まれるため、ストアフロントのパフォーマンスには影響しません。
  • StorefrontPreview をレンダリングする場所では、現在の買い物客のアクセストークンを返す getToken prop を定義する必要があります。

オプションで、Storefront Preview をサードパーティ CMS と統合する場合は、StorefrontPreview コンポーネントに onContextChange prop を追加できます。サードパーティ CMS との統合を参照してください。以下の例では、onContextChange prop を追加し、handleContextChange という名前の非同期関数を渡します。handleContextChange 関数の console.log ステートメントを独自のロジックに置き換えて、コンテキストの変更に応答できます。特定の要件に基づいて handleContextChange 関数をカスタマイズします。この関数の newContext パラメーターに、更新されたコンテキスト情報が含まれます。

PWA Kit バージョン 2.8.x を使用している場合は、ストアフロントで次のコードを使用して通信チャネルを確立します。_app/index.jsx ファイルで IntlProvider コンポーネントの周囲に StorefrontPreview コンポーネントを追加します。

PWA Kit バージョン 3.2.x を使用している場合は、ストアフロントで次のコードを使用して通信チャネルを確立します。_app/index.jsx ファイルで IntlProvider コンポーネントの周囲に StorefrontPreview コンポーネントを追加します。

  • この手順は、PWA Kit バージョン 2.8.0 および 3.2.0 のリリース前に生成されたプロジェクトにのみ必要です。
  • バージョン 2.8.1 および 3.2.1 以降は、この手順は新しいプロジェクトで自動的に実行されます。
  • バージョン 2.8.0 または 3.2.0 を使用するプロジェクトでは、defaultPwaKitSecurityHeaders ミドルウェア PWA Kit 存在しないため、この手順は必要 ありません。

通信チャネルを有効にするには、ストアフロントで次の条件を満たす必要があります。

  • Runtime Admin (runtime.commercecloud.com) による iframe への埋め込みを許可し、
  • 手順 4 で説明したスクリプトを読み込んで実行できるようにします。

コンテンツセキュリティポリシー (CSP) の frame-ancestors、connect-src、script-src のディレクティブに https://runtime.commercecloud.com を追加して、通信チャネルを有効にします。これを自動的に処理するには、pwa-kit-runtime パッケージが提供する defaultPwaKitSecurityHeaders ミドルウェアをインポートして使用します。

すでに StorefrontPreview コンポーネントをストアフロントにすでに追加していて、サードパーティ CMS と統合する場合は、StorefrontPreview コンポーネントに onContextChange prop を追加します。サードパーティ CMS との統合を参照してください。

以下の例では、onContextChangeprop および handleContextChange という名前の非同期関数を追加します。handleContextChange 関数の console.log ステートメントを独自のロジックに置き換えて、コンテキストの変更に応答できます。特定の要件に基づいて handleContextChange 関数をカスタマイズします。この関数の newContext パラメーターに、更新されたコンテキスト情報が含まれます。

PWA Kit のバージョン 2.8.x を使用している場合は、次のコードを使用して onContextChange prop を _app/index.jsx ファイルに追加します。

PWA Kit のバージョン 3.2.x を使用している場合は、次のコードを使用して onContextChange prop を _app/index.jsx ファイルに追加します。

Storefront Preview を使用するには、次の手順に従います。

  1. ブラウザーで Runtime Admin を開き、Account Manager 認証情報を使用してログインします。

  2. プロジェクトの環境ページに移動し、サイトをプレビューする環境の横にある Preview Site (サイトのプレビュー) をクリックします。

    ストアフロントを表示する新しいタブが開き、左側のサイドバーに Storefront Preview フォームが表示されます。

  3. (オプション) プレビューするコンテキストの有効日付と時刻を選択します。表示される日付と時刻は、お使いのコンピューターのタイムゾーンに基づいており、コンテキストを設定するリクエストを送信する前に UTC 時間に変換されます。日付と時刻を指定しない場合は、プレビューには現在の日付と時刻が反映されます。

  4. (オプション) プレビューしたいコンテキストのプロモーション (キャンペーンの割り当て) と (ソースコードグループに割り当てられている) 価格表をトリガーする ソースコード を入力します。

  5. (オプション) Business Manager で設定した 顧客グループ ID を入力します。各 ID はコンマで区切ります。

  6. (オプション) Business Manager で設定したパーソナライズされた価格、商品、またはプロモーションに適用する カスタム限定子 を入力します。カスタム限定子キーは一意である必要があります。最大 20 個のカスタム限定子を定義できます。

  7. Preview (プレビュー) をクリックします。

    これで、プレビューしたいコンテキストを使用してストアフロントを移動できます。

    共有しやすいように、ブラウザータブの URL が更新され、コンテキスト値が含まれるようになります。

場合によっては、プレビューされたストアフロントを操作して、予想される動作を確認する必要があります。たとえば、特定のサイズの衣料品をクリックすると、該当する割引価格が表示されます。

Storefront Preview で問題が発生した場合は、MRT 環境で Storefront Preview のログを有効にできます。 これにより、Preview (プレビュー) ボタンをクリックすると、問題のデバッグに役立つ追加のログが出力されます。

Storefront Preview のログを有効にするには、MRT 環境に MRT 環境変数STOREFRONT_PREVIEW_DEBUG=1を追加します。

MRT でのログのテールを使用して、Storefront Preview のログを読み取ることができます。

このセクションでは、Storefront Preview の使用中に発生する可能性のある一般的なエラーに対して推奨される解決策を提供します。

お使いのブラウザーによっては、サードパーティの Cookie が有効になっていない場合に異なる動作が発生する場合があります。

  • Chrome: 「Preview is not enabled on this storefront」(このストアフロントではプレビューが有効になっていません) というモーダルが表示され、ストアフロントに SecurityError が表示されます。
  • Safari: 「Failed to initialize Storefront Preview」(ストアフロントプレビューの初期化に失敗しました) というモーダルが表示され、ストアフロントは表示されません。

原因: お使いのブラウザーは、https://runtime.commercecloud.com でサードパーティの Cookie を許可していません。

推奨される解決策: ブラウザーの設定と、https://runtime.commercecloud.com でサードパーティの Cookie を許可するために使用する拡張機能を更新します。

Storefront Preview の読み込み時のエラーメッセージ: "Preview is not enabled on this storefront!" (このストアフロントではプレビューが有効になっていません)

原因: ストアフロントに、Runtime Admin との通信を可能にするスクリプトファイルがありません。

推奨される解決策: エラーメッセージウィンドウに表示される指示に従うか、上記の手順 4 の構成を完了します。

Preview (プレビュー) ボタンをクリックしたときのレスポンスエラーメッセージは以下のとおりです。

推奨される解決策: 上記の手順 1 と手順 2 の構成を完了します。

ブラウザーによっては、正しいコンテンツセキュリティポリシー (CSP) がない場合にエラーが発生する場合があります。

  • Chrome: 「Preview is not enabled on this storefront」(このストアフロントではプレビューが有効になっていません) というモーダルが表示され、ストアフロントに「refused to connect」(接続が拒否されました) というエラーページが表示されます。
  • Safari: 「Preview is not enabled on this storefront」(このストアフロントではプレビューが有効になっていません) というモーダルが表示され、ストアフロントは表示されません。

**原因:**ストアフロントのコンテンツセキュリティポリシーで Runtime Admin が許可されていません。

推奨される解決策: 上記のステップ 5 の指示に従って、コンテンツセキュリティポリシーを正しく構成します。

Storefront Preview によって読み込まれる最初のページは、環境の外部ホスト名として構成されたドメインです。

**原因:**外部ホスト名が環境設定で正しく構成されていません。

推奨される解決策:環境設定の 詳細 セクションで、正しいドメインを指すように外部ホスト名を構成します。

Preview (プレビュー) ボタンをクリックしたときのレスポンスエラーメッセージは以下のとおりです。

推奨される解決策: 上記の手順 3 を完了します。

Preview (プレビュー) ボタンをクリックしたときのレスポンスエラーメッセージは以下のとおりです。

原因: MRT 環境変数 SLAS_PRIVATE_CLIENT_ID と SLAS_PRIVATE_CLIENT_SECRET の値が正しくないか、SLAS プライベートクライアントの構成が間違っています。

推奨される解決策: 上記の手順 1 と手順 2 を完了します。

StorefrontPreview コンポーネントに onContextChange prop を追加した後でサイトをプレビューしているときに、エラーメッセージが表示されたり、予期しない結果が表示されることがあります。

原因:onContextChange prop によって呼び出される関数に問題がある可能性があります。

推奨される解決策:onContextChange prop とそれが呼び出す関数を StorefrontPreview コンポーネントから削除します。次に、サイトをプレビューして、同じ問題が発生するかどうかを確認します。発生しない場合は、関数をデバッグしてエラーを解決します。たとえば、以下を実行できます:

  • onContextChange prop とそれが呼び出す関数を StorefrontPreview コンポーネントに戻します。サードパーティ CMS とのインテグレーションを参照してください。
  • サイトのプレビュー中にネットワークアクティビティを検査し、フェッチリクエストが予期したデータを送信しているかどうかを確認します。

onContextChange prop とそれが呼び出す関数を削除しても問題が解決しない場合は、サポートケースを開いてください。

サイトのプレビュー中にコンテンツが期待どおりに表示されず、上記のエラーが発生しない場合。たとえば、Storefront Preview で入力した値に基づいて価格が変わらない場合などです。

原因: 前提条件の 1 つ以上を完了していない可能性があります。

推奨される解決策: 前提条件をすべて満たしていることを確認します。それでも問題が解決しない場合は、サポートケースを開いてください。