사용자 속성 오브젝트

속성 오브젝트에 필드가 포함된 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
25
26
27
28
29
30

{
  // 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" : "Alex",
  "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" ]},
  // Array of objects custom attribute
  "my_array_of_objects_attribute": [{"key": "value"}, {"key": "value"}],
  // Adding to an array of objects (nested custom attribute syntax)
  "my_array_of_objects_attribute": { "$add": [{"key": "value"}] },
  // Removing from an array of objects (nested custom attribute syntax)
  "my_array_of_objects_attribute": { "$remove": [{"$identifier_key": "key", "$identifier_value": "value"}] },
}

• 외부 사용자 ID
• 사용자 별칭

참고

일반 배열 커스텀 속성에는 add 및 remove($ 없이)를 사용하세요.

오브젝트 배열(중첩 커스텀 속성)의 경우 /users/track 요청 페이로드에서 $add, $remove, $update를 사용하세요. 이러한 연산자는 식별자($identifier_key 및 $identifier_value)를 매칭하여 오브젝트 수준의 변경 사항을 적용하며, $new_object를 사용한 제자리 업데이트를 지원합니다.

배열의 나머지 상태는 그대로 유지하면서 기존 배열 안의 오브젝트를 추가, 제거 또는 업데이트해야 할 때 이 형식을 사용하세요. 전체 요청 예시는 오브젝트 배열 API 예시 및 오브젝트 배열 SDK 예시를 참조하세요.

프로필 속성을 제거하려면 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가 새 고객 프로필을 생성합니다.

참고

/users/track 엔드포인트를 통해 별칭 전용 고객 프로필을 생성하는 경우 _update_existing_only를 false로 설정해야 합니다. 이 값을 생략하면 Braze는 별칭 전용 프로필을 생성하지 않습니다.

푸시 토큰 가져오기

Braze로 푸시 토큰을 가져오기 전에 정말 필요한지 다시 한번 확인하세요. Braze SDK를 적용하면 SDK가 푸시 토큰을 자동으로 처리하므로 API를 통해 업로드할 필요가 없습니다.

API를 통해 업로드해야 하는 경우, 식별된 사용자 또는 익명 사용자에 대해 업로드할 수 있습니다. 즉, external_id가 있어야 하거나 익명 사용자의 push_token_import 플래그가 true로 설정되어 있어야 합니다.

참고

다른 시스템에서 푸시 토큰을 가져올 때는 external_id를 항상 사용할 수 있는 것은 아닙니다. Braze로 전환하는 동안 이러한 사용자와의 커뮤니케이션을 유지하려면 push_token_import를 true로 지정하여 external_id를 제공하지 않고도 익명 사용자의 레거시 토큰을 가져올 수 있습니다.

push_token_import를 true로 지정하는 경우:

• external_id 및 braze_id는 지정하지 않아야 합니다
• 속성 오브젝트에는 푸시 토큰이 반드시 포함되어야 합니다
• 토큰이 Braze에 이미 존재하면 요청이 무시됩니다. 그렇지 않으면 Braze가 각 토큰에 대해 임시 익명 고객 프로필을 생성하여 해당 사용자에게 계속 메시지를 보낼 수 있도록 합니다

가져오기 후 각 사용자가 Braze가 적용된 버전의 앱을 실행하면, Braze는 가져온 푸시 토큰을 해당 사용자의 Braze 고객 프로필로 자동 이동하고 임시 프로필을 정리합니다.

Braze는 한 달에 한 번 push_token_import 플래그가 있지만 푸시 토큰이 없는 익명 프로필을 확인합니다. 익명 프로필에 더 이상 푸시 토큰이 없으면 Braze는 해당 프로필을 삭제합니다. 그러나 익명 프로필에 여전히 푸시 토큰이 있다면 실제 사용자가 아직 해당 푸시 토큰이 있는 기기에 로그인하지 않았음을 의미하므로 Braze는 아무 작업도 하지 않습니다.

자세한 내용은 푸시 토큰 마이그레이션을 참조하세요.

커스텀 속성 데이터 유형

다음 데이터 유형을 커스텀 속성으로 저장할 수 있습니다.

팁

커스텀 이벤트와 커스텀 속성을 언제 사용해야 하는지에 대한 안내는 커스텀 이벤트 및 커스텀 속성을 참조하세요.

오브젝트 배열 예시

이 오브젝트 배열을 사용하면 숙박 정보 내의 특정 기준에 따라 Segment를 만들고, 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 }
]}

$add, $remove, $update를 사용하는 오브젝트 배열 예시는 오브젝트 배열 API 예시 및 오브젝트 배열 SDK 예시를 참조하세요.

Braze 고객 프로필 필드

중요

다음 고객 프로필 필드는 대소문자를 구분하므로 반드시 소문자로 참조하세요.

팁

카테고리별로 정리되어 있고 SDK, API, CSV, Cloud Data Ingestion에 대한 안내가 포함된 표준 속성 참조 자료는 표준 속성을 참조하세요.

