새 사용자 별칭 만들기

이 엔드포인트를 사용하여 기존 식별된 사용자에 대한 새 사용자 별칭을 추가하거나 식별되지 않은 새 사용자를 만들 수 있습니다.

요청당 최대 50개의 사용자 별칭을 지정할 수 있습니다.

기존 사용자의 사용자 별칭을 추가하려면 새 사용자 별칭 오브젝트에 external_id를 포함해야 합니다. 오브젝트에 external_id가 있지만 해당 external_id를 가진 사용자가 없는 경우 별칭은 어떤 사용자에게도 추가되지 않습니다. external_id가 없으면 사용자는 계속 생성되지만 나중에 식별해야 합니다. “사용자 식별” 및 users/identify 엔드포인트를 사용하여 이 작업을 수행할 수 있습니다.

별칭 전용 사용자를 새로 만들려면 새 사용자 별칭 오브젝트에서 external_id를 생략해야 합니다. 사용자가 생성된 후 /users/track 엔드포인트를 사용하여 별칭 전용 사용자를 속성, 이벤트 및 구매와 연결하고, /users/identify 엔드포인트를 사용하여 external_id로 사용자를 식별합니다.

alias_label과 alias_name이 이미 존재하는 경우

alias_label과 alias_name의 조합은 사용자 기반 전체에서 고유해야 합니다. 자세한 내용은 사용자 별칭을 참조하세요.

alias_label과 alias_name 쌍이 이미 어떤 사용자에게 존재하는 경우(동일한 사용자이든 다른 사용자이든) 요청을 보내면 엔드포인트는 여전히 성공 응답을 반환합니다(예: "aliases_processed": 1, "message": "success"). 이 경우 요청의 사용자에게 새 별칭이 추가되지 않습니다. alias_label과 alias_name 쌍이 이미 사용 중이므로 요청은 어떤 변경도 수행하지 않으며, 해당 사용자에게 별칭이 추가되지 않은 것처럼 보일 수 있습니다.

필수 조건

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

사용량 제한

이 엔드포인트에는 분당 20,000건의 요청에 대한 공유 사용량 제한이 적용됩니다. 이 사용량 제한은 API 사용량 제한에 설명된 대로 /users/delete, /users/identify, /users/merge 및 /users/alias/update 엔드포인트와 공유됩니다.

요청 본문

1
2
Content-Type: application/json
Authorization: Bearer YOUR_REST_API_KEY

1
2
3
{
  "user_aliases" : (required, array of new user alias object)
}

요청 매개변수

새 사용자 별칭 오브젝트 사양이 포함된 엔드포인트 요청 본문

1
2
3
4
5
{
  "external_id" : (optional, string),
  "alias_name" : (required, string),
  "alias_label" : (required, string)
}

요청 예시

1
2
3
4
5
6
7
8
9
10
11
12
curl --location --request POST 'https://rest.iad-01.braze.com/users/alias/new' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_REST_API_KEY' \
--data-raw '{
  "user_aliases" :[
    {
      "external_id": "external_identifier",
      "alias_name" : "example_name",
      "alias_label" : "example_label"
    }
  ]
}'

응답

동일한 alias_label과 alias_name이 이미 사용자에게 존재하여 별칭이 건너뛰어진 경우에도 응답 본문은 여전히 성공을 나타낼 수 있습니다. 자세한 내용은 별칭 라벨과 이름이 이미 존재하는 경우를 참조하세요.

1
2
3
4
{
    "aliases_processed": 1,
    "message": "success"
}

문제 해결

이 엔드포인트를 사용하여 사용자 별칭을 만든 후 속성이 업데이트되지 않는 이유는 무엇인가요?

이 문제는 일반적으로 /users/alias/new 호출 후 별도의 /users/track 요청을 통해 별칭으로 속성을 업데이트하려고 할 때 발생합니다. 추적 요청이 Braze에서 새 alias_label과 alias_name 쌍을 프로필에 일관되게 연결하기 전에 처리될 수 있으므로, 속성이 예상한 사용자에게 적용되지 않을 수 있습니다.

권장 접근 방식: 별칭 전용 프로필을 만들거나 이미 존재하는 별칭으로 프로필을 업데이트하려는 경우에만 단일 /users/track 호출을 사용하세요. attributes 배열에서 user_alias와 프로필 필드를 동일한 사용자 속성 오브젝트에 넣으면 Braze가 사용자를 확인하고 한 번에 업데이트를 적용합니다.

해당 오브젝트에서 별칭 전용 프로필을 만들어야 할 수 있는 경우 _update_existing_only를 false로 설정하세요. user_alias를 사용하면서 이 값을 생략하면 Braze는 기본적으로 업데이트 전용 동작을 수행하며 별칭 전용 프로필을 만들지 않습니다. 워크스페이스의 사용자에게 해당 별칭이 이미 존재하는 경우 동일한 요청이 새 속성으로 해당 프로필을 업데이트합니다.

/users/track를 사용하여 external_id로 식별된 기존 사용자에게 새 별칭을 추가할 수는 없습니다. 사용자 속성 오브젝트에서 external_id와 user_alias는 상호 배타적입니다. 식별된 사용자에게 별칭을 추가하려면 먼저 /users/alias/new를 호출하세요. 별칭이 연결된 후에는 external_id 또는 기존 별칭을 사용하여 /users/track로 해당 프로필을 업데이트할 수 있습니다.

예를 들어, 다음 /users/track 본문은 별칭이 아직 존재하지 않는 경우 별칭 전용 프로필을 만들거나, 해당 별칭이 이미 있는 기존 프로필을 업데이트합니다:

1
2
3
4
5
6
7
8
9
10
11
12
{
  "attributes": [
    {
      "user_alias": {
        "alias_name": "[email protected]",
        "alias_label": "email"
      },
      "_update_existing_only": false,
      "string_attribute": "test_alias_only_update"
    }
  ]
}