Skip to content

사용자 생성 및 업데이트 (동기)

post

/users/track/sync

core endpoint

이 엔드포인트를 사용하여 커스텀 이벤트와 구매를 기록하고 사용자 프로필 속성을 동기식으로 업데이트할 수 있습니다. 이 엔드포인트는 비동기식으로 사용자 프로필을 업데이트하는 /users/track 엔드포인트와 유사하게 작동합니다.

동기 및 비동기 API 호출

비동기 호출에서 API는 상태 코드 201을 반환하여 요청이 성공적으로 수신되고 이해되었으며 수락되었음을 나타냅니다. 그러나 이것이 요청이 완전히 완료되었다는 것을 의미하지는 않습니다.

동기 호출에서 API는 상태 코드 201을 반환하여 요청이 성공적으로 수신되고 이해되었으며 수락되고 완료되었음을 나타냅니다. 호출 응답은 작업 결과로 선택된 사용자 프로필 필드를 보여줍니다.

이 엔드포인트는 /users/track 엔드포인트보다 사용량 제한이 낮습니다(아래 사용량 제한 참조). 각 /users/track/sync 요청에는 하나의 이벤트 오브젝트, 하나의 속성 오브젝트 또는 하나의 구매 오브젝트만 포함할 수 있습니다. 이 엔드포인트는 동기 호출이 필요한 사용자 프로필 업데이트를 위해 예약해야 합니다. 건전한 구현을 위해 /users/track/sync와 /users/track을 함께 사용하는 것을 권장합니다.

예를 들어 동일한 사용자에 대해 짧은 시간 동안 연속적인 요청을 보내는 경우 비동기식 /users/track 엔드포인트에서는 경합 조건이 발생할 수 있지만, /users/track/sync 엔드포인트를 사용하면 2XX 응답을 받은 후 각 요청을 순차적으로 보낼 수 있습니다.

필수 조건

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

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

사용량 제한

모든 고객에 대해 이 엔드포인트에 분당 500건의 기본 속도 제한을 적용합니다. 각 /users/track/sync 요청에는 최대 하나의 이벤트 오브젝트, 하나의 속성 오브젝트 또는 하나의 구매 오브젝트가 포함될 수 있습니다. 각 오브젝트(이벤트, 속성 및 구매 배열)는 각각 한 명의 사용자를 업데이트할 수 있습니다.

요청 본문

1
2

Content-Type: application/json
Authorization: Bearer YOUR_REST_API_KEY

1
2
3
4
5

{
  "attributes": (optional, one attributes object),
  "events": (optional, one event object),
  "purchases": (optional, one purchase object),
}

요청 매개변수

응답

이 엔드포인트의 요청 매개변수를 사용할 때 성공 메시지 또는 심각한 오류가 있는 메시지 중 하나의 응답을 받게 됩니다.

성공 메시지

성공 메시지는 Braze가 업데이트한 사용자 프로필 데이터에 대한 정보를 포함하는 다음 응답을 반환합니다.

1
2
3
4
5
6
7

{
    "users": (optional, object), the identifier of the user in the request. May be empty if no users are found and _update_existing_only key is set to true,
        "custom_attributes": (optional, object), the custom attributes as a result of the request. Braze lists only custom attributes from the request,
        "custom_events": (optional, object), the custom events as a result of the request. Braze lists only custom events from the request,
        "purchase_events": (optional, object), the purchase events as a result of the request. Braze lists only purchase events from the request,
    },
    "message": "success"

심각한 오류가 있는 메시지

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

1
2
3
4
5
6
7
8

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

요청 및 응답 예시

외부 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/sync' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_REST_API_KEY' \
--data-raw '{
    "attributes": [
        {
            "external_id": "xyz123",
            "string_attribute": "fruit",
            "boolean_attribute_1": true,
            "integer_attribute": 25,
            "array_attribute": [
                "banana",
                "apple"
            ]
        }
    ]
}'

응답

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

{
    "users": [
        {
            "external_id": "xyz123",
            "custom_attributes": {
                "string_attribute": "fruit",
                "boolean_attribute_1": true,
                "integer_attribute": 25,
                "array_attribute": [
                    "banana",
                    "apple",
                ]
            }
        }
    ],
    "message": "success"
}

