ユーザーを識別する
/users/identify
このエンドポイントを使用して、未確認の(エイリアスのみの)ユーザーを識別します。
2023年8月7日から、このエンドポイントはすべての呼び出しのデータをマージします。これは、merge_behavior
がすべての呼び出しに対してmerge
に設定されることを意味します。
/users/identify
を呼び出すと、エイリアスのみのプロファイルと識別されたプロファイルが結合され、エイリアスのみのプロファイルが削除されます。
ユーザーを識別するには、external_id
をaliases_to_identify
オブジェクトに含める必要があります。そのexternal_id
を持つユーザーがいない場合、external_id
はエイリアスされたユーザーの記録に追加され、ユーザーは識別されたと見なされます。リクエストごとに最大50個のユーザーエイリアスを追加できます。
その後、複数の追加ユーザーエイリアスを単一のexternal_id
に関連付けることができます。
- これらの後続の関連付けが
merge_behavior
フィールドをnone
に設定して行われると、ユーザーエイリアスに関連付けられたプッシュトークンとメッセージ履歴のみが保持されます。属性、イベント、または購入は「孤立」し、識別されたユーザーには利用できません。1つの回避策は、識別前にエイリアスされたユーザーのデータを/users/export/ids
エンドポイントを使用してエクスポートし、識別されたユーザーに属性、イベント、および購入を再関連付けることです。 merge_behavior
フィールドをmerge
に設定して関連付けを行うと、このエンドポイントは匿名ユーザーで見つかった特定のフィールドを識別されたユーザーにマージします。
ユーザーを識別する際にデータの予期しない損失を防ぐために、まずデータ収集のベストプラクティスを参照して、エイリアスのみのユーザー情報が既に存在する場合のユーザーデータのキャプチャについて学ぶことを強くお勧めします。
前提条件
このエンドポイントを使用するには、API キーとusers.identify
の権限が必要です。
レート制限
2021年9月16日以降に Braze にオンボーディングしたお客様については、このエンドポイントに対して行う要求にレート制限が適用されます。詳細については、APIの制限を参照してください。
Request body
1
2
Content-Type: application/json
Authorization: Bearer YOUR_REST_API_KEY
1
2
3
4
{
"aliases_to_identify" : (required, array of alias to identify objects),
"merge_behavior": (optional, string) one of 'none' or 'merge' is expected
}
リクエストパラメーター
パラメータ | required | データ型 | 説明 |
---|---|---|---|
aliases_to_identify |
required | オブジェクトを識別するためのエイリアスの配列 | エイリアスを参照してオブジェクトを識別するおよびユーザーエイリアスオブジェクトを参照してください。 |
merge_behavior |
オプション | string | none または merge のいずれかが必要です。 |
Merge_behavior フィールド
merge_behavior
フィールドをmerge
に設定すると、エンドポイントは匿名ユーザーに見つかった以下のフィールドのいずれかを特定のユーザーに排他的にマージするように設定されます。
- 名
- 姓
- メール
- 性別
- 生年月日
- 電話番号
- タイムゾーン
- 市区町村
- 国
- 言語
- セッション数 (両方のプロファイルのセッションの合計)
- 最初のセッションの日付(Brazeは2つの日付のうち、より早い日付を選択します)
- 最終セッションの日付(Brazeは2つの日付のうち後の日付を選択します)
- カスタム属性
- カスタムイベントおよび購入イベントデータ
- 「X回をY日以内に」というセグメンテーションのためのカスタムイベントおよび購入イベントプロパティ(X<=50およびY<=30の場合)
- セグメント化可能なカスタムイベントの概要
- イベント数(両方のプロファイルの合計)
- イベントが最初に発生した日(Brazeは2つの日付のうち、より早い日付を選択します)
- イベントが最後に発生した日(Brazeは2つの日付のうち、後の日付を選択します)
- 両方のプロファイルからの合計額(セント単位)でのアプリ内購入合計
- 購入総数 (両方のプロファイルの合計)
- 初回購入日(Brazeは2つの日付のうち、より早い日付を選択します)
- 最終購入日(Brazeは2つの日付のうち後の日付を選択します)
- アプリの概要
- Last_X_atフィールド(Brazeは孤立したプロファイルフィールドがより最近のものであればフィールドを更新します)
- キャンペーンの概要(Brazeは最新の日付フィールドを選択します)
- ワークフローの概要(Brazeは最新の日付フィールドを選択します)
- メッセージとメッセージエンゲージメント履歴
匿名ユーザーから識別されたユーザーに対して検出された次のいずれかのフィールド。
- カスタムイベントと購入イベントのカウントと最初の日付と最後の日付のタイムスタンプ
- これらのマージされたフィールドは「XイベントがY日間に更新される」フィルターを更新します。購入イベントの場合、これらのフィルターには「Y日間の購入回数」および「過去Y日間の支出金額」が含まれます。
セッションデータは、アプリが両方のユーザープロファイルに存在する場合にのみマージされます。たとえば、ターゲットユーザーには「ABCApp」のアプリ概要がなく、元のユーザーにはある場合、ターゲットユーザーのプロファイルにはマージ後に「ABCApp」のアプリ概要が表示されます。
フィールドをnone
に設定しても、ユーザーデータは識別されたユーザープロファイルにマージされません。
メールによるユーザーの識別
email
が識別子として指定されている場合、識別子には追加のprioritization
値が必要です。prioritization
は、複数のユーザーが見つかった場合にどのユーザーをマージするかを指定する配列である必要があります。prioritization
は順序付けられた配列であり、優先順位付けから複数のユーザーが一致する場合、マージは行われません。
配列に使用できる値は、identified
、unidentified
、most_recently_updated
です。most_recently_updated
は、最も最近更新されたユーザーを優先することを意味します。
優先配列には、一度に以下のオプションのうち1つしか存在できません。
identified
はexternal_id
を持つユーザーを優先することを指しますunidentified
はexternal_id
なしでユーザーを優先することを指します
リクエスト例
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"
}'
詳細については、alias_name
およびalias_label
、ユーザーエイリアスドキュメントをご覧ください。
応答
1
2
3
4
5
6
Content-Type: application/json
Authorization: Bearer YOUR_REST_API_KEY
{
"aliases_processed": 1,
"message": "success"
}