ユーザーを追跡
このエンドポイントを使用して、カスタムイベントと購入を記録し、ユーザープロファイル属性を更新します。
BrazeはAPIを通して渡されたデータを額面通りに処理し、顧客は不要なデータポイントの消費を最小限に抑えるために、デルタ（変化するデータ）のみを渡すべきである。続きを読むには、データポイントを参照してください。
前提条件
このエンドポイントを使用するには、API キーとusers.trackの権限が必要です。
サーバー間の呼び出しに API を使用する顧客がファイアウォールの内側にいる場合には、rest.iad-01.braze.com を許可リストに登録する必要が生じることがあります。
レート制限
要求本文:
1
2
Content-Type: application/json
Authorization: Bearer YOUR_REST_API_KEY
1
2
3
4
5
{
"attributes": (optional, array of attributes object),
"events": (optional, array of event object),
"purchases": (optional, array of purchase object),
}
リクエストパラメーター
次のテーブルに記載されている各リクエストコンポーネントには、external_id、user_alias、braze_id、email、または phone のいずれかが必要です。
| パラメータ | 必須 | データ型 | 説明 |
|---|---|---|---|
attributes |
オプション | 属性オブジェクトの配列 | ユーザー属性オブジェクトを参照してください |
events |
オプション | イベントオブジェクトの配列 | イベントオブジェクトを参照してください |
purchases |
オプション | 購入オブジェクトの配列 | 購入オブジェクトを参照してください |
例のリクエスト
メールアドレスでユーザープロファイルを更新
/users/track エンドポイントを使用して、メールアドレスでユーザープロファイルを更新できます。
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
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
curl --location --request POST 'https://rest.iad-01.braze.com/users/track' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_REST_API_KEY' \
--data-raw '{
"attributes": [
{
"email": "[email protected]",
"string_attribute": "fruit",
"boolean_attribute_1": true,
"integer_attribute": 26,
"array_attribute": [
"banana",
"apple"
]
}
],
"events": [
{
"email": "[email protected]",
"app_id": "your_app_identifier",
"name": "rented_movie",
"time": "2022-12-06T19:20:45+01:00",
"properties": {
"release": {
"studio": "FilmStudio",
"year": "2022"
},
"cast": [
{
"name": "Actor1"
},
{
"name": "Actor2"
}
]
}
},
{
"user_alias": {
"alias_name": "device123",
"alias_label": "my_device_identifier"
},
"app_id": "your_app_identifier",
"name": "rented_movie",
"time": "2013-07-16T19:20:50+01:00"
}
],
"purchases": [
{
"email": "[email protected]",
"app_id": "your_app_identifier",
"product_id": "product_name",
"currency": "USD",
"price": 12.12,
"quantity": 6,
"time": "2017-05-12T18:47:12Z",
"properties": {
"color": "red",
"monogram": "ABC",
"checkout_duration": 180,
"size": "Large",
"brand": "Backpack Locker"
}
}
]
}'
電話番号でユーザープロファイルを更新する
電話番号を使用して/users/trackエンドポイントでユーザープロファイルを更新できます。このエンドポイントは、有効な電話番号を含めた場合にのみ機能します。
email とphone の両方をリクエストに含めると、Brazeはメールを識別子として使用する。
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
curl --location --request POST 'https://rest.iad-01.braze.com/users/track' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_REST_API_KEY' \
--data-raw '{
"attributes": [
{
"phone": "+15043277269",
"string_attribute": "fruit",
"boolean_attribute_1": true,
"integer_attribute": 25,
"array_attribute": [
"banana",
"apple"
]
}
],
}'
サブスクリプショングループを設定する
この例では、ユーザーを作成し、ユーザー属性オブジェクト内にサブスクリプショングループを設定する方法を示します。
このエンドポイントを使用してサブスクリプションステータスを更新すると、external_id で指定されたユーザー (User1 など) が更新され、そのユーザー (User1) と同じメールアドレスを持つすべてのユーザーのサブスクリプションステータスも更新されます。
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
curl --location --request POST 'https://rest.iad-01.braze.com/users/track' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_REST_API_KEY' \
--data-raw '{
"attributes": [
{
"external_id": "user_identifier",
"email": "[email protected]",
"email_subscribe": "subscribed",
"subscription_groups": [{
"subscription_group_id": "subscription_group_identifier_1",
"subscription_state": "unsubscribed"
},
{
"subscription_group_id": "subscription_group_identifier_2",
"subscription_state": "subscribed"
},
{
"subscription_group_id": "subscription_group_identifier_3",
"subscription_state": "subscribed"
}
]
}
]
}'
エイリアスのみのユーザーを作成するリクエスト例
リクエストの本文に_update_existing_onlyキーをfalseの値で設定することにより、新しいエイリアス専用ユーザーを作成するために/users/trackエンドポイントを使用できます。この値が省略された場合、エイリアスのみのユーザープロファイルは作成されません。エイリアスのみのユーザーを使用すると、そのエイリアスを持つ1つのプロファイルが存在することが保証されます。これは、新しい統合を構築する際に特に役立ちます。重複したユーザープロファイルの作成を防ぎます。
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
curl --location --request POST 'https://rest.iad-01.braze.com/users/track' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_REST_API_KEY' \
--data-raw '{
{
"attributes": [
{
"_update_existing_only": false,
"user_alias": {
"alias_name": "example_name",
"alias_label": "example_label"
},
"email": "[email protected]"
}
],
}'
回答
これらのAPIリクエストのいずれかを使用する場合、次の3つの一般的な応答のいずれかを受け取るはずです: 成功メッセージ、非致命的なエラーを含む成功メッセージ、または致命的なエラーを含むメッセージ。
成功したメッセージ
成功したメッセージには次の応答が返されます:
1
2
3
4
5
6
{
"message": "success",
"attributes_processed": (optional, integer), if attributes are included in the request, this will return an integer of the number of external_ids with attributes that were queued to be processed,
"events_processed": (optional, integer), if events are included in the request, this will return an integer of the number of events that were queued to be processed,
"purchases_processed": (optional, integer), if purchases are included in the request, this will return an integer of the number of purchases that were queued to be processed,
}
非致命的なエラーがある成功メッセージ
メッセージが成功しているが、長いイベントリストの中に1つの無効なイベントオブジェクトが含まれているなどの致命的でないエラーがある場合、次の応答が返されます:
1
2
3
4
5
6
7
8
{
"message": "success",
"errors": [
{
<minor error message>
}
]
}
成功メッセージの場合、errors 配列内のエラーの影響を受けないデータは引き続き処理されます。
致命的なエラーが発生したメッセージ
メッセージに致命的なエラーがある場合、次の応答が返されます:
1
2
3
4
5
6
7
8
{
"message": <fatal error message>,
"errors": [
{
<fatal error message>
}
]
}
致命的なエラー応答コード
ステータスコードおよび関連するエラーメッセージについては、リクエストが致命的なエラーに遭遇した場合に返される致命的なエラーと応答を参照してください。
「provided external_id is blacklisted and disallowed」というエラーを受け取った場合、リクエストに「dummyユーザー」が含まれている可能性があります。詳細については、「スパムのブロック」を参照してください。
よくある質問
法的に要求されているトランザクションメールを SMS ゲートウェイに送信しないでください。これらのメールは配信されない可能性が高いためです。
電話番号とプロバイダーのゲートウェイドメイン（MM3として知られている）を使用して送信したメールは、SMS（テキスト）メッセージとして受信される可能性があるが、一部のメールプロバイダーはこの動作をサポートしていない。例えば、T-モバイルの電話番号（”[email protected]”など）にメールを送った場合、SMSメッセージはT-モバイル・ネットワークでその電話番号を所有している人に送信される。
これらのメールがSMSゲートウェイに配信されなくても、メール課金にはカウントされることを覚えておいてほしい。サポートされていないゲートウェイへのメール送信を避けるには、サポートされていないゲートウェイのドメイン名のリストを確認します。
同じメールアドレスを持つ複数のプロファイルが見つかった場合はどうなりますか？
external_id が存在する場合、external ID を持つ最新の更新されたプロファイルが更新の優先順位となります。external_idが存在しない場合、最も最近更新されたプロファイルが更新の優先対象となります。
メールアドレスのプロファイルが存在しない場合はどうなりますか？
新しいプロファイルが作成され、メール専用のユーザーが作成されます。エイリアスは作成されません。メールフィールドは[email protected]に設定されます。これは、メールアドレスによるユーザープロファイルの更新要求の例で示されています。
どのようにして/users/trackを使用してレガシーユーザーデータをインポートしますか？
まだモバイルアプリを使用していないユーザーのユーザープロファイルを生成するために、Braze APIを通じてデータを送信することができます。ユーザーがその後アプリケーションを使用すると、SDKを介して識別された後のすべての情報が、APIコールを介して作成された既存のユーザープロファイルとマージされます。識別前に SDK によって匿名で記録されたユーザーの行動は、既存の API 生成ユーザープロファイルと統合された時点で失われます。
セグメンテーションツールは、ユーザーがアプリを使用したかどうかに関係なく、これらのユーザーを含めます。ユーザー API 経由でアップロードされたものの、アプリをまだ使用していないユーザーを除外する場合は、Session Count > 0 フィルターを追加します。
/users/trackは重複イベントをどのように処理しますか？
イベント配列内の各イベントオブジェクトは、指定された時間にユーザーによるカスタムイベントの単一の発生を表します。これは、Brazeに取り込まれる各イベントに独自のイベントIDがあることを意味し、「重複」イベントは別々のユニークなイベントとして扱われるということです。
月間アクティブユーザー数 CY 24-25
Monthly Active Users - CY 24-25を購入した顧客に対して、Brazeは/users/track エンドポイントで異なるレート制限を管理している：
- 1時間あたりのレート制限は、お客様のアカウントで予想されるデータ摂取アクティビティに応じて設定される。このアクティビティは、お客様が購入した月間アクティブユーザー数、業界、季節性、またはその他の要因に対応する可能性がある。
- 時間あたりのリクエスト数の制限に加えて、Brazeは1秒あたりのリクエスト数にバースト制限を課している。
- 各リクエストは、アトリビューション、イベント、購入オブジェクトを合わせて最大50件の更新をバッチ処理することができる。
予想される摂取量に基づく現在の制限は、ダッシュボードの「設定」>「APIと識別子」>「API制限」で確認できる。当社は、システムの安定性を保護するため、またはお客様のアカウントのデータスループットを向上させるために、レート制限を変更する場合がある。時間単位または秒単位のリクエスト制限やお客様のビジネスのニーズに関するご質問やご不明な点については、Brazeサポートまたはカスタマーサクセスマネージャーにお問い合わせください。
GitHub でこのページを編集