Engage SDKパッケージを使用してNextアプリを統合する(クライアント設定Cookie)

日本語翻訳に関する免責事項

このページの翻訳はAIによって自動的に行われました。可能な限り正確な翻訳を心掛けていますが、原文と異なる表現や解釈が含まれる場合があります。正確で公式な情報については、必ず英語の原文をご参照ください。

このトピックでは、Engage SDKパッケージを使用してNext.jsアプリを統合する方法について説明します。このチュートリアルでは、クライアント設定のCookieを使用します。

このチュートリアルでは、次の方法について説明します。

@sitecore/engageをインストールして初期化します。
初めてのVIEWイベントSend。
Sitecore CDPがVIEWイベントをキャプチャしたことを確認します。

始める前に

Sitecore CDPインスタンスに関する必要な詳細を収集します。
統合するNext.jsアプリを用意します。このウォークスルーは、Pages RouterとApp Routerの両方のバージョン12、13、および14.2.5でNext.jsテストされました。

@sitecore/engageのインストールと初期化

アプリを統合するための最初の手順は、@sitecore/engageパッケージをインストールして初期化することです。

パッケージをインストールして初期化するには、次のようにします。

ターミナルで、Next.jsアプリのルートフォルダを開きます。
次のコマンドを実行して、Engage SDKをインストールします。
npm install @sitecore/engage
コードエディターで、Next.jsアプリのルートフォルダーを開きます。
ルーターの種類に応じて、次の操作を行います。
- Pages Routerを使用している場合は、pages/apiフォルダに、engage.jsというファイルを作成します。
- App Routerを使用している場合は、appフォルダに、_apiというサブフォルダを作成します。次に、_apiフォルダーにengage.jsというファイルを作成します。

engage.jsに、次のコードを貼り付けます。

import { init } from "@sitecore/engage";

let engage;

const loadEngage = async () => {
  engage = await init({
    clientKey: "<client_key_PLACEHOLDER>",
    targetURL: "<stream_api_target_endpoint_PLACEHOLDER>",
    pointOfSale: "<point_of_sale_PLACEHOLDER>",
    cookieDomain: "<cookie_domain_PLACEHOLDER>",
    cookieExpiryDays: 365,
    forceServerCookieMode: false,
    includeUTMParameters: true,
    webPersonalization: false /* boolean or object. See Settings object for all options. Default: false */
  });
};

loadEngage();
export { engage };

プレースホルダーの値を、Sitecore CDPインスタンスの必要な詳細に置き換えます。

コンテンツセキュリティポリシー(CSP)

Engage SDKスクリプトを確実に読み込むには、コンテンツセキュリティポリシー(CSP)に次のものを追加する必要があります。

Stream APIターゲットエンドポイント。
https://d1mj578wat5n4o.cloudfront.net
Webパーソナライゼーションを実行し、環境がAP Region、EU Region、またはUS Regionの場合:

https://d35vb5cccm4xzp.cloudfront.net
Webパーソナライゼーションを実行し、環境がJP Regionの場合:

https://d2ez8k04aaol9g.cloudfront.net

このスクリプトは、次のことを行います。

@sitecore/engageパッケージからinit() 関数をインポートします。
Sitecore CDPインスタンスの詳細を使用してEngage APIを非同期的に読み込み、クライアントからCookieを設定します。
Engage APIのインスタンスをengageという変数としてエクスポートします。

モジュールをインポートするには:
- Pages Routerを使用する場合 - pagesフォルダ内のindex.jsファイルで、ReactからuseEffectをインポートし、engage.jsからengageをインポートします。
  import { useEffect } from "react"; import { engage } from "./api/engage.js";
- App Routerを使用している場合-appフォルダ内のpage.jsファイルで、ReactからuseEffectをインポートし、_api/engageからengageをインポートします。また、ファイルの先頭、すべてのインポートの上に "use client" ディレクティブを追加します。
  "use client"; import { useEffect } from "react"; import { engage } from "./_api/engage";

初めてのVIEWイベントSend

@sitecore/engageパッケージをインストールして初期化したら、データを収集してSitecore CDPに送信します。VIEWイベントは、Webページが読み込まれるたびにトリガーされるため、VIEWイベントを送信します。

VIEWイベントを送信するには:

VIEWイベント・データを送信するには、次のようにします。

Pages Routerを使用する場合は、index.jsファイルのHome関数で、engage.pageView()関数を呼び出します。

export default function Home() {

  // Send VIEW event ->
  useEffect(() => {
    if (engage !== undefined) {
      sendPageViewEvent();
    };
  }, []);

  const sendPageViewEvent = async () => {
    const response = await engage.pageView({
      channel: "<channel_PLACEHOLDER>",
      currency: "<currency_PLACEHOLDER>"
    });

    // For testing and debugging purposes only
    if (response) {
    console.log("Copy-paste the following line into Sitecore CDP > Guests > Search field:");
      console.log(engage.getBrowserId());
    };
  };
  // <- Send VIEW event

  return (<></>)
}

App Routerを使用する場合は、page.jsファイルのHome関数で、engage.pageView()関数を呼び出します。

export default function Home() {

  // Send VIEW event ->
  useEffect(() => {
    if (engage !== undefined) {
      sendPageViewEvent();
    };
  }, []);

  const sendPageViewEvent = async () => {
    const response = await engage.pageView({
      channel: "<channel_PLACEHOLDER>",
      currency: "<currency_PLACEHOLDER>"
    });

    // For testing and debugging purposes only
    if (response) {
    console.log("Copy-paste the following line into Sitecore CDP > Guests > Search field:");
      console.log(engage.getBrowserId());
    };
  };
  // <- Send VIEW event

  return (<></>)
}

プレースホルダーの値を、Sitecore CDPインスタンスの必要な詳細に置き換えます。

このスクリプトは、VIEWイベントオブジェクトを作成し、コンポーネントが初めてレンダリングされた直後にイベントデータをSitecore CDPに送信します。また、ブラウザIDをコンソールに記録します。次の手順では、ブラウザー IDを使用して、Sitecore CDPでVIEWイベントを検索します。

ターミナルで「 npm run dev 」と入力して、Next.jsアプリを起動します。Webページが読み込まれると、VIEWイベントがトリガーされ、イベントデータが送信されます。

Sitecore CDPがVIEWイベントをキャプチャしたことを確認します

VIEWイベントを送信した後、Sitecore CDPにログインしてイベントを見つけます。

Sitecore CDPがVIEWイベントをキャプチャしたことを確認するには:

Webブラウザーのコンソールで、次のようなテキストを見つけます。

a38b230c-11eb-4cf9-8d5d-274e9f344925
テキストをコピーします。
Sitecore CDPで、「Guests」をクリックし、検索ドロップダウンで「Browser ID」を選択し、コピーしたテキストを検索フィールドに貼り付けます。

匿名のゲストが表示されます。

このゲストは、ちょうど1分前にアプリを読み込んでいます。次に、このゲストに関連付けられているVIEWイベントを見つけます。
ゲストをクリックします。ゲストプロファイルが表示されます。
ゲストプロファイルページで、Event viewerをクリックします。このゲストに関連付けられているイベントのリストが表示されます。このリストにはVIEWイベントが含まれています。これは、前の手順でトリガーされたイベントです。

次のステップ

これで、アプリとSitecore CDPが正常に統合されました。アプリからイベントを送信し、Sitecore CDPがユーザーに関するデータをリアルタイムでキャプチャすることを確認しました。

この記事を改善するための提案がある場合は、お知らせください!