メインコンテンツへスキップ

概要

fetchExperiences は、MoEngage Personalize SDK のクライアント側メソッドです。実行時(通常はページ読み込み時またはコンポーネントのマウント時)に Experience キーのリストを指定して呼び出すと、MoEngage が現在のユーザー向けに解決したパーソナライズされたコンテンツが返されます。 Experience キーは、Personalize API Experience 用に MoEngage ダッシュボードで構成される識別子です。各キーは、ホームページのバナー、カートのオファー枠、商品一覧のカードなど、Web サイト上の配置場所に対応します。MoEngage は現在のユーザーをアクティブな Experience と照合して評価し、ユーザーが対象となる Experience のみを返します。ユーザーに対して解決できなかった Experience は、構造化された理由コードとともに別の failures 配列で返されます。 レンダリングレイヤーはお客様の Web サイトが担います。MoEngage は判定結果とコンテンツのペイロードを提供します。

fetchExperiences の実装

前提条件

SDK のインストール

  1. Web サイトに Web SDK を統合するには、こちらの記事を参照してください。
  2. Web サイトに Personalize SDK を統合するには、こちらの記事を参照してください。

Personalize API Experience の作成

Personalize API Experience を作成するには、こちらの記事を参照してください。

使用するタイミング

Web サイトが独自のコンポーネントを使用してパーソナライズされたコンテンツをレンダリングし、MoEngage がコンテンツのペイロードと判定を提供する場合は、fetchExperiences を使用します。一般的なユースケースには、パーソナライズされたバナー、オファーカード、ロイヤルティモジュール、商品一覧のプロモーション、カートでのアップセル、動的なレコメンデーションブロックなどがあります。
関連のないページコンポーネントから個別に実装するのではなく、一元化されたパーソナライゼーションレイヤーを通じて実装してください。これにより、サイト全体でのフォールバック動作、アトリビューション、Experience キーのガバナンスの管理が容易になります。

メソッドシグネチャ

このメソッドは、experiences と failures を含むレスポンスオブジェクトで解決される Promise を返します。

Experience の取得

特定の Experience を取得する

ページに固定の配置場所があり、リクエストする Experience キーが正確にわかっている場合に使用します。

カスタム属性を使用して Experience を取得する

MoEngage のオーディエンスがロケール、ページタイプ、国などの実行時の値をターゲティングに使用する場合は、カスタム属性を渡します。

対象となるすべてのアクティブな Experience を取得する

空の配列を渡すと、現在のユーザーがすべてのアクティブな Experience と照合して評価されます。MoEngage は対象となる結果を最大 25 件返します。
固定の配置場所には、明示的な Experience キーを使用してください。空の配列は、動的なオファーフィードやディスカバリー型のコンテンツエリアなど、返される Experience の動的なセットを処理できるようにフロントエンドが構築されている場合にのみ渡してください。空の配列モードでは、返された各 Experience をどこに配置するか、必要な配置場所の Experience が返されなかった場合にどうするか、利用可能な枠よりも多くの結果が返された場合にどう処理するかを、レンダリングロジックで判断する必要があります。

仕組み

  1. ページが MoEngage SDK を初期化し、ユーザーの ID と同意を確立します。
  2. コードが、関連する Experience キーと任意のカスタム属性を指定して fetchExperiences を呼び出します。
  3. MoEngage が、アクティブなキャンペーンと関連するセグメントルール、コントロールグループ、A/B バリアント、Decision Policy に照らしてユーザーを評価します。
  4. Promise が、experiences と failures を含むレスポンスオブジェクトで解決されます。
  5. コードが、解決された各 Experience のペイロードを読み取り、検証し、レンダリングします。
  6. コードが、experience_context と offering_context(レスポンスに含まれている場合)を MoEngage のインプレッションおよびクリックのトラッキング呼び出しに渡します。

レスポンス

レスポンスの構造

