> For the complete documentation index, see [llms.txt](https://docs.dfinery.ai/developer-guide/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.dfinery.ai/developer-guide/common/identity-scenario.md).

# 통합 ID 연동 시나리오

이 문서는 유저 식별 정보 설정으로 인한 유저 정보의 구성과 단말기 연결의 이해를 돕기 위해 가상의 시나리오를 예시로 들어 설명하는 문서입니다.

## 앱 최초 설치

SDK를 초기화 하기 위해 유저는 각 플랫폼 별 연동하기 가이드에 명시된 단계에 따라 적용해야 합니다.

## 유저 로그인

이 섹션은 [익명의 유저 프로필](#anonymous-user) 상태에서 [식별된 유저 프로필](#identified-user)로 전환되는 과정을 보여줍니다.

### 1. 유저 식별 정보 설정하기

로그인 이벤트를 기록하기 전에 유저를 구분할 값인 `EXTERNAL_ID`값을 유저 식별 정보에 설정 해줍니다. 이 과정을 통해 해당 유저는 익명의 유저 프로필 상태에서 식별된 유저 프로필로 전환되며 통합 ID가 생성되어 어떤 플랫폼에서든 이 유저를 통합 ID를 통해 특정할 수 있게 됩니다.

{% tabs %}
{% tab title="Java" %}

```java
DfineryProperties.setIdentity(DFIdentity.EXTERNAL_ID, "A")
//다른 식별 정보를 추가로 설정함으로써 유저 식별의 정확도를 높일 수 있습니다.
DfineryProperties.setIdentity(DFIdentity.EMAIL, "A@igaworks.com")
DfineryProperties.setIdentity(DFIdentity.PHONE_NO, "8201012345678")
...
```

{% endtab %}

{% tab title="Swift" %}

```swift
Dfinery.shared().setIdentity(key: DFIdentity.EXTERNAL_ID, value: "A")
//다른 식별 정보를 추가로 설정함으로써 유저 식별의 정확도를 높일 수 있습니다.
Dfinery.shared().setIdentity(key: DFIdentity.EMAIL, value: "jimmy.kang@igaworks.com")
Dfinery.shared().setIdentity(key: DFIdentity.PHONE_NO, value: "821012345678")
...
```

{% endtab %}

{% tab title="Javascript" %}

```javascript
Dfinery.setIdentity(DFIdentity.EXTERNAL_ID, "A")
//다른 식별 정보를 추가로 설정함으로써 유저 식별의 정확도를 높일 수 있습니다.
Dfinery.setIdentity(DFIdentity.EMAIL, "A@igaworks.com")
Dfinery.setIdentity(DFIdentity.PHONE_NO, "8201012345678")
```

{% endtab %}
{% endtabs %}

{% @mermaid/diagram content="sequenceDiagram
participant 익명유저
Note over 익명유저: EXTERNAL\_ID를 "A"로 설정
익명유저->>식별된유저A: 식별된 유저 A로 변경" %}

### 2. 유저 프로필 설정하기

식별된 유저 A에 해당하는 설정에 필요한 정보가 있을 경우 유저 프로필 설정을 통해 반영합니다.

{% hint style="success" %}
유저 프로필은 임의의 키 값을 유저가 콘솔에서 설정해서 반영 가능합니다.
{% endhint %}

{% tabs %}
{% tab title="Java" %}

```java
DfineryProperties.setUserProfile(DFUserProfile.GENDER, DFGender.MALE)
DfineryProperties.setUserProfile(DFUserProfile.MEMBERSHIP, "VIP")
...
```

{% endtab %}

{% tab title="Swift" %}

```swift
Dfinery.shared().setUserProfile(key: DFUserProfile.GENDER, value: DFGENDER.MALE)
Dfinery.shared().setUserProfile(key: DFUserProfile.MEMBERSHIP, value: "VIP")
...
```

{% endtab %}

{% tab title="Javascript" %}

```javascript
Dfinery.setUserProfile(DFUserProfile.GENDER, DFGender.MALE)
Dfinery.setUserProfile(DFUserProfile.MEMBERSHIP, "VIP")
...
```

{% endtab %}
{% endtabs %}

{% @mermaid/diagram content="classDiagram
class 식별된유저A
식별된유저A : gender("MALE")
식별된유저A : membership("VIP")" %}

### 3. 로그인 이벤트 기록하기

로그인 이벤트를 기록합니다.

{% tabs %}
{% tab title="Java" %}

```java
Dfinery.getInstance().logEvent(DFEvent.LOGIN)
```

{% endtab %}

{% tab title="Swift" %}

```swift
Dfinery.shared().logEvent(DFEvent.LOGIN)
```

{% endtab %}

{% tab title="Javascript" %}

```javascript
Dfinery.logEvent(DFEvent.LOGIN)
```

{% endtab %}
{% endtabs %}

## 유저 로그아웃

이 섹션은 식별된 유저 A가 로그아웃을 하는 과정을 보여줍니다.

### 1. 로그아웃 이벤트 기록하기

로그아웃 이벤트를 기록합니다.

{% tabs %}
{% tab title="Java" %}

```java
Dfinery.getInstance().logEvent(DFEvent.LOGOUT)
```

{% endtab %}

{% tab title="Swift" %}

```swift
Dfinery.shared().logEvent(DFEvent.LOGOUT)
```

{% endtab %}

{% tab title="Javascript" %}

```javascript
Dfinery.logEvent(DFEvent.LOGOUT)
```

{% endtab %}
{% endtabs %}

### 2. 유저 식별 정보를 초기화하기 (선택사항)

만약 식별된 유저 A가 로그아웃한 이후 A에 대해 액션이 타게팅이 되기를 원치 않을 경우 `resetIdentity()` API를 호출함으로써 유저 식별 정보를 초기화 합니다.

{% hint style="warning" %}
유저 식별 정보를 초기화 할 경우 기존에 이어지고 있던 이벤트 흐름이 끊기고 단말기와 유저의 연결도 끊기게 되므로 호출에 주의하여 주시기 바랍니다.

만약 그래도 호출하신다면 수집된 이벤트의 반영을 위해 API 호출 전에 반영하고자 하는 이벤트를 먼저 호출한 후 호출하여 주시기를 바랍니다.
{% endhint %}

{% tabs %}
{% tab title="Java" %}

```java
DfineryProperties.resetIdentity();
```

{% endtab %}

{% tab title="Swift" %}

```swift
Dfinery.shared().resetIdentity()
```

{% endtab %}

{% tab title="Javascript" %}

```javascript
Dfinery.resetIdentity()
```

{% endtab %}
{% endtabs %}

## 기존 `EXTERNAL_ID`를 사용한 로그인

이 섹션은 통합 식별 정보를 설정한 이력이 있는 유저가 다시 같은 `EXTERNAL_ID` 값을 사용해서 로그인을 하는 과정을 보여줍니다.

### 1. 유저 식별 정보 설정하기

입력한 `EXTERNAL_ID` 값이 기존과 동일할 경우 기존에 생성되었던 식별된 유저 A와 단말기가 다시 연결됩니다.

{% tabs %}
{% tab title="Java" %}

```java
DfineryProperties.setIdentity(DFIdentity.EXTERNAL_ID, "A")
```

{% endtab %}

{% tab title="Swift" %}

```swift
Dfinery.shared().setIdentity(key: DFIdentity.EXTERNAL_ID, value: "A")
```

{% endtab %}

{% tab title="Javascript" %}

```javascript
Dfinery.setIdentity(DFIdentity.EXTERNAL_ID, "A")
```

{% endtab %}
{% endtabs %}

### 2. 로그인 이벤트 기록하기

이벤트의 흐름 또한 기존과 마찬가지로 식별된 유저 A의 이벤트 흐름이 계속해서 이어집니다.

{% tabs %}
{% tab title="Java" %}

```java
Dfinery.getInstance().logEvent(DFEvent.LOGIN)
```

{% endtab %}

{% tab title="Swift" %}

```swift
Dfinery.shared().logEvent(DFEvent.LOGIN)
```

{% endtab %}

{% tab title="Javascript" %}

```javascript
Dfinery.logEvent(DFEvent.LOGIN)
```

{% endtab %}
{% endtabs %}

{% @mermaid/diagram content="graph TB
subgraph 식별된유저A
A(Login)--> B(Logout) --> C(Login)
end" %}

## 다른 `EXTERNAL_ID`를 사용한 로그인

이 섹션은 통합 식별 정보를 설정한 이력이 있는 유저가 다른 `EXTERNAL_ID` 값을 사용해서 로그인을 하는 과정을 보여줍니다.

### 1. 유저 식별 정보 설정하기

입력한 `EXTERNAL_ID` 값이 기존과 다를 경우 SDK는 다른 유저로 판단해서 기존에 저장하고 있었던 통합 ID 정보를 모두 삭제하고 새로 설정하게 되며 단말기가 식별된 유저 B로 연결됩니다.

{% tabs %}
{% tab title="Java" %}

```java
DfineryProperties.setIdentity(DFIdentity.EXTERNAL_ID, "B")
```

{% endtab %}

{% tab title="Swift" %}

```swift
Dfinery.shared().setIdentity(key: DFIdentity.EXTERNAL_ID, value: "B")
```

{% endtab %}

{% tab title="Javascript" %}

```javascript
Dfinery.setIdentity(DFIdentity.EXTERNAL_ID, "B")
```

{% endtab %}
{% endtabs %}

{% @mermaid/diagram content="sequenceDiagram
participant 식별된유저A
Note over 식별된유저A: EXTERNAL\_ID를 "B"로 설정
Note over 식별된유저A,식별된유저B: A의 식별 정보 제거
식별된유저A->>식별된유저B: 식별된 유저 B로 변경" %}

### 2. 유저 프로필 설정하기

유저 프로필은 식별된 유저 B에 반영됩니다.

{% tabs %}
{% tab title="Java" %}

```java
DfineryProperties.setUserProfile(DFUserProfile.GENDER, DFGender.FEMALE)
DfineryProperties.setUserProfile(DFUserProfile.MEMBERSHIP, "VVIP")
...
```

{% endtab %}

{% tab title="Swift" %}

```swift
Dfinery.shared().setUserProfile(key: DFUserProfile.GENDER, value: DFGender.FEMALE)
Dfinery.shared().setUserProfile(key: DFUserProfile.MEMBERSHIP, value: "VVIP")
...
```

{% endtab %}

{% tab title="Javascript" %}

```javascript
Dfinery.setUserProfile(DFUserProfile.GENDER, DFGender.FEMALE)
Dfinery.setUserProfile(DFUserProfile.MEMBERSHIP, "VVIP")
...
```

{% endtab %}
{% endtabs %}

{% @mermaid/diagram content="classDiagram
class 식별된유저A
식별된유저A : gender("MALE")
식별된유저A : membership("VIP")
class 식별된유저B
식별된유저B : gender("FEMALE")
식별된유저B : membership("VVIP")" %}

### 3. 로그인 이벤트 기록하기

이벤트의 흐름은 새로이 식별된 유저 B의 이벤트 흐름으로 변경됩니다.

{% tabs %}
{% tab title="Java" %}

```java
Dfinery.getInstance().logEvent(DFEvent.LOGIN)
```

{% endtab %}

{% tab title="Swift" %}

```swift
Dfinery.shared().logEvent(DFEvent.LOGIN)
```

{% endtab %}

{% tab title="Javascript" %}

```javascript
Dfinery.logEvent(DFEvent.LOGIN)
```

{% endtab %}
{% endtabs %}

{% @mermaid/diagram content="graph TB
subgraph 식별된유저B
D(Login)
end
subgraph 식별된유저A
A(Login)--> B(Logout) --> C(Login)
end" %}

***

## 용어

### 익명의 유저 프로필 <a href="#anonymous-user" id="anonymous-user"></a>

유저 식별 정보를 설정하지 않았을 경우 유저는 익명 유저로 취급됩니다. 예를 들어 웹사이트에 방문했지만 가입하지 않았거나 모바일 앱을 다운로드 했지만 프로필을 만들지 않은 유저가 될 수 있습니다.

처음에 SDK를 통해 유저가 인식되면 SDK에서 생성한 고유 식별자가 발급되어 익명의 유저 프로필이 생성됩니다.

### 식별된 유저 프로필 <a href="#identified-user" id="identified-user"></a>

아래 식별 정보 유형 중 `EXTERNAL_ID` 값을 설정할 경우 DFINERY에서 식별된 유저로 취급되며 여러 장치에서 동일한 유저 프로필을 식별할 수 있게 됩니다. 또한 보다 명확한 유저 식별을 위해 유저 이메일, 전화번호 등의 정보를 추가로 설정할 수 있습니다.