> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.onesignal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 별칭

> OneSignal에서 사용자 지정 별칭을 사용하여 자체 고유 식별자를 통해 다양한 플랫폼과 기기에서 사용자를 식별하고 추적하는 방법을 알아보세요. 별칭은 여러 소스에서 사용자 데이터를 통합하는 데 도움이 되며 통합, 사용자 데이터 관리 및 트랜잭션 메시징에 필수적입니다.

사용자 지정 별칭을 사용하면 OneSignal의 사용자에게 사용자 지정 키-값 식별자를 할당하여 자체 내부 ID를 사용한 크로스 플랫폼 사용자 추적 및 식별이 가능합니다.

<Warning>
  **중요**: 사용자 지정 별칭을 사용하기 **전에** [External ID](./users)를 설정해야 합니다.

  OneSignal은 고유한 `onesignal_id`를 사용하여 사용자를 식별합니다. 이 ID는 동일한 `external_id`가 있는 경우에만 [구독](./subscriptions) 전체에서 일관성을 유지합니다.

  사용자 지정 별칭은 구독을 함께 연결하지 **않습니다**. 올바르게 작동하려면 `external_id`에 의존합니다. 이것이 없으면 별칭이 기기나 플랫폼 전체에서 동일한 사용자와 연결되지 않습니다.
</Warning>

***

## 사용자 지정 별칭이란 무엇인가요?

사용자 지정 별칭은 다음과 같은 `key : value` 쌍입니다:

* `alias_label`(키)은 모든 사용자에게 일관되고 정적인 식별자입니다(예: `facebook_id`, `firebase_id`, `crm_user_id`).
* `alias_id`(값)은 해당 레이블에 대한 특정 사용자의 ID입니다(예: `facebook_id: 3453443`, `firebase_id: test3555`).

이를 통해 OneSignal 사용자 레코드를 다른 플랫폼이나 데이터베이스의 식별자에 연결할 수 있습니다.

***

## 별칭을 사용하는 이유는 무엇인가요?

1. 여러 플랫폼과 데이터베이스에서 사용자를 식별합니다.
2. [Create Message REST API](/reference/create-message)를 사용하여 타겟팅된 트랜잭션 메시지를 보냅니다.
3. User REST API를 통해 사용자를 가져오거나 업데이트하거나 삭제합니다.

***

## 별칭 설정 방법

OneSignal SDK를 사용하거나 REST API를 통해 별칭을 설정할 수 있습니다.

### SDK 사용

앱에서 다음 단계를 따르세요:

1. External ID 설정
   `OneSignal.login(externalId)`를 호출하여 사용자 레코드를 연결합니다.

2. 사용자 지정 별칭 설정
   `OneSignal.User.addAlias(label, id)`를 사용하여 단일 별칭을 추가하거나 `OneSignal.User.addAliases({ label1: id1, label2: id2 })`를 사용하여 여러 별칭을 설정합니다.

3. 로그아웃(선택 사항)
   `OneSignal.logout()`를 사용하여 해당 기기 또는 세션에 대한 External ID 및 관련 별칭을 제거합니다.

**예제**:

```javascript theme={null}
OneSignal.login("user_123");

OneSignal.User.addAliases({
  facebook_id: "3453443",
  firebase_id: "test3555"
});

// Later, when the user logs out
OneSignal.logout();
```

***

### REST API 사용

API를 통해 사용자 지정 별칭을 설정하려면 [Create Alias](/reference/create-alias) 엔드포인트를 사용합니다. 이 방법은 일반적으로 서버 측 사용자 관리를 위한 백엔드 시스템에서 사용됩니다.

**예제 요청**:

```json theme={null}
POST /aliases
{
  "subscription_id": "abc123",
  "aliases": {
    "facebook_id": "3453443",
    "crm_user_id": "XYZ789"
  }
}
```

***

## 모범 사례

* 별칭을 할당하기 전에 항상 `external_id`를 설정하세요.
* 팀 전체의 혼란을 피하기 위해 안정적이고 설명적인 레이블(예: `crm_user_id`, `legacy_user_id`)을 사용하세요.
* 이메일 주소나 전화번호와 같은 민감한 정보를 별칭 값으로 사용하지 마세요.
* `logout()`를 사용하여 기기 로그아웃 또는 사용자 전환 이벤트 시 별칭을 정리하세요.

***

<Check>
  사용자 지정 별칭 튜토리얼 완료!
  다음 단계:

  * 아직 확인하지 않았다면 [사용자](./users) 및 [구독](./subscriptions) 문서를 검토하세요.
  * API를 통해 별칭을 사용하는 방법에 대한 자세한 내용은 [REST API](/reference/create-alias) 문서를 살펴보세요.
  * [통합](./integrations)을 설정하여 시스템 간에 사용자 데이터를 동기화하세요.
</Check>

***