사용자 만들기 및 업데이트

이 엔드포인트를 사용하여 커스텀 이벤트 및 구매를 기록하고 고객 프로필 속성을 업데이트하세요.

필수 조건

이 엔드포인트를 사용하려면 users.track 권한이 있는 API 키가 필요합니다.

서버 간 호출에 API를 사용하는 고객이 방화벽 뒤에 있는 경우 rest.iad-01.braze.com을 허용 목록에 추가해야 할 수 있습니다.

사용량 제한

Braze는 이 엔드포인트에 3초당 3,000건의 요청이라는 기본 속도 제한을 적용합니다. 각 /users/track 요청은 attributes, events, purchases를 합산하여 최대 75개의 오브젝트를 포함할 수 있습니다. 각 오브젝트는 한 명의 사용자를 업데이트할 수 있습니다. 단일 고객 프로필은 여러 오브젝트로 업데이트할 수 있습니다.

월간 활성 사용자 CY 24-25, Universal MAU, Web MAU 또는 Mobile MAU를 구매한 고객에게는 추가 사용량 제한이 적용됩니다. 자세한 내용은 월간 활성 사용자 CY 24-25 제한을 참조하세요.

자세한 내용은 API 사용량 제한을 참조하세요. 한도 증액이 필요하시면 고객 성공 매니저에게 문의하세요.

요청 본문

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

요청 매개변수

식별자 확인

각 요청 오브젝트에는 하나 이상의 식별자가 포함되어야 합니다. 다음 표에서는 Braze가 고객 프로필 조회에 사용할 식별자를 결정하는 방법을 설명합니다.

기본 식별자가 있는 경우 동일한 요청 오브젝트의 email 또는 phone 값은 사용자 조회를 위한 식별자가 아닌 프로필 속성으로 처리됩니다. 예를 들어, 요청에 external_id와 email이 모두 포함된 경우:

• Braze는 external_id로 고객 프로필을 조회합니다.
• email 값은 확인된 프로필의 속성으로 설정(또는 업데이트)됩니다.

요청 예시

이메일 주소로 고객 프로필 업데이트

/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": "[email protected]",
            "string_attribute": "fruit",
            "boolean_attribute_1": true,
            "integer_attribute": 26,
            "array_attribute": [
                "banana",
                "apple"
            ]
        }
    ],
    "events": [
        {
            "email": "[email protected]",
            "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": "[email protected]",
            "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
26
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": "[email protected]",
    "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",
          "use_double_opt_in_logic": true
        }
      ]
    }
  ]
}'

별칭 전용 사용자 만들기 요청 예시

/users/track 엔드포인트를 사용하여 요청 본문에서 _update_existing_only 키를 false 값으로 설정하면 별칭 전용 사용자를 만들 수 있습니다. 이 값을 생략하면 Braze는 별칭 전용 고객 프로필을 생성하지 않습니다. 별칭 전용 사용자를 사용하면 해당 별칭을 가진 프로필이 하나만 존재하게 됩니다. 이는 통합을 구축할 때 특히 유용하며, Braze가 중복된 고객 프로필을 생성하는 것을 방지할 수 있습니다.

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

응답

앞서 언급한 API 요청을 사용할 때 성공 메시지, 치명적이지 않은 오류가 있는 성공 메시지, 심각한 오류가 있는 메시지 등 세 가지 일반적인 응답 중 하나를 받게 됩니다.

성공 메시지

성공 메시지는 다음과 같은 응답을 반환합니다:

1
2
3
4
5
6
{
  "message": "success",
  "attributes_processed": (optional, integer), if attributes are included in the request, this returns an integer of the number of external_ids with attributes that Braze queued for processing,
  "events_processed": (optional, integer), if events are included in the request, this returns an integer of the number of events that Braze queued for processing,
  "purchases_processed": (optional, integer), if purchases are included in the request, this returns an integer of the number of purchases that Braze queued for processing,
}

치명적이지 않은 오류가 있는 성공 메시지

메시지는 성공했지만 긴 이벤트 목록 중 하나의 잘못된 이벤트 오브젝트와 같이 치명적이지 않은 오류가 있는 경우 다음과 같은 응답을 받게 됩니다:

1
2
3
4
5
6
7
8
{
  "message": "success",
  "errors": [
    {
      <minor error message>
    }
  ]
}

성공 메시지의 경우 Braze는 errors 배열의 오류에 영향을 받지 않는 모든 데이터를 계속 처리합니다.

심각한 오류가 있는 메시지

메시지에 심각한 오류가 있는 경우 다음과 같은 응답을 받게 됩니다:

1
2
3
4
5
6
7
8
{
  "message": <fatal error message>,
  "errors": [
    {
      <fatal error message>
    }
  ]
}

심각한 오류 응답 코드

요청에 심각한 오류가 발생할 경우 Braze가 반환하는 상태 코드 및 관련 오류 메시지는 심각한 오류 및 응답을 참조하세요.

“provided external_id is blacklisted and disallowed”라는 오류가 표시되는 경우 요청에 “더미 사용자”가 포함된 것일 수 있습니다. 자세한 내용은 스팸 차단을 참조하세요.

엔드포인트별 오류

다음 오류는 /users/track 엔드포인트에 한정된 것이며 응답의 errors 배열에 반환됩니다. 이를 사용하여 요청의 개별 오브젝트 관련 문제를 해결하세요.

자주 묻는 질문

동일한 이메일 주소를 가진 프로필이 여러 개 발견되면 어떻게 되나요?

external_id가 존재하는 경우, Braze는 외부 ID가 있는 가장 최근에 업데이트된 프로필을 우선적으로 업데이트합니다. external_id가 존재하지 않는 경우 Braze는 가장 최근에 업데이트된 프로필을 우선적으로 업데이트합니다.