이메일로 커스텀 이벤트 업데이트

요청

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

curl --location --request POST 'https://rest.iad-01.braze.com/users/track/sync' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_REST_API_KEY' \
--data-raw '{
    "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"
                    }
                ]
            }
        }
    ]
}'

응답

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

{
    "users": [
        {
            "email": "[email protected]",
            "custom_events": [
                {
                "name": "rented_movie",
                "first": "2022-01-001T00:00:00.000Z",
                "last": "2022-12-06T18:20:45.000Z",
                "count": 10
                }
            ]
        }
    ],
    "message": "success"
}

사용자 별칭으로 구매 이벤트 업데이트

요청

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

curl --location --request POST 'https://rest.iad-01.braze.com/users/track/sync' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_REST_API_KEY' \
--data-raw '{
  "purchases" : [
    {
      "user_alias" : {
          "alias_name" : "device123",
          "alias_label" : "my_device_identifier"
      }
      "app_id" : "11ae5b4b-2445-4440-a04f-bf537764c9ad",
      "product_id" : "Completed Order",
      "currency" : "USD",
      "price" : 219.98,
      "time" : "2022-12-06T19:20:45+01:00",
      "properties" : {
          "products" : [
            {
              "name": "Monitor",
              "category": "Gaming",
              "product_amount": 19.99
            },
            {
              "name": "Gaming Keyboard",
              "category": "Gaming ",
              "product_amount": 199.99
            }
          ]
      }
   }
  ]
}'

응답

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

{
    "users": [
        {
          "user_alias" : {
            "alias_name" : "device123",
            "alias_label" : "my_device_identifier"
          },
          "purchase_events": [
                {
                "product_id": "Completed Order",
                "first": "2013-07-16T19:20:30+01:00",
                "last": "2022-12-06T18:20:45.000Z",
                "count": 3
                }
            ]
        }
    ],
    "message": "success"
}

자주 묻는 질문

비동기식 엔드포인트와 동기식 엔드포인트 중 무엇을 사용해야 하나요?

대부분의 프로필 업데이트의 경우 /users/track 엔드포인트가 더 높은 사용량 제한과 요청을 배치할 수 있는 유연성 덕분에 가장 적합합니다. 그러나 /users/track/sync 엔드포인트는 동일한 사용자에 대한 빠른 연속 요청으로 인해 경합 조건이 발생하는 경우 유용합니다.

응답 시간이 /users/track 엔드포인트와 다른가요?

동기 호출에서는 API가 Braze가 요청을 완료할 때까지 기다린 후 응답을 반환합니다. 그 결과, 동기 요청은 평균적으로 /users/track에 대한 비동기 요청보다 더 오래 걸립니다. 대부분의 요청에 대해 몇 초 내에 응답을 받을 수 있습니다.

동시에 여러 요청을 보낼 수 있나요?

예, 요청이 서로 다른 사용자를 대상으로 하거나 각 요청이 한 사용자에 대해 서로 다른 속성, 이벤트, 구매를 업데이트하는 경우에 가능합니다.

동일한 속성, 이벤트 또는 구매에 대해 한 사용자에게 여러 요청을 보내는 경우, Braze는 경합 조건이 발생하지 않도록 각 요청 사이에 성공 응답을 기다릴 것을 권장합니다.

응답 값이 원래 요청의 값과 일치하지 않는 이유는 무엇인가요?

요청이 완료되었더라도 커스텀 속성 값이 업데이트되지 않았을 수 있습니다. 이는 커스텀 속성 업데이트가 최대 문자 수를 초과하거나, 배열 제한을 초과하거나, 사용자가 Braze에 존재하지 않는데 _update_existing_only = true로 설정된 경우에 발생할 수 있습니다.

이러한 경우 응답을 요청이 완료되었지만 원하는 업데이트가 이루어지지 않았다는 표시로 간주하세요. 위에서 설명한 이유를 참고하여 문제를 해결하세요.
New Stuff!