Hightouch Personalization API

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

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

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

前提条件

• ユースケース
• データセット

統合

ステップ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を使用して取得できます。

たとえば、キャンペーンやキャンバスにこのスニペットを含めることができます。

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サポートまでお問い合わせください。