이메일 주소가 포함된 프로필이 없는 경우 어떻게 되나요?

Braze는 이메일 주소로 고객 프로필 업데이트 요청 예시에 나와 있는 것처럼 프로필과 이메일 전용 사용자를 생성하고 이메일 필드를 [email protected]으로 설정합니다. Braze는 별칭을 만들지 않습니다.

기존 사용자 데이터를 가져오기 위해 /users/track을 어떻게 사용하나요?

아직 모바일 앱을 사용하지 않은 사용자를 위해 Braze API를 통해 데이터를 제출하여 고객 프로필을 생성할 수 있습니다. 이후 사용자가 애플리케이션을 사용하면 SDK를 통해 식별된 후의 모든 정보가 API 호출로 생성한 기존 고객 프로필과 병합됩니다. 식별 전에 SDK에 의해 익명으로 기록된 모든 사용자 행동은 기존 API 생성 고객 프로필과 병합되면 손실됩니다.

세분화 툴에는 앱 참여 여부와 관계없이 이러한 사용자가 포함됩니다. 사용자 API를 사용하여 업로드한 사용자 중 아직 앱에 참여하지 않은 사용자를 제외하려면 Session Count > 0 필터를 추가하세요.

중복 고객 프로필 생성을 방지하려면 어떻게 해야 하나요?

중복 프로필은 요청에 기존 프로필과 일치하지 않는 기본 식별자(예: external_id)가 포함되어 있고, 동시에 기존 프로필과 일치하는 email 또는 phone 값이 포함된 경우 발생할 수 있습니다. 기본 식별자가 사용자 조회에 사용되므로, Braze는 인식되지 않는 external_id에 대해 기존 이메일 전용 또는 전화번호 전용 프로필을 업데이트하는 대신 새 프로필을 생성합니다.

중복을 방지하려면:

• 이메일 전용 또는 전화번호 전용 프로필에서 식별된 프로필로 사용자를 전환할 때, /users/track에 둘 다 보내는 대신 /users/identify 엔드포인트를 사용하여 기존 프로필에 external_id를 할당하세요.
• 중복이 이미 존재하는 경우 /users/merge 엔드포인트를 사용하여 병합하세요.

/users/track에서는 중복 이벤트를 어떻게 처리하나요?

이벤트 배열의 각 이벤트 오브젝트는 지정된 시간에 사용자가 수행한 커스텀 이벤트의 단일 발생을 나타냅니다. 즉, Braze에 수집된 각 이벤트에는 고유한 이벤트 ID가 있으므로 “중복” 이벤트는 별도의 고유한 이벤트로 취급됩니다.

/users/track에서는 잘못된 중첩 커스텀 속성을 어떻게 처리하나요?

중첩 커스텀 속성에 유효하지 않은 값(예: 잘못된 시간 형식 또는 null 값)이 포함된 경우 Braze는 요청의 모든 중첩 커스텀 속성 업데이트를 처리에서 삭제합니다. 이는 해당 특정 속성 내의 모든 중첩 구조에 적용됩니다. 성공적인 처리를 위해 전송하기 전에 중첩 커스텀 속성 내의 모든 값이 유효한지 확인하세요.

월간 활성 사용자 CY 24-25, 유니버설 MAU, 웹 MAU 및 모바일 MAU

새 요금제를 사용하는 고객의 경우 회사 수준에서 사용량 제한이 적용됩니다. 고객은 워크스페이스별 시간당 사용량 제한을 설정할 수 있지만 버스트 제한은 여전히 모든 워크스페이스 간에 공유됩니다.

월간 활성 사용자 CY 24-25, 유니버설 MAU, 웹 MAU 또는 모바일 MAU를 구매한 고객의 경우 Braze는 /users/track 엔드포인트에서 다양한 사용량 제한을 관리합니다:

• 시간당 사용량 제한은 계정의 예상 데이터 수집 활동에 따라 설정되며, 이는 구매한 월간 활성 사용자 수, 업종, 계절성 또는 기타 요인에 따라 달라질 수 있습니다.
• 시간당 제한 외에도 Braze는 3초마다 전송할 수 있는 요청 수에 버스트 제한을 적용합니다.
• 각 요청은 속성, 이벤트 또는 구매 오브젝트에 걸쳐 최대 75개의 업데이트를 일괄 처리할 수 있습니다.

예상 수집량에 따른 현재 제한은 대시보드의 설정 > API 및 식별자 > API 사용량 대시보드에서 확인할 수 있습니다. 시스템 안정성을 보호하거나 계정의 데이터 처리량 증가를 허용하기 위해 사용량 제한을 수정할 수 있습니다. 시간당 또는 초당 요청 제한 및 비즈니스 요구 사항에 대한 질문이나 우려 사항이 있는 경우 Braze 고객지원 또는 고객 성공 매니저에게 문의하세요.

월간 활성 사용자 CY 24-25, 유니버설 MAU, 웹 MAU 및 모바일 MAU에 대한 사용량 제한 헤더

사용량 제한이 적용되지 않은 모든 응답(예: 429가 아닌 응답)에는 클라이언트에 시간당 사용량 제한 기간의 상태를 나타내는 다음 HTTP 응답 헤더가 포함됩니다. 이 헤더를 사용하여 요청 비율을 관리하세요:

HTTP 429 오류가 발생하면 RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset 헤더는 반환되지 않습니다. 오류가 발생하면 해당 헤더는 요청을 다시 시작할 수 있는 시간(초)을 나타내는 정수를 반환하는 X-Ratelimit-Retry-After 헤더로 대체됩니다.