콘텐츠로 건너뛰기
View in Postman (opens in new tab)

사용자 만들기 및 업데이트

post

/users/track

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

Braze는 API를 통해 전달된 데이터를 있는 그대로 처리하므로, 불필요한 데이터 포인트 로깅을 최소화하려면 델타(변경된 데이터)만 전달해야 합니다.

대량으로 사용자를 업데이트해야 하나요?

/users/track/bulk 엔드포인트를 사용하면 더 큰 배치를 전송하고 요청 볼륨을 줄일 수 있습니다.

요청 처리 상태 추적

Braze는 /users/track 요청을 비동기적으로 처리합니다. 성공 응답은 Braze가 요청을 수신하고 처리 대기줄에 넣었다는 의미이지만, 데이터가 아직 고객 프로필에 반영되지 않았을 수 있습니다. 처리가 완료되는 시점을 확인하려면 요청에 group_id를 추가하고 /users/track/status 엔드포인트로 그룹 상태를 확인하세요.

요청 처리 상태를 사용하여 다음을 수행할 수 있습니다:

  • 속성 또는 가입 업데이트에 의존하는 Canvas 또는 Campaign(캠페인)을 트리거하기 전에 해당 업데이트가 프로필에 반영되었는지 확인합니다.
  • 영향을 받는 사용자에게 메시징을 시작하기 전에 백필 또는 가져오기가 완료되었는지 확인합니다.
  • 동의 변경과 같이 우선순위가 높은 업데이트의 처리 완료 기록을 남깁니다.

작동 방식

  1. 관련 요청 집합에 사용할 group_id를 선택합니다. 예를 들어, 백필의 모든 요청에 하나의 group_id를 사용하거나, 확인하려는 단일 요청에 고유한 group_id를 사용합니다.
  2. 각 /users/track 요청 본문의 최상위 레벨에 group_id를 포함합니다. Braze는 수락된 각 요청을 해당 그룹에 포함해 집계합니다.
  3. 해당 group_id로 /users/track/status 엔드포인트를 호출합니다. 그룹의 status가 completed이면 Braze가 그룹의 모든 요청 처리를 완료한 것입니다.

그룹이 completed 상태가 된 후 동일한 group_id로 다른 요청을 보내면, Braze가 새 요청 처리를 완료할 때까지 그룹 상태가 processing으로 돌아갑니다.

Braze는 각 그룹의 상태를 전체 단위로 추적합니다. Braze가 일부 오브젝트를 거부한 요청을 포함하여 그룹의 모든 요청 처리를 완료하면 그룹은 completed 상태가 됩니다. Braze는 거부된 오브젝트를 각 /users/track 응답의 errors 배열에 나열합니다.

상태 추적은 /users/track 엔드포인트에서만 사용할 수 있습니다. Braze는 /users/track/bulk 엔드포인트 또는 /users/track/sync 엔드포인트에 대한 요청 상태는 추적하지 않습니다.

그룹 ID 요구 사항

group_id는 1~128자여야 하며 문자, 숫자, 마침표(.), 밑줄(_), 물결표(~), 하이픈(-)만 포함할 수 있습니다.

그룹 ID의 범위는 워크스페이스 단위입니다. 두 워크스페이스에서 동일한 group_id를 사용하면 서로 별개인 두 그룹을 가리킵니다.

추적하려는 요청 집합마다 새로운 group_id를 사용하세요. group_id를 재사용하면 기존 그룹에 요청이 추가되며, 보존 기간은 연장되지 않습니다.

제한 및 보존

제한 값
보존 24시간

Braze는 group_id가 포함된 첫 번째 요청 시점부터 24시간 동안 그룹 상태를 보존합니다. 보존 기간이 지나면 /users/track/status 엔드포인트는 해당 group_id에 대해 빈 results 배열을 반환합니다.
그룹당 요청 수 6,000,000
워크스페이스당 활성 그룹 수 100,000. 그룹은 보존 기간이 끝날 때까지 활성 상태입니다.
/users/track/status 사용량 제한 워크스페이스당 분당 1,500건의 요청. 이 제한은 /users/track 사용량 제한과 별개입니다.

상태 추적 오류

워크스페이스가 최대 활성 그룹 수에 도달한 경우와 같이 일부 상황에서는 Braze가 요청 상태를 추적할 수 없습니다. 이 경우에도 /users/track 응답은 성공으로 반환되며, Braze는 요청의 속성, 이벤트, 구매를 계속 처리합니다. 응답의 errors 배열에는 Braze가 요청을 추적하지 않는 이유를 설명하는 항목이 포함됩니다:

