사용자 속성 오브젝트

속성 오브젝트의 필드가 포함된 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가 적용되면 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(APNs) 및 Android(FCM) 토큰을 프로그래밍 방식으로 플랫폼에 마이그레이션합니다. 식별된 사용자(연결된 외부 ID가 있는 사용자)와 익명 사용자(외부 ID가 없는 사용자) 모두 마이그레이션할 수 있습니다.

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

중요

API를 통해 웹 푸시 토큰을 마이그레이션하는 것은 불가능합니다. 웹 푸시 토큰은 다른 플랫폼과 동일한 스키마를 따르지 않기 때문입니다.

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

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

• 외부 id 있음
• 외부 id 없음

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를 통해 가져온 토큰이 유효한 포그라운드 푸시 토큰이라고 가정하지만, 해당 토큰이 어떤 APNs 환경에 속하는지는 판단할 수 없습니다.

게이트웨이 필드가 없으면 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 응답에서 그대로 가져온 것입니다. 과도한 세션으로 차단된 프로필을 찾으려면 세션 수 필터를 5,000,000 초과로 설정하여 Segment를 생성하고, 해당 Segment를 CSV로 내보낸 다음, 인게이지먼트 > 사용자 검색에서 프로필 필드를 교차 확인하거나 /users/export/ids 엔드포인트를 사용하여 확인합니다. 고유 커스텀 이벤트 이름이나 제품 이름에 대한 동등한 필터는 없으므로, 해당 사유로 차단된 프로필을 확인하려면 Braze 계정 매니저에게 문의하세요. 자세한 내용은 스팸 차단을 참조하세요.