Hightouch Personalization API

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

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

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

前提条件

• use cases
• datasets

統合

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

Hightouchのソースは、組織のビジネスデータが存在する場所です。この場合、ユーザーデータが保存されている場所になります。

1. Hightouchで、Sources Overview > Add Source に移動します。ソースとしてデータウェアハウスを選択します。
   
   
2. 関連する認証情報を入力します。これらはソースによって異なります。

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

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

Hightouchモデルは、ソースからどのようなデータを取得するかを定義します。新しいモデルをセットアップするには、以下の手順に従います。

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

ステップ3: Personalization API を設定する

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

• お客様のインフラに最も近い地域で Personalization API を有効にする
• Hightouchが管理するキャッシュでマテリアライズされるべきモデルを定義するために同期を作成する

以下の手順に従って、両方を完了させます。

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

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

ステップ4: Brazeコネクテッドコンテンツを通じて Personalization API を呼び出す

Personalization API インスタンスを設定したら、それをBrazeコネクテッドコンテンツのエンドポイントとして使用できます。

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

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

たとえば、CampaignやCanvasにこのスニペットを含めることができます。

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
%}

Liquid テンプレートを使って、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 サポートまでお問い合わせください。