ユーザー属性オブジェクト

属性オブジェクトにフィールドを含む API リクエストは、指定されたユーザープロファイルに指定された値で、その名前の属性を作成または更新します。

Braze ユーザープロファイルフィールド名（以下にリストされているもの、または Braze ユーザープロファイルフィールドのセクションにリストされているもの）を使用して、ダッシュボードのユーザープロファイル上の特別な値を更新するか、独自のカスタム属性データをユーザーに追加します。

オブジェクト本体

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
{
  // One of "external_id" or "user_alias" or "braze_id" or "email" or "phone" is required
  "external_id" : (optional, string) see external user ID,
  "user_alias" : (optional, User alias object),
  "braze_id" : (optional, string) Braze user identifier,
  "email": (optional, string) User email address,
  "phone": (optional, string) User phone number,
  // Setting this flag to true puts the API in "Update Only" mode.
  // When using a "user_alias", "Update Only" defaults to true.
  "_update_existing_only" : (optional, boolean),
  // See note regarding anonymous push token imports
  "push_token_import" : (optional, boolean),
  // Braze User Profile Fields
  "first_name" : "Jon",
  "email" : "[email protected]",
  // Custom Attributes
  "my_custom_attribute" : value,
  "my_custom_attribute_2" : {"inc" : int_value},
  "my_array_custom_attribute":[ "Value1", "Value2" ],
  // Adding a new value to an array custom attribute
  "my_array_custom_attribute" : { "add" : ["Value3"] },
  // Removing a value from an array custom attribute
  "my_array_custom_attribute" : { "remove" : [ "Value1" ]},
}

• 外部ユーザー ID
• ユーザーのエイリアス

プロファイル属性を削除するには、null に設定します。external_id や user_alias などの一部のフィールドは、ユーザープロファイルに追加された後に削除することはできません。

識別子の解決

匿名プッシュトークンインポートを実行している場合を除き、各ユーザー属性オブジェクトには少なくとも1つの識別子（external_id、user_alias、braze_id、email、または phone）を含める必要があります。できる限り、オブジェクトごとに1つの識別子のみを含めて、どのユーザープロファイルが更新または作成されるかがあいまいにならないようにしてください。

識別子を使用する際は、以下の点に注意してください。

• external_id と user_alias は相互に排他的です。両方を同じユーザー属性オブジェクトに含めるとエラーが返されます。すでに external_id を持つユーザーにエイリアスを追加するには、/users/alias/new エンドポイントを使用してください。
• email は phone よりも優先されます。同じオブジェクトに email と phone の両方が含まれている場合、Braze は識別子として email を使用します。つまり、電話番号が別のプロファイルに属している場合でも、属性はそのメールアドレスに関連付けられたユーザープロファイルに適用されます。

既存のプロファイルのみを更新する

Braze で既存のユーザープロファイルのみを更新したい場合は、リクエスト本文の中で _update_existing_only キーに true の値を渡す必要があります。この値を省略した場合、external_id がまだ存在しなければ、Braze は新しいユーザープロファイルを作成します。

プッシュトークンインポート

Braze にプッシュトークンをインポートする前に、本当に必要かどうかを再確認してください。Braze SDK が導入されると、プッシュトークンは自動的に処理され、API を介してアップロードする必要はありません。

API を使用してアップロードする必要がある場合は、識別されたユーザーまたは匿名ユーザーに対してアップロードできます。これは、external_id が存在する必要があるか、匿名ユーザーが push_token_import フラグを true に設定する必要があることを意味します。

push_token_import を true として指定する場合:

• external_id と braze_id は指定しないでください
• 属性オブジェクトにはプッシュトークンを含める必要があります
• トークンがすでに Braze に存在する場合、リクエストは無視されます。そうでない場合は、Braze がトークンごとに一時的な匿名ユーザープロファイルを作成し、これらの個人にメッセージを送信し続けることができます

インポート後、各ユーザーが Braze 対応のアプリを起動すると、Braze はインポートされたプッシュトークンを自動的に Braze ユーザープロファイルに移動し、一時プロファイルをクリーンアップします。

Braze は月に1回、push_token_import フラグが設定されたプッシュトークンのない匿名プロファイルを検索します。匿名プロファイルにプッシュトークンがなくなった場合、Braze はプロファイルを削除します。ただし、匿名プロファイルにまだプッシュトークンがあり、実際のユーザーがそのプッシュトークンを使用してデバイスにまだログインしていないことが示唆される場合、Braze は何も行いません。

詳細については、プッシュトークンの移行を参照してください。

カスタム属性のデータタイプ

次のデータタイプはカスタム属性として保存できます。

オブジェクトの配列の例

このオブジェクトの配列を使用すると、宿泊内の特定の条件に基づいてセグメントを作成し、Liquid テンプレートを使用して各宿泊のデータでメッセージをパーソナライズできます。

