사용자 속성 오브젝트

속성 오브젝트의 필드가 포함된 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 같은 일부 필드는 고객 프로필에 추가한 후에는 제거할 수 없습니다.

식별자 확인

익명 푸시 토큰 가져오기를 수행하지 않는 한, 각 사용자 속성 오브젝트에는 최소한 하나의 식별자(external_id, user_alias, braze_id, email 또는 phone)가 포함되어야 합니다. 가능한 경우, 어떤 고객 프로필이 업데이트되거나 생성되는지에 대한 모호성을 피하기 위해 오브젝트당 하나의 식별자만 포함하세요.

식별자를 사용할 때 다음 사항을 염두에 두세요:

• 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는 매달 한 번 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를 통해 해당 사용자에게 푸시 알림을 보낼 수 없습니다.

또는 푸시 토큰을 수동으로 마이그레이션하여 사용자의 재참여를 더욱 신속하게 유도할 수 있습니다.

웹 토큰 고려 사항

웹 푸시 토큰의 특성상 웹용 푸시를 구현할 때 다음 사항을 고려해야 합니다:

API를 통한 수동 마이그레이션

수동 푸시 토큰 마이그레이션은 API를 통해 이전에 생성한 키를 Braze 플랫폼으로 가져오는 프로세스입니다.

users/track 엔드포인트를 사용하여 프로그래밍 방식으로 iOS(APN) 및 Android(FCM) 토큰을 플랫폼으로 마이그레이션합니다. 식별된 사용자(연결된 외부 ID가 있는 사용자)와 익명 사용자(외부 ID가 없는 사용자)를 모두 마이그레이션할 수 있습니다.

푸시 토큰 마이그레이션 중에 앱의 app_id를 지정하여 적절한 푸시 토큰을 적절한 앱에 연결합니다. 각 앱(iOS, Android 등)에는 API 키 페이지의 식별 섹션에서 찾을 수 있는 고유한 app_id가 있습니다. 올바른 플랫폼의 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 이전에 사용한 특정 푸시 파트너에 따라 달라집니다.