概要
fetchExperiences は、MoEngage Personalize SDK のクライアント側メソッドです。実行時(通常はページ読み込み時またはコンポーネントのマウント時)に Experience キーのリストを指定して呼び出すと、MoEngage が現在のユーザー向けに解決したパーソナライズされたコンテンツが返されます。
Experience キーは、Personalize API Experience 用に MoEngage ダッシュボードで構成される識別子です。各キーは、ホームページのバナー、カートのオファー枠、商品一覧のカードなど、Web サイト上の配置場所に対応します。MoEngage は現在のユーザーをアクティブな Experience と照合して評価し、ユーザーが対象となる Experience のみを返します。ユーザーに対して解決できなかった Experience は、構造化された理由コードとともに別の failures 配列で返されます。
レンダリングレイヤーはお客様の Web サイトが担います。MoEngage は判定結果とコンテンツのペイロードを提供します。
fetchExperiences の実装
前提条件
SDK のインストール
Personalize API Experience の作成
Personalize API Experience を作成するには、こちらの記事を参照してください。使用するタイミング
Web サイトが独自のコンポーネントを使用してパーソナライズされたコンテンツをレンダリングし、MoEngage がコンテンツのペイロードと判定を提供する場合は、fetchExperiences を使用します。一般的なユースケースには、パーソナライズされたバナー、オファーカード、ロイヤルティモジュール、商品一覧のプロモーション、カートでのアップセル、動的なレコメンデーションブロックなどがあります。
関連のないページコンポーネントから個別に実装するのではなく、一元化されたパーソナライゼーションレイヤーを通じて実装してください。これにより、サイト全体でのフォールバック動作、アトリビューション、Experience キーのガバナンスの管理が容易になります。
メソッドシグネチャ
このメソッドは、
experiences と failures を含むレスポンスオブジェクトで解決される Promise を返します。
Experience の取得
特定の Experience を取得する
ページに固定の配置場所があり、リクエストする Experience キーが正確にわかっている場合に使用します。カスタム属性を使用して Experience を取得する
MoEngage のオーディエンスがロケール、ページタイプ、国などの実行時の値をターゲティングに使用する場合は、カスタム属性を渡します。対象となるすべてのアクティブな Experience を取得する
空の配列を渡すと、現在のユーザーがすべてのアクティブな Experience と照合して評価されます。MoEngage は対象となる結果を最大 25 件返します。仕組み
- ページが MoEngage SDK を初期化し、ユーザーの ID と同意を確立します。
- コードが、関連する Experience キーと任意のカスタム属性を指定して
fetchExperiencesを呼び出します。 - MoEngage が、アクティブなキャンペーンと関連するセグメントルール、コントロールグループ、A/B バリアント、Decision Policy に照らしてユーザーを評価します。
- Promise が、
experiencesとfailuresを含むレスポンスオブジェクトで解決されます。 - コードが、解決された各 Experience のペイロードを読み取り、検証し、レンダリングします。
- コードが、
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() で解析してください。
失敗の処理
Experience キーがfailures に含まれている場合、その Experience は現在のユーザーに配信されていません。実装では、その配置場所を非表示にするか、デフォルトのコンテンツをレンダリングする必要があります。
E001
実装例
完全な例 - 直接的なフィールド値のペイロードを読み取る
以下のクリックハンドラーでは、サンプルとして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 の両方のクリックがトラッキングされます。