Skip to content

사용자 추적

post

/users/track

core endpoint

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

See me in Postman

필수 구성 요소

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

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

사용량 제한

요청 본문

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

요청 매개변수

요청 예시

이메일 주소로 사용자 프로필 업데이트

/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": "test@braze.com",
            "string_attribute": "fruit",
            "boolean_attribute_1": true,
            "integer_attribute": 26,
            "array_attribute": [
                "banana",
                "apple"
            ]
        }
    ],
    "events": [
        {
            "email": "test@braze.com",
            "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": "test@braze.com",
            "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

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": "example@email.com",
    "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"
        }
      ]
    }
  ]
}'

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

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

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@example.com"
        }
    ],
}'

응답

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

성공 메시지

성공 메시지에는 다음과 같은 응답이 표시됩니다.

1
2
3
4
5
6

{
  "message": "success",
  "attributes_processed": (optional, integer), if attributes are included in the request, this will return an integer of the number of external_ids with attributes that were queued to be processed,
  "events_processed": (optional, integer), if events are included in the request, this will return an integer of the number of events that were queued to be processed,
  "purchases_processed": (optional, integer), if purchases are included in the request, this will return an integer of the number of purchases that were queued to be processed,
}

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

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

1
2
3
4
5
6
7
8

{
  "message": "success",
  "errors": [
    {
      <minor error message>
    }
  ]
}

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

치명적인 오류가 있는 메시지

메시지에 치명적인 오류가 있는 경우 다음과 같은 응답이 표시됩니다:

1
2
3
4
5
6
7
8

{
  "message": <fatal error message>,
  "errors": [
    {
      <fatal error message>
    }
  ]
}

치명적인 오류 응답 코드

요청에 치명적인 오류가 발생할 경우 반환되는 상태 코드 및 관련 오류 메시지는 치명적인 오류 및 응답을 참조하세요.

“제공된 external_id가 블랙리스트에 포함되어 허용되지 않습니다”라는 오류가 표시되는 경우 요청에 “더미 사용자”가 포함된 것일 수 있습니다. 자세한 내용은 스팸 차단을 참조하세요.

자주 묻는 질문

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

external_id 이 존재하는 경우 외부 ID로 가장 최근에 업데이트된 프로필이 업데이트 우선순위를 갖습니다. external_id 이 존재하지 않는 경우 가장 최근에 업데이트된 프로필이 우선적으로 업데이트됩니다.

이메일 주소가 있는 프로필이 현재 존재하지 않으면 어떻게 되나요?

새 프로필이 생성되고 이메일 전용 사용자가 만들어집니다. 별칭은 생성되지 않습니다. 이메일 필드는 이메일 주소로 사용자 프로필 업데이트 요청 예시에서 설명한 대로 test@braze.com 로 설정됩니다.

기존 사용자 데이터를 가져오기 위해 /users/track을 어떻게 사용합니까?

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

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

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

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

월간 활성 사용자 CY 24-25

월간 활성 사용자 - CY 24-25를 구매한 고객의 경우, Braze는 /users/track 엔드포인트에서 다양한 요금 한도를 관리합니다:

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

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

Github   GitHub 에서 이 페이지를 편집합니다.
이 페이지가 얼마나 도움이 되었나요?
New Stuff!