{
  "message": "success",
  "errors": [
    {
      "type": "request_status_group_full"
    }
  ]
}
오류 유형 설명
invalid_group_id group_id가 문자열이 아니거나, 비어 있거나, 128자를 초과하거나, 허용되지 않는 문자를 포함하고 있습니다. 자세한 내용은 그룹 ID 요구 사항을 참조하세요.
request_status_active_group_limit_exceeded 워크스페이스가 활성 그룹 제한에 도달했습니다. 기존 그룹이 만료될 때까지 기다리거나 group_id 없이 요청을 보내세요.
request_status_group_full 그룹이 요청 제한에 도달했습니다. 추가 요청에는 새 group_id를 사용하세요.
request_status_not_tracked Braze가 요청을 추적할 수 없습니다. 예를 들어, 그룹의 보존 기간이 종료되었거나 워크스페이스에 상태 추적이 활성화되어 있지 않은 경우입니다.

자주 묻는 질문

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

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는 해당 요청의 모든 중첩 커스텀 속성 업데이트를 처리에서 제외합니다. 이는 해당 속성 내의 모든 중첩 구조에 적용됩니다. 처리가 성공적으로 이루어지도록 전송하기 전에 중첩 커스텀 속성 내의 모든 값이 유효한지 확인하세요.

/users/track에 대한 요청은 순서대로 처리되는 것이 보장되나요?

/users/track에 여러 개의 개별 API 호출을 빠르게 연속으로 보내는 경우, Braze는 요청이 전송되거나 수신된 정확한 순서대로 처리된다고 보장할 수 없습니다. 이는 Braze가 속도와 유연성을 극대화하기 위해 비동기 처리를 사용하기 때문입니다.

예를 들어, 동일한 사용자에 대해 몇 초 간격으로 여러 업데이트 요청을 보내면(일부는 null 속성 값, 일부는 유효한 값 포함), null 값이 포함된 요청이 먼저 전송되었더라도 유효한 값이 포함된 요청보다 나중에 처리될 수 있습니다. 그 결과 속성 값이 이전 값으로 되돌아가거나 가장 최근에 보낸 업데이트가 반영되지 않은 것처럼 보일 수 있습니다.

사용자 데이터를 업데이트할 때 경합 조건을 방지하려면:

  • 단일 요청으로 업데이트를 일괄 처리하세요: 연속으로 여러 번 호출하는 대신 한 사용자의 모든 속성 업데이트를 하나의 API 호출에 포함하세요.
  • 요청 사이에 지연을 두세요: 동일한 사용자에 대해 별도로 호출해야 하는 경우, 다음 요청을 보내기 전에 첫 번째 요청의 처리가 완료될 수 있도록 요청 사이에 몇 초의 지연을 두세요.
  • 동일한 필드에 대한 업데이트가 겹치지 않도록 하세요: 두 요청이 동일한 속성을 서로 다른 값으로 업데이트하는 경우, 순서가 뒤바뀔 가능성을 줄이기 위해 해당 업데이트를 하나의 요청으로 보내거나 지연을 두고 분리하세요.
  • 다음 요청 전에 처리 완료를 확인하세요(베타): 첫 번째 요청에 group_id를 포함하고, /users/track/status 엔드포인트가 completed를 반환할 때까지 기다린 후 종속 요청을 보내세요. 자세한 내용은 요청 처리 상태 추적을 참조하세요.

경합 조건 및 모범 사례에 대한 자세한 내용은 경합 조건을 참조하세요.

Braze가 요청 처리를 완료한 시점을 어떻게 알 수 있나요?

/users/track 요청에 group_id를 포함한 다음, 해당 group_id로 /users/track/status 엔드포인트를 호출하세요. 그룹의 status가 completed이면 Braze가 그룹의 모든 요청 처리를 완료한 것입니다. 이 기능은 베타 버전입니다. 자세한 내용은 요청 처리 상태 추적을 참조하세요.

그룹 상태는 얼마나 자주 확인해야 하나요?

몇 초마다와 같이 일정한 간격으로 /users/track/status 엔드포인트를 폴링하고, 그룹의 status가 completed가 되면 중지하세요. 폴링 빈도는 엔드포인트의 사용량 제한인 워크스페이스당 분당 1,500건 이내로 유지하세요.

그룹이 아직 처리 중인 이유는 무엇인가요?

