ユーザーを識別する

このエンドポイントを使用して、提供された外部IDを使用して未確認（エイリアスのみ、メールのみ、または電話番号のみ）のユーザーを識別する。

CDI の仕組み

/users/identify 、エイリアス（エイリアス専用プロファイル）、メール・アドレス（メール専用プロファイル）、または電話番号（電話番号専用プロファイル）によって識別されるユーザー・プロファイルを、external_id （識別済みプロファイル）を持つユーザー・プロファイルと結合し、その後エイリアス専用プロファイルを削除する。

ユーザーの識別には、aliases_to_identify またはemails_to_identify またはphone_numbers_to_identify オブジェクトにexternal_id を含める必要がある。そのexternal_id を持つユーザーが存在しない場合、external_id がエイリアスされたユーザーの記録に追加され、そのユーザーは識別されたとみなされる。

次のことに注意してください。

• これらの後続の関連付けがmerge_behaviorフィールドをnoneに設定して行われると、ユーザーエイリアスに関連付けられたプッシュトークンとメッセージ履歴のみが保持されます。属性、イベント、または購入は「孤立」し、識別されたユーザーには利用できません。1つの回避策は、識別前にエイリアスされたユーザーのデータを/users/export/idsエンドポイントを使用してエクスポートし、識別されたユーザーに属性、イベント、および購入を再関連付けることです。
• merge_behavior フィールドを merge に設定して関連付けを行うと、このエンドポイントは匿名ユーザーで見つかった特定のフィールドを識別されたユーザーにマージします。
• ユーザーは特定のラベルに対して1つのエイリアスしか持つことができない。もしユーザーがすでにexternal_id 、エイリアスのみのプロファイルと同じラベルを持つエイリアスが存在する場合、ユーザープロファイルは統合されない。

前提条件

このエンドポイントを使用するには、API キーとusers.identifyの権限が必要です。

レート制限

2021年9月16日以降に Braze にオンボーディングした顧客の場合、このエンドポイントには、1分あたり20,000リクエストの共有レート制限が適用されます。このレート制限は、API レート制限に記載されているように、/users/delete、/users/alias/new、/users/merge、および /users/alias/update エンドポイントと共有されます。

要求本文:

1
2
Content-Type: application/json
Authorization: Bearer YOUR_REST_API_KEY

1
2
3
4
5
6
{
   "aliases_to_identify" : (required, array of alias to identify objects),
   "emails_to_identify": (optional, array of string) User emails to identify,
   "phone_numbers_to_identify": (optional, array of string) User phone numbers to identify,
   "merge_behavior": (optional, string) one of 'none' or 'merge' is expected
}

リクエストパラメーター

リクエストごとに最大50個のユーザーエイリアスを追加できます。複数の追加ユーザーエイリアスを単一のexternal_idに関連付けることができます。

Merge_behavior フィールド

merge_behaviorフィールドをmergeに設定すると、匿名ユーザーにのみ存在する以下のフィールドが識別されたユーザーに統合されます。フィールドをnoneに設定しても、ユーザーデータは識別されたユーザープロファイルにマージされません。デフォルトでは、このフィールドはmerge に設定される。

メールによるユーザーの識別

識別子としてemail を指定する場合は、prioritization も識別子に含めなければならない。prioritization は、複数のユーザーが見つかった場合に、どのユーザーをマージするかを指定する配列でなければならない。prioritization は、順序付けられた配列である。つまり、優先順位付けから複数のユーザーがマッチした場合、マージは行われない。

配列に指定できる値は以下の通りである：

• identified
• unidentified
• most_recently_updated (最新の更新ユーザーを優先することを指す）
• least_recently_updated (最も更新の遅いユーザーを優先することを指す）

優先配列には、一度に以下のオプションのうち1つしか存在できません。

• identified を持つユーザーを優先することである。 external_id
• unidentified のないユーザーを優先することである。 external_id

配列にidentified を指定した場合、キャンバスに入るにはユーザーがexternal_id 。メールアドレスを持つユーザーに、識別子の有無にかかわらずメッセージを入力させたい場合は、代わりにmost_recently_updated またはleast_recently_updated パラメータのみを使用する。

リクエスト例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
curl --location --request POST 'https://rest.iad-01.braze.com/users/identify' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_REST_API_KEY' \
--data-raw '{
  "aliases_to_identify": [
    {
      "external_id": "external_identifier",
      "user_alias": {
          "alias_name": "example_alias",
          "alias_label": "example_label"
      }
    }
  ],
  "emails_to_identify": [
    {
      "external_id": "external_identifier_2",
      "email": "[email protected]",
      "prioritization": ["unidentified", "most_recently_updated"]
    }
  ]
  "merge_behavior": "merge"
}'

応答

1
2
3
4
5
6
Content-Type: application/json
Authorization: Bearer YOUR_REST_API_KEY
{
    "aliases_processed": 1,
    "message": "success"
}