이 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" : "Alex",
      "has_profile_picture" : true,
      "dob": "1988-02-14",
      "music_videos_favorited" : { "add" : [ "calvinharris-summer" ], "remove" : ["nickiminaj-anaconda"] }
    },
    {
      "external_id" : "user2",
      "first_name" : "Lee",
      "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" : "Yuri",
      "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가 없는 사용자) 모두 마이그레이션할 수 있습니다.

참고

Braze는 가져온 푸시 토큰을 앱과 환경에 대한 유효한 포그라운드 푸시 토큰으로 간주합니다.

iOS 토큰을 가져올 때, Braze는 해당 토큰에 대한 Apple Push Notification service(APNs) 게이트웨이(development 또는 production)를 저장하지 않습니다. Braze는 앱에 구성된 게이트웨이를 통해 이러한 토큰으로 전송합니다. 다른 환경용으로 생성된 토큰인 경우, APNs가 BadDeviceToken으로 거부하며 전송이 반송됩니다.

Braze는 나중에 SDK가 동일한 토큰을 등록하고 게이트웨이를 보고하는 경우에만 해당 토큰에 대한 게이트웨이를 저장합니다.

푸시 토큰 마이그레이션 중에 앱의 app_id를 지정하여 적절한 푸시 토큰을 적절한 앱에 연결하세요. 각 앱(iOS, Android 등)에는 고유한 app_id가 있으며, API 키 페이지의 식별 섹션에서 확인할 수 있습니다. 반드시 올바른 플랫폼의 app_id를 사용하세요.

중요

API를 통해 웹 푸시 토큰을 마이그레이션할 수는 없습니다. 웹 푸시 토큰은 다른 플랫폼과 동일한 스키마를 따르지 않기 때문입니다.

웹 푸시 토큰을 프로그래밍 방식으로 마이그레이션하려고 하면 다음과 같은 오류가 표시될 수 있습니다. Received '400: Invalid subscription auth' sending to 'https://fcm.googleapis.com/fcm/send

API 마이그레이션 대신 SDK를 통합하여 토큰 기반이 자연스럽게 다시 채워지도록 하는 것을 권장합니다.

• 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"}
      ]
    }
  ]
}'

iOS 푸시 토큰 가져오기

/users/track으로 iOS 푸시 토큰을 마이그레이션하면 푸시 토큰에 gateway 필드가 설정되지 않습니다. Braze는 API를 통해 가져온 토큰을 유효한 포그라운드 푸시 토큰으로 간주하지만, 토큰이 어떤 APN 환경에 속하는지는 판단할 수 없습니다.

게이트웨이 필드가 없으면 Braze는 푸시 알림을 보낼 때 앱에 설정된 대체 환경 설정을 사용합니다. 토큰의 실제 환경이 설정된 대체 환경과 다르면 BadDeviceToken 오류가 발생할 수 있습니다. 예를 들어, 프로덕션 게이트웨이를 통해 보낸 개발 토큰은 실패합니다.

전송 문제를 방지하려면 다음을 따르세요.

• Braze 대시보드의 앱 환경 설정이 가져오는 토큰과 일치하는지 확인하세요.
• 프로덕션 앱의 경우 프로덕션 토큰만 가져오세요.
• 테스트 환경의 경우 앱 구성과 가져온 토큰이 모두 개발 환경을 사용하는지 확인하세요.

참고

Braze SDK를 통해 등록된 토큰에는 게이트웨이 필드가 자동으로 포함됩니다. SDK가 앱의 인타이틀먼트에서 환경을 감지하기 때문입니다.

Android 푸시 토큰 가져오기

중요

다음 고려 사항은 Android 앱에만 적용됩니다. iOS 앱은 푸시를 표시하는 프레임워크가 하나뿐이고, Braze에 필요한 푸시 토큰과 인증서가 있으면 푸시 알림이 즉시 렌더링되므로 이 단계가 필요하지 않습니다.

Braze SDK 통합이 완료되기 전에 사용자에게 Android 푸시 알림을 보내야 한다면, 키-값 페어를 사용하여 푸시 알림을 검증하세요.

푸시 페이로드를 처리하고 표시할 수신기가 있어야 합니다. 수신기에 푸시 페이로드를 알리려면 푸시 Campaign에 필요한 키-값 페어를 추가하세요. 이러한 페어의 값은 Braze 이전에 사용하던 푸시 파트너에 따라 달라집니다.

참고

일부 푸시 알림 공급자의 경우, 키-값 페어가 올바르게 해석될 수 있도록 Braze에서 키-값 페어를 평탄화해야 합니다. 특정 Android 앱의 키-값 페어를 평탄화하려면 고객 성공 매니저에게 문의하세요.

자주 묻는 질문

스팸으로 처리되었거나 메시징이 차단된 사용자는 어떻게 찾나요?

Braze 대시보드에는 별도의 스팸 목록이 없습니다. Braze는 세션이 500만 개를 초과하거나, 고유 커스텀 이벤트 이름이 20,000개를 초과하거나, 구매에 포함된 고유 제품 이름이 20,000개를 초과하는 개별 고객 프로필(“더미 사용자”)을 차단합니다. 차단된 프로필에 대해서는 SDK와 REST API로 들어오는 모든 데이터의 수집이 중단됩니다. 식별자가 차단된 경우 /users/track에서 "provided external_id is blacklisted and disallowed" 오류가 반환될 수 있습니다. 이 문구는 API 응답을 그대로 옮긴 것입니다.

세션 과다로 차단된 프로필을 찾으려면 다음 순서로 진행하세요.

1. 세션 수 필터를 5,000,000 초과로 설정해 Segment를 생성합니다.
2. 해당 Segment를 CSV로 내보냅니다.
3. 인게이지먼트 > 사용자 검색 또는 /users/export/ids 엔드포인트에서 프로필 필드를 대조해 확인합니다.

고유 커스텀 이벤트 이름이나 제품 이름 기준으로 쓸 수 있는 필터는 없습니다. 이런 이유로 차단된 프로필을 확인하려면 Braze 계정 매니저에게 문의하세요. 자세한 내용은 스팸 차단을 참조하세요.