解決されたレスポンスには、experiences と failures の 2 つのトップレベルキーが含まれます。両方が同じレスポンスに含まれる場合があり、1 回の呼び出しで、解決された Experience と失敗の両方が同時に返されることがあります。

レスポンスフィールド

ペイロード形式

ペイロードの形状は、MoEngage での Experience の構成方法によって異なります。形式は 2 種類あります。

形式 1 - 直接的なフィールド値

各コンテンツフィールドは、payload の下に個別のキーとして返されます。値は直接読み取ることができ、解析は不要です。
オプショナルチェーンを使用して値を直接読み取ります。
ハイフンを含む Experience キーにはブラケット表記を使用してください(result.experiences['homepage-banner'])。ドット表記(result.experiences.homepage-banner)では - が減算演算子として扱われ、原因の特定が難しい実行時エラーが発生します。

形式 2 - シリアル化された JSON オファー配列

1 つのペイロードフィールドに、Decision Policy によって返されたランク付けされたオファーのリストを表す JSON エンコードされた文字列が含まれます。使用する前に JSON.parse() で解析してください。
すべてのペイロードフィールドに対して JSON.parse() を呼び出さないでください。シリアル化された JSON が含まれていることがわかっているフィールドのみを解析してください。タイトルや URL などのプレーンな文字列値に対して JSON.parse() を呼び出すと、エラーがスローされます。

失敗の処理

Experience キーが failures に含まれている場合、その Experience は現在のユーザーに配信されていません。実装では、その配置場所を非表示にするか、デフォルトのコンテンツをレンダリングする必要があります。 E001E003 および E008 は、想定される実行時の状態です。E004E007 は MoEngage の構成に問題があることを示しており、調査のためにログエントリーまたはアラートを発生させる必要があります。

実装例

完全な例 - 直接的なフィールド値のペイロードを読み取る

以下のクリックハンドラーでは、サンプルとして attachClickHandler() を使用しています。これを、お使いのフロントエンドフレームワークやコンポーネントライブラリで使用しているイベントバインディングパターンに置き換えてください。

完全な例 - シリアル化された JSON オファー配列のペイロードを読み取る

Experience のペイロードにオファリングデータが含まれている場合(形式 2)、配列内の各オファーには独自の offering_context があります。表示された、または操作された各オファーについて、インプレッションとクリックをトラッキングします。 メソッドの完全なリファレンスについては、Offerings イベントのトラッキングを参照してください。 以下のクリックハンドラーでは、サンプルとして attachClickHandler(offer, index) を使用しています。これを、お使いのフロントエンドフレームワークやコンポーネントライブラリで使用しているイベントバインディングパターンに置き換えてください。

インプレッションとクリックのトラッキング

解決された各 Experience とそのオファーをレンダリングした後、適切な MoEngage SDK のトラッキングメソッドを呼び出します。
  • 解決されたすべての Experience キーについて、レンダリング後に Moengage.personalize.trackImpression(experience_context) を呼び出します。
  • ユーザーがレンダリングされた Experience を操作したときは、Moengage.personalize.trackClick(experience_context, extraAttributes) を呼び出します。extraAttributes はオプションで、クリックされた CTA に関する追加のコンテキストを渡すために使用します。
  • オファリングデータを含む Experience については、レンダリングされた各オファーに対して Moengage.personalize.offeringShown(offering_context) を呼び出します。配列内の各オファーには独自の offering_context があります。そのまま渡し、オファー間でコンテキストを再利用しないでください。
  • オファーがクリックされたときは、Moengage.personalize.offeringClicked(offering_context, experience_context) を呼び出します。両方のコンテキストを渡すと、1 回の呼び出しでオファリングと親の Experience の両方のクリックがトラッキングされます。
メソッドの完全なリファレンスについては、Personalize API Experience イベントのトラッキングおよび Offerings イベントのトラッキングを参照してください。 さらにサポートが必要な場合は、MoEngage のカスタマーサクセスマネージャー(CSM)またはサポートチームにお問い合わせください。