Skip to content

ユーザーを追跡

post

/users/track

core endpoint

このエンドポイントを使用して、カスタムイベントと購入を記録し、ユーザープロファイル属性を更新します。

See me in Postman

前提条件

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

サーバー間の呼び出しに API を使用する顧客がファイアウォールの内側にいる場合には、rest.iad-01.braze.com を許可リストに登録する必要が生じることがあります。

レート制限

Request body

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),
}

リクエストパラメーター

パラメータ required データ型 説明
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": "test@braze.com",
            "string_attribute": "fruit",
            "boolean_attribute_1": true,
            "integer_attribute": 25,
            "array_attribute": [
                "banana",
                "apple"
            ]
        }
    ],
    "events": [
        {
            "email": "test@braze.com",
            "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": "test@braze.com",
            "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エンドポイントでユーザープロファイルを更新できます。このエンドポイントは、有効な電話番号を含めた場合にのみ機能します。

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": "example@email.com",
    "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@example.com"
        }
    ],
}'

応答

これらの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ユーザー」が含まれている可能性があります。詳細については、「スパムのブロック」を参照してください。

よくある質問

同じメールアドレスを持つ複数のプロファイルが見つかった場合はどうなりますか？

external_id が存在する場合、external ID を持つ最新の更新されたプロファイルが更新の優先順位となります。external_idが存在しない場合、最も最近更新されたプロファイルが更新の優先対象となります。

メールアドレスのプロファイルが存在しない場合はどうなりますか？

新しいプロファイルが作成され、メール専用のユーザーが作成されます。エイリアスは作成されません。メールフィールドはtest@braze.comに設定されます。これは、メールアドレスによるユーザープロファイルの更新要求の例で示されています。

どのようにして/users/trackを使用してレガシーユーザーデータをインポートしますか？

まだモバイルアプリを使用していないユーザーのユーザープロファイルを生成するために、Braze APIを通じてデータを送信することができます。ユーザーがその後アプリケーションを使用すると、SDKを介して識別された後のすべての情報が、APIコールを介して作成された既存のユーザープロファイルとマージされます。識別前に SDK によって匿名で記録されたユーザーの行動は、既存の API 生成ユーザープロファイルと統合された時点で失われます。

セグメンテーションツールは、ユーザーがアプリを使用したかどうかに関係なく、これらのユーザーを含めます。ユーザー API 経由でアップロードされたものの、アプリをまだ使用していないユーザーを除外する場合は、Session Count > 0 フィルターを追加します。

/users/trackは重複イベントをどのように処理しますか？

イベント配列内の各イベントオブジェクトは、指定された時間にユーザーによるカスタムイベントの単一の発生を表します。これは、Brazeに取り込まれる各イベントに独自のイベントIDがあることを意味し、「重複」イベントは別々のユニークなイベントとして扱われるということです。

Github   GitHub でこのページを編集
「このページはどの程度役に立ちましたか?」
New Stuff!