1
2
3
4
{"hotel_stays": [
  { "hotel_name": "Ocean View Resort", "check_in_date": "2023-06-15", "nights_stayed": 5 },
  { "hotel_name": "Mountain Lodge", "check_in_date": "2023-09-10", "nights_stayed": 3 }
]}

Braze ユーザープロファイルフィールド

この API によって明示的に設定された言語値は、Braze がデバイスから自動的に受信するロケール情報よりも優先されます。

ユーザー属性リクエストの例

この例には、API 呼び出しあたり合計75個の許可された属性オブジェクトのうち、4個のユーザー属性オブジェクトが含まれています。

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
POST https://YOUR_REST_API_URL/users/track
Content-Type: application/json
Authorization: Bearer YOUR-REST-API-KEY
{
  "attributes" : [
    {
      "external_id" : "user1",
      "first_name" : "Jon",
      "has_profile_picture" : true,
      "dob": "1988-02-14",
      "music_videos_favorited" : { "add" : [ "calvinharris-summer" ], "remove" : ["nickiminaj-anaconda"] }
    },
    {
      "external_id" : "user2",
      "first_name" : "Jill",
      "has_profile_picture" : false,
      "push_tokens": [{"app_id": "Your App Identifier", "token": "abcd", "device_id": "optional_field_value"}]

    },
    {
      "user_alias" : { "alias_name" : "device123", "alias_label" : "my_device_identifier"},
      "first_name" : "Alice",
      "has_profile_picture" : false
    },
    {
      "external_id": "user3",
      "subscription_groups" : [{"subscription_group_id" : "subscription_group_identifier", "subscription_state" : "subscribed"}]
    }
  ]
}

プッシュトークンの移行

Braze を統合する前に、自社または他のプロバイダー経由でプッシュ通知を送信していた場合、プッシュトークンの移行により、プッシュトークンを登録済みのユーザーにプッシュ通知を送信し続けることができます。

SDK を介した自動移行

Braze SDK を統合すると、オプトインしたユーザーのプッシュトークンは、次回アプリを開いたときに自動的に移行されます。それまでは、これらのユーザーに Braze 経由でプッシュ通知を送信することはできません。

あるいは、プッシュトークンを手動で移行することで、ユーザーへの再エンゲージをより迅速に行うことができます。

Web トークンに関する考慮事項

Web プッシュトークンの性質上、Web プッシュを実装する際には以下の点を考慮してください。

API を使用した手動移行

手動プッシュトークン移行は、以前に作成されたこれらのキーを API を通じて Braze プラットフォームにインポートするプロセスです。

users/track エンドポイントを使用して、iOS（APNs）および Android（FCM）トークンをプラットフォームにプログラムで移行します。識別されたユーザー（関連する external ID を持つユーザー）と匿名ユーザー（external ID を持たないユーザー）の両方を移行できます。

プッシュトークン移行時にアプリの app_id を指定し、適切なプッシュトークンを適切なアプリに関連付けます。各アプリ（iOS、Android など）にはそれぞれ app_id があり、API Keys ページの Identification セクションで確認できます。必ず正しいプラットフォームの app_id を使用してください。

• external id present
• external id missing

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-API-KEY-HERE' \
--data-raw '{
  "attributes" : [
    {
      "push_token_import" : false,
      "external_id": "example_external_id",
      "country": "US",
      "language": "en",
      "YOUR_CUSTOM_ATTRIBUTE": "YOUR_VALUE",
      "push_tokens": [
        {"app_id": "APP_ID_OF_OS", "token": "PUSH_TOKEN_STRING"}
      ]
    }
  ]
}'

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
curl --location --request POST 'https://rest.iad-01.braze.com/users/track' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR-API-KEY-HERE' \
--data-raw '{
  "attributes": [
    {
      "push_token_import" : true,
      "email": "[email protected]",
      "country": "US",
      "language": "en",
      "YOUR_CUSTOM_ATTRIBUTE": "YOUR_VALUE",
      "push_tokens": [
        {"app_id": "APP_ID_OF_OS", "token": "PUSH_TOKEN_STRING", "device_id": "DEVICE_ID"}
      ]
    },

    {
      "push_token_import" : true,
      "email": "[email protected]",
      "country": "US",
      "language": "en",
      "YOUR_CUSTOM_ATTRIBUTE_1": "YOUR_VALUE",
      "YOUR_CUSTOM_ATTRIBUTE_2": "YOUR_VALUE",
      "push_tokens": [
        {"app_id": "APP_ID_OF_OS", "token": "PUSH_TOKEN_STRING", "device_id": "DEVICE_ID"}
      ]
    }
  ]
}'

Android のプッシュトークンをインポートする

Braze SDK の統合が完了する前に Android プッシュ通知をユーザーに送信する必要がある場合は、キーと値のペアを使用してプッシュ通知を検証します。

プッシュペイロードを処理し表示するレシーバーが必要です。プッシュペイロードをレシーバーに通知するには、必要なキーと値のペアをプッシュキャンペーンに追加します。これらのペアの値は、Braze の前に使用していた特定のプッシュパートナーによって決まります。