Hightouch Personalization API

Hightouch の Personalization API は、クラウドデータウェアハウスのデータセットに基づいて低レイテンシーのデータAPI をホストできるようにするマネージドサービスです。

Braze と Hightouch の統合により、Braze コネクテッドコンテンツとこの API を使用して、送信時に最新の顧客またはオブジェクトのデータをキャンペーンまたはキャンバスに取り込むことができます。

Hightouch の Personalization API は、Braze の設定で使用する REST エンドポイントを提供します。具体的には、Braze のコネクテッドコンテンツを使用して Personalization API に対する GET リクエストを実行し、特定の識別子に関連するすべての情報を取得できます。この API によって公開されるデータは、顧客、製品、またはその他のオブジェクトデータを表す場合があります。

前提条件

• 使用例
• データセット

統合

ステップ1:データソースを Hightouch に接続する

ハイタッチ・ソースは、組織のビジネス・データが存在する場所である。この場合、ユーザーデータが保存されている場所はどこでもかまいません。

1. ハイタッチで、「ソースの概要」＞「ソースの追加」と進む。ソースとしてデータウェアハウスを選択します。
   
   
2. 関連する認証情報を入力する。これらはソースによって異なる。

詳細については、関連するソースのドキュメントを参照してください。

ステップ2:モデルデータ

ハイタッチ・モデルは、ソースからどのようなデータを引き出すかを定義する。新しいモデルをセットアップするには、以下の手順に従う：

1. Hightouch で [Models overview] > [Add model] に移動し、接続したソースを選択します。
   
   
2. 次にモデリング方法を選択します。すべての情報を1つのテーブルにまとめる必要があるので、ビジュアル・テーブル・セレクタを使って定義することができる。あるいは、必要なカラムだけを含むSQLを書いたり、既存のdbtモデル、ルッカー・ルック、シグマ・ワークブックに頼ることもできる。
   
   
3. 続行する前に、モデルをプレビューして、興味のあるデータを照会していることを確認する。デフォルトでは、Brazeはプレビューを最初の100レコードに制限している。データを検証したら、[Continue] をクリックします。
   
   
4. 例えば、”User recommendations “のように、モデルに名前をつける。
   
   
5. 最後に主キーを選択し、[Finish] をクリックします。主キーは、一意の識別子を持つ列である必要があります。これは、特定のユーザーのレコメンデーションを取得するために Personalization API を呼び出すときに使用するフィールドでもあります。

ステップ3:パーソナライゼーションAPIを設定する

API でリクエストを受信するための準備は、次の2つのステップからなります。

• お客様のインフラに最も近い地域でパーソナライゼーションAPIを有効にする
• Hightouchが管理するキャッシュで実体化されるべきモデルを定義するためにシンクを作成する。

以下の指示に従って、両方を完了させる：

1. ハイタッチでは 目的地を選択し、あなたのために作成されたHightouchパーソナライゼーションAPIを選択する。この宛先が有効になっていない場合は、ハイタッチ・サポートに連絡すること。
   
   
2. 次に、適切な地域を選択する。インフラに最も近い地域を選択することで、応答時間を短縮することができる。インフラストラクチャに近いリージョンが表示されない場合は、Hightouch サポートにお問い合わせください。
   
   
3. [Syncs] 概要ページに進み、[Add sync] ボタンをクリックします。次に、該当するモデルと、以前に設定した宛先を選択します。
   
   
4. 英数字のコレクション名を入力します。コレクションは概念的にはデータベースのテーブルに似ている。各コレクションは特定のデータタイプ (顧客や請求書など) を表します。コレクション名には英数字のみを使用する必要があります。コレクション名は、Personalization API エンドポイントの一部になります。
   
   
5. 次に、モデルのどの列をレコード検索の一次インデックスとして使用するかを指定します。このフィールドは、コレクション内の各レコードを一意に識別する必要があり、多くの場合、モデルの主キーと同じである。パーソナライゼーションAPIは、複数のインデックスの検索をサポートする。たとえば、user_id、anonymous_id、または email_address を使用して顧客プロファイルを取得できます。複数のインデックスを有効にする場合は、Hightouch サポートにご連絡ください。
   
   
6. フィールドマッパーを使用して、APIレスポンスペイロードに含まれるべきモデルのカラムを指定する。これらのフィールドの名前を変更し、リキッドテンプレート言語を使用して変換を適用するために高度なマッパーを使用することができる。
   
   
7. ユースケースに適した削除動作を選択します。
   
   
8. 最後に [Continue] をクリックし、同期スケジュールを選択します。

Hightouch は、ウェアハウス内のデータをマネージドデータベースに同期し、Personalization API を介して公開します。

ステップ4:Braze Connected Contentを通じてパーソナライゼーションAPIを呼び出す

パーソナライゼーションAPIインスタンスを設定したら、それをBraze Connected Contentのエンドポイントとして使用できる。

API は、https://personalization.{region}.hightouch.com でアクセスできます (例: https://personalization.us-west-2.hightouch.com)。

情報はエンドポイント /v1/collections/:collection_name/records/:index_key/:index_value を使用して取得できます。

例えば、キャンペーンやキャンバスにこのスニペットを入れることができる：

1
2
3
4
5
6
7
8
9
{% connected_content
     https://personalization.us-west-2.hightouch.com/v1/collections/customer/records/id/12345
     :method get
     :headers {
       "Authorization": "Bearer {{YOUR-API-KEY}}"
  }
     :content_type application/json
     :save customer
%}

リキッドテンプレートを使って、JSONペイロードで返されたプロパティを参照し、メッセージングで使うことができる。

以下のペイロードの例の場合：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
{
    "user_id": 12345,
    "full_name": "Jane Doe",
    "lifetime_value": 1492.18,
    "churn_risk": 0.04,
    "90_day_summary": {
        "num_songs_listened": 813,
        "top_genres": [
            "house",
            "techno",
            "ambient"
        ],
        "top_artists": [
            "deadmau5",
            "Marsh",
            "Enamour"
        ],
    },
    "recommendations": {
        "concerts": [
            {
                "artist": "Aphex Twin",
                "location": "San Francisco, CA",
                "event_date": "2023-01-31"
            },
            {
                "artist": "Sultan + Shepard",
                "location": "San Francisco, CA",
                "event_date": "2023-02-25"
            }
        ],
        "upcoming_album_release": {
            "title": "Universal Language",
            "artist": "Simon Doty",
            "label": "Anjunadeep",
            "release_date": "2023-04-28"
        }
    },
}

以下の Liquid リファレンスは、この例のデータを戻します。

トラブルシューティング

ご質問がある場合は、Hightouch サポートまでお問い合わせください。