그룹은 Braze가 그룹 내 수락된 모든 요청의 처리를 완료할 때까지 processing 상태를 유지합니다. 처리 중에 요청이 실패하면 Braze가 재시도하며, 재시도가 성공할 때까지 그룹은 processing 상태로 남습니다. 그룹이 completed 상태가 된 후 요청을 추가하면 상태가 processing으로 돌아갑니다. 드물게 그룹이 보존 기간이 끝날 때까지 processing 상태로 남을 수도 있습니다. 그룹이 평소 처리 시간보다 훨씬 오래 processing 상태로 남아 있다면 Braze 고객지원에 문의하세요.

/users/track/status가 빈 results 배열을 반환하는 이유는 무엇인가요?

Braze가 워크스페이스에서 그룹을 찾지 못하면 results 배열이 비어 있습니다. 그룹의 24시간 보존 기간이 종료되었거나, group_id가 요청에 사용한 값과 일치하지 않거나, 다른 워크스페이스로 요청을 보낸 경우에 이런 일이 발생합니다. 또한 Braze가 해당 group_id에 대한 요청을 하나도 추적하지 않은 경우에도 발생합니다. 각 /users/track 응답에서 상태 추적 오류를 확인하세요.

/users/track 응답이 예상보다 느린 이유는 무엇인가요?

성공적인 /users/track 호출은 대개 빠르게 수락되지만, Braze는 속성, 이벤트, 구매 업데이트를 여전히 비동기적으로 처리합니다. 페이로드가 크거나 REST 엔드포인트로의 네트워크 라우팅이 느리면 체감 지연 시간이 늘어날 수 있습니다. 사용자별 동기 확인이나 호출 간 더 엄격한 순서 보장이 필요하다면 /users/track/sync(제한된 베타)를 참조하세요.

/users/track이 429 Too Many Requests를 반환하는 이유는 무엇인가요?

요청 볼륨이 사용량 제한을 초과하면 /users/track은 HTTP 429 Too Many Requests 응답을 반환합니다. 요청 전송을 재개하려면:

  1. X-RateLimit-Retry-After 응답 헤더에 지정된 시간(초) 동안 요청을 일시 중지합니다.
  2. 다시 429 응답을 받을 가능성을 줄이기 위해 더 낮은 속도로 요청을 재개합니다.
  3. 가능하면 업데이트를 결합하고 계정의 요청 오브젝트 제한을 준수합니다.
  4. API 사용량 대시보드를 사용하여 요청 급증 및 429 응답 추세를 파악합니다. 워크스페이스 기본값 및 기타 엔드포인트 제한은 API 사용량 제한을 참조하세요.

지원되는 계약에서 429가 아닌 응답의 경우, 월간 활성 사용자 CY 24-25, 유니버설 MAU, 웹 MAU 및 모바일 MAU에 대한 사용량 제한 헤더에 설명된 X-RateLimit-* 응답 헤더로 현재 기간에 남은 요청 수를 확인하세요.

잘못된 구문 또는 구문 분석 오류와 함께 400 Bad Request가 발생하는 이유는 무엇인가요?

구문 또는 구문 분석 오류가 포함된 HTTP 400은 일반적으로 요청 본문이 유효한 JSON이 아니라는 의미입니다. 흔한 원인으로는 후행 쉼표, JSON 내부의 주석, 작은따옴표로 묶인 문자열, 페이로드 앞에 추가된 여는 {, 또는 Content-Type 헤더가 application/json인 상태에서 JSON이 아닌 본문을 전송하는 경우 등이 있습니다. 전송하기 전에 JSON 린터로 페이로드를 검증하고, HTTP 클라이언트가 원시 문자열을 연결하는 대신 오브젝트를 JSON으로 인코딩하는지, 본문이 UTF-8로 인코딩되어 있는지 확인하세요. 기타 400 응답(예: 페이로드 크기 및 요청당 오브젝트 제한)은 심각한 오류 및 응답과 이 페이지의 엔드포인트별 오류 표를 참조하세요.

월간 활성 사용자 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 응답 헤더가 포함됩니다. 이 헤더를 사용하여 요청 속도를 관리하세요:

헤더 이름 설명
X-RateLimit-Limit 기간당 허용되는 요청 수
X-RateLimit-Remaining 기간 내에 남아 있는 대략적인 요청 수
X-RateLimit-Reset 현재 기간이 재설정되기까지 남은 시간(초)

HTTP 429 오류가 발생하면 RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset 헤더는 반환되지 않습니다. 이 오류가 발생하면 해당 헤더 대신 요청을 다시 시작할 수 있을 때까지 남은 시간(초)을 정수로 반환하는 X-RateLimit-Retry-After 헤더가 제공됩니다.

OpenAPI 문서를 다운로드하여 스키마 검증에 사용할 수 있습니다. 방법은 요청 검증에 OpenAPI 스키마 사용하기를 참조하세요.

New Stuff!