> 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/platform/flutter/event.md).

# 이벤트

이 문서는 DFINERY SDK를 사용하여 유저의 동작을 분석하기 위해 수행해야 할 작업에 대해 설명합니다. 이를 사용하기 위해서는 [SDK 연동](/developer-guide/platform/flutter/integration.md)이 선행되어야 합니다.

## 시작하기 전에

이벤트를 연동하기 전에 [DFINERY 콘솔](https://console.dfinery.ai/)에서 이벤트 등록을 하세요. 이벤트 등록은 콘솔의 부가 설정 > 데이터 연동 > 이벤트 관리 > 이벤트 목록 페이지로 이동한 뒤 이벤트 생성 버튼을 눌러 표준 및 커스텀 이벤트를 생성할 수 있습니다.

## 유의사항

* 등록되지 않은 이벤트 또는 이벤트 속성이 입력될 경우 이벤트가 기록되지 않습니다.
* 입력한 이벤트 속성의 타입과 이벤트 속성 타입이 맞지 않을 경우 이벤트가 기록되지 않습니다.
* 이벤트에 필수로 입력되어야 하는 이벤트 속성이 누락될 경우 이벤트가 기록되지 않습니다.
* [상품](#item_property)은 한 이벤트에 최대 100개까지 입력 가능합니다.

## 이벤트 기록

`logEvent` 메소드를 사용하여 유저의 이벤트를 기록합니다. [표준 이벤트](#predefinded_event)는 상수를 제공합니다.

```dart
Dfinery.logEvent({required String eventName, Map<String, dynamic>? properties})
```

각각의 매개변수는 다음을 의미합니다.

* `eventName` : 이벤트 이름
* `properties` : 이벤트 속성 (옵션)

### 이벤트 기록 예시

```dart
// 속성이 없을 경우
Dfinery.logEvent(eventName: DFEvent.login);

// 속성이 있을 경우
final param = {
    DFEventProperty.signChannel: 'Kakao'
};
Dfinery.logEvent(eventName: DFEvent.signUp, properties: param);
```

## 표준 이벤트 및 속성

표준 이벤트와 표준 이벤트 속성, 상품 속성은 아래와 같습니다.

### 표준 이벤트 <a href="#predefinded_event" id="predefinded_event"></a>

표준 이벤트 이름은 다음과 같이 사전 정의된 정적 상수로 제공됩니다.

| 상수                          | 이벤트명                       | 표기명      |
| --------------------------- | -------------------------- | -------- |
| `DFEvent.login`             | df\_login                  | 로그인      |
| `DFEvent.logout`            | df\_logout                 | 로그아웃     |
| `DFEvent.signUp`            | df\_sign\_up               | 회원가입     |
| `DFEvent.purchase`          | df\_purchase               | 구매       |
| `DFEvent.viewHome`          | df\_view\_home             | 홈 화면 조회  |
| `DFEvent.viewProductDetail` | df\_view\_product\_details | 상품 상세보기  |
| `DFEvent.addToCart`         | df\_add\_to\_cart          | 장바구니 담기  |
| `DFEvent.addToWishList`     | df\_add\_to\_wishlist      | 관심상품 추가  |
| `DFEvent.refund`            | df\_refund                 | 주문취소하기   |
| `DFEvent.viewSearchResult`  | df\_view\_search\_result   | 상품 검색하기  |
| `DFEvent.shareProduct`      | df\_share\_product         | 상품 공유하기  |
| `DFEvent.viewList`          | df\_view\_list             | 상품 목록 조회 |
| `DFEvent.viewCart`          | df\_view\_cart             | 장바구니 조회  |
| `DFEvent.addPaymentInfo`    | df\_add\_payment\_info     | 구매 정보 입력 |
| `DFEvent.removeCart`        | df\_remove\_cart           | 장바구니 삭제  |

### 표준 이벤트 속성

표준 이벤트의 속성 명의 경우 다음과 같이 이벤트 속성 명이 사전 정의된 정적 상수로 제공됩니다.

| 상수                                    | 이벤트 속성명                     | 표기명       |
| ------------------------------------- | --------------------------- | --------- |
| `DFEventProperty.items`               | df\_items                   | 상품        |
| `DFEventProperty.totalRefundAmount`   | df\_total\_refund\_amount   | 환불(취소) 총액 |
| `DFEventProperty.orderId`             | df\_order\_id               | 주문 번호(ID) |
| `DFEventProperty.deliveryCharge`      | df\_delivery\_charge        | 배송료       |
| `DFEventProperty.paymentMethod`       | df\_payment\_method         | 결제 방법     |
| `DFEventProperty.totalPurchaseAmount` | df\_total\_purchase\_amount | 주문 총액     |
| `DFEventProperty.sharingChannel`      | df\_sharing\_channel        | 상품공유 채널   |
| `DFEventProperty.signChannel`         | df\_sign\_channel           | 회원가입 채널   |
| `DFEventProperty.keyword`             | df\_keyword                 | 검색 키워드    |

### 상품 속성 <a href="#item_property" id="item_property"></a>

DFEventProperty.items 내에 배열로 적재되는 상품에 대한 표준 이벤트 속성에 대한 정보입니다. itemId, itemName, itemPrice, itemQuantity, itemDiscount는 필수 값으로 반드시 포함해야 합니다.

| 상수                              | 이벤트 속성명        | 타입     | 설명        | 필수 |
| ------------------------------- | -------------- | ------ | --------- | -- |
| `DFEventProperty.itemId`        | df\_item\_id   | String | 상품 번호(ID) | ✅  |
| `DFEventProperty.itemName`      | df\_item\_name | String | 상품 명      | ✅  |
| `DFEventProperty.itemPrice`     | df\_price      | double | 상품 단가     | ✅  |
| `DFEventProperty.itemQuantity`  | df\_quantity   | int    | 상품 수량     | ✅  |
| `DFEventProperty.itemDiscount`  | df\_discount   | double | 상품 할인가    | ✅  |
| `DFEventProperty.itemCategory1` | df\_category1  | String | 상품 카테고리1  |    |
| `DFEventProperty.itemCategory2` | df\_category2  | String | 상품 카테고리2  |    |
| `DFEventProperty.itemCategory3` | df\_category3  | String | 상품 카테고리3  |    |
| `DFEventProperty.itemCategory4` | df\_category4  | String | 상품 카테고리4  |    |
| `DFEventProperty.itemCategory5` | df\_category5  | String | 상품 카테고리5  |    |

## 표준 이벤트 사용 예시

### 로그인

유저가 서비스에 회원으로 가입하는 동작을 나타내는 이벤트입니다.

{% hint style="success" %}
로그인을 한 [유저 식별 정보를 설정](/developer-guide/platform/flutter/identity.md)하면 통합 아이디에 정보가 반영되어 유저를 더 명확하게 식별할 수 있게 됩니다.
{% endhint %}

```dart
Dfinery.logEvent(eventName: DFEvent.login);
```

### 로그아웃

유저가 앱에서 로그아웃하는 동작을 나타내는 이벤트입니다.

```dart
Dfinery.logEvent(eventName: DFEvent.logout);
```

### 회원가입

유저가 회원으로 가입하는 동작을 나타내는 이벤트입니다.

```dart
final param = {
  DFEventProperty.signChannel: 'Kakao'
};
Dfinery.logEvent(eventName: DFEvent.signUp, properties: param);
```

#### 표준 이벤트 속성

| 이름                            | 타입     | 설명      | 필수 |
| ----------------------------- | ------ | ------- | -- |
| `DFEventProperty.signChannel` | String | 회원가입 채널 | ✅  |

### 구매

유저가 상품이나 서비스를 구매하는 동작을 나타내는 이벤트입니다.

```dart
final item = {
    DFEventProperty.itemId: "상품번호",
    DFEventProperty.itemName: "상품이름",
    DFEventProperty.itemCategory1: "식품",
    DFEventProperty.itemCategory2: "과자",
    DFEventProperty.itemPrice: 5000.0,
    DFEventProperty.itemDiscount: 500.0,
    DFEventProperty.itemQuantity: 5
};
final items = [item];
final param = {
    DFEventProperty.items: items,
    DFEventProperty.orderId: "상품번호",
    DFEventProperty.paymentMethod: "BankTransfer",
    DFEventProperty.totalPurchaseAmount: 25500.0,
    DFEventProperty.deliveryCharge: 3000.0,
    DFEventProperty.itemDiscount: 0
};
Dfinery.logEvent(eventName: DFEvent.purchase, properties: param);
```

#### 표준 이벤트 속성

| 이름                                    | 타입     | 설명                   | 필수 |
| ------------------------------------- | ------ | -------------------- | -- |
| `DFEventProperty.items`               | List   | [상품](#item_property) | ✅  |
| `DFEventProperty.orderId`             | String | 주문 번호(ID)            | ✅  |
| `DFEventProperty.paymentMethod`       | String | 결제 방법                | ✅  |
| `DFEventProperty.totalPurchaseAmount` | double | 주문 총액                | ✅  |
| `DFEventProperty.deliveryCharge`      | double | 배송료                  | ✅  |
| `DFEventProperty.discount`            | double | 상품할인가                | ✅  |

### 홈 화면 조회

유저가 앱의 홈 화면을 조회하는 동작을 나타내는 이벤트입니다.

```dart
Dfinery.logEvent(eventName: DFEvent.viewHome);
```

### 상품 상세 보기

유저가 특정 상품의 상세 정보를 조회하는 동작을 나타내는 이벤트입니다.

```dart
final item = {
  DFEventProperty.itemId: "상품번호",
  DFEventProperty.itemName: "상품이름",
  DFEventProperty.itemCategory1: "식품",
  DFEventProperty.itemCategory2: "과자",
  DFEventProperty.itemPrice: 5000.0,
  DFEventProperty.itemDiscount: 500.0,
  DFEventProperty.itemQuantity: 5
};
final items = [item];
final param = {
    DFEventProperty.items: items
};
Dfinery.logEvent(eventName: DFEvent.viewProductDetail, properties: param);
```

#### 표준 이벤트 속성

| 이름                      | 타입   | 설명                   | 필수 |
| ----------------------- | ---- | -------------------- | -- |
| `DFEventProperty.items` | List | [상품](#item_property) | ✅  |

### 장바구니 담기

유저가 상품을 장바구니에 담는 동작을 나타내는 이벤트입니다.

```dart
final item = {
    DFEventProperty.itemId: "상품번호",
    DFEventProperty.itemName: "상품이름",
    DFEventProperty.itemCategory1: "식품",
    DFEventProperty.itemCategory2: "과자",
    DFEventProperty.itemPrice: 5000.0,
    DFEventProperty.itemDiscount: 500.0,
    DFEventProperty.itemQuantity: 5
};
final items = [item];
final param = {
    DFEventProperty.items: items
};
Dfinery.logEvent(eventName: DFEvent.addToCart, properties: param);
```

#### 표준 이벤트 속성

| 이름                      | 타입   | 설명                   | 필수 |
| ----------------------- | ---- | -------------------- | -- |
| `DFEventProperty.items` | List | [상품](#item_property) | ✅  |

### 관심 상품 추가

유저가 상품을 관심 목록에 추가하는 동작을 나타내는 이벤트입니다.

```dart
final item = {
    DFEventProperty.itemId: "상품번호",
    DFEventProperty.itemName: "상품이름",
    DFEventProperty.itemCategory1: "식품",
    DFEventProperty.itemCategory2: "과자",
    DFEventProperty.itemPrice: 5000.0,
    DFEventProperty.itemDiscount: 500.0,
    DFEventProperty.itemQuantity: 5
};
final items = [item];
final param = {
    DFEventProperty.items: items
};
Dfinery.logEvent(eventName: DFEvent.addToWishList, properties: param);
```

#### 표준 이벤트 속성

| 이름                      | 타입   | 설명                   | 필수 |
| ----------------------- | ---- | -------------------- | -- |
| `DFEventProperty.items` | List | [상품](#item_property) | ✅  |

### 주문 취소하기

유저가 구매한 주문을 취소하고 환불하는 동작을 나타내는 이벤트입니다.

```dart
final item = {
    DFEventProperty.itemId: "상품번호",
    DFEventProperty.itemName: "상품이름",
    DFEventProperty.itemCategory1: "식품",
    DFEventProperty.itemCategory2: "과자",
    DFEventProperty.itemPrice: 5000.0,
    DFEventProperty.itemDiscount: 500.0,
    DFEventProperty.itemQuantity: 5
};
final items = [item];
final param = {
    DFEventProperty.items: items,
    DFEventProperty.totalRefundAmount: 22500.0
};
Dfinery.logEvent(eventName: DFEvent.refund, properties: param);
```

#### 표준 이벤트 속성

| 이름                                  | 타입     | 설명                   | 필수 |
| ----------------------------------- | ------ | -------------------- | -- |
| `DFEventProperty.items`             | List   | [상품](#item_property) | ✅  |
| `DFEventProperty.totalRefundAmount` | double | 환불(취소) 총액            | ✅  |

### 상품 검색하기

유저가 상품을 검색하여 결과를 확인하는 동작을 나타내는 이벤트입니다.

```dart
final item = {
    DFEventProperty.itemId: "상품번호",
    DFEventProperty.itemName: "상품이름",
    DFEventProperty.itemCategory1: "식품",
    DFEventProperty.itemCategory2: "과자",
    DFEventProperty.itemPrice: 5000.0,
    DFEventProperty.itemDiscount: 500.0,
    DFEventProperty.itemQuantity: 5
};
final items = [item];
final param = {
    DFEventProperty.items: items,
    DFEventProperty.keyword: '삼겹살'
};
Dfinery.logEvent(eventName: DFEvent.viewSearchResult, properties: param);
```

#### 표준 이벤트 속성

| 이름                        | 타입     | 설명                   | 필수 |
| ------------------------- | ------ | -------------------- | -- |
| `DFEventProperty.items`   | List   | [상품](#item_property) | ✅  |
| `DFEventProperty.keyword` | String | 검색 키워드               | ✅  |

### 상품 공유하기

유저가 상품을 공유하는 동작을 나타내는 이벤트입니다.

```dart
final item = {
    DFEventProperty.itemId: "상품번호",
    DFEventProperty.itemName: "상품이름",
    DFEventProperty.itemCategory1: "식품",
    DFEventProperty.itemCategory2: "과자",
    DFEventProperty.itemPrice: 5000.0,
    DFEventProperty.itemDiscount: 500.0,
    DFEventProperty.itemQuantity: 5
};
final items = [item];
final param = {
    DFEventProperty.items: items,
    DFEventProperty.sharingChannel: "Facebook"
};
Dfinery.logEvent(eventName: DFEvent.shareProduct, properties: param);
```

#### 표준 이벤트 속성

| 이름                               | 타입     | 설명                   | 필수 |
| -------------------------------- | ------ | -------------------- | -- |
| `DFEventProperty.items`          | List   | [상품](#item_property) | ✅  |
| `DFEventProperty.sharingChannel` | String | 상품 공유 채널             | ✅  |

### 상품 목록 조회

유저가 상품 목록을 조회하는 동작을 나타내는 이벤트입니다.

```dart
final item = {
    DFEventProperty.itemId: "상품번호",
    DFEventProperty.itemName: "상품이름",
    DFEventProperty.itemCategory1: "식품",
    DFEventProperty.itemCategory2: "과자",
    DFEventProperty.itemPrice: 5000.0,
    DFEventProperty.itemDiscount: 500.0,
    DFEventProperty.itemQuantity: 5
};
final items = [item];
final param = {
    DFEventProperty.items: items
};
Dfinery.logEvent(eventName: DFEvent.viewList, properties: param);
```

#### 표준 이벤트 속성

| 이름                      | 타입   | 설명                   | 필수 |
| ----------------------- | ---- | -------------------- | -- |
| `DFEventProperty.items` | List | [상품](#item_property) | ✅  |

### 장바구니 조회

유저가 장바구니를 조회하는 동작을 나타내는 이벤트입니다.

```dart
final item = {
    DFEventProperty.itemId: "상품번호",
    DFEventProperty.itemName: "상품이름",
    DFEventProperty.itemCategory1: "식품",
    DFEventProperty.itemCategory2: "과자",
    DFEventProperty.itemPrice: 5000.0,
    DFEventProperty.itemDiscount: 500.0,
    DFEventProperty.itemQuantity: 5
};
final items = [item];
final param = {
    DFEventProperty.items: items
};
Dfinery.logEvent(eventName: DFEvent.viewCart, properties: param);
```

#### 표준 이벤트 속성

| 이름                      | 타입   | 설명                   | 필수 |
| ----------------------- | ---- | -------------------- | -- |
| `DFEventProperty.items` | List | [상품](#item_property) | ✅  |

### 구매 정보 입력

유저가 구매 정보를 입력하는 동작을 나타내는 이벤트입니다.

```dart
Dfinery.logEvent(eventName: DFEvent.addPaymentInfo);
```

### 장바구니 삭제

유저가 장바구니에 담긴 상품을 제거하는 동작을 나타내는 이벤트입니다.

```dart
final item = {
    DFEventProperty.itemId: "상품번호",
    DFEventProperty.itemName: "상품이름",
    DFEventProperty.itemCategory1: "식품",
    DFEventProperty.itemCategory2: "과자",
    DFEventProperty.itemPrice: 5000.0,
    DFEventProperty.itemDiscount: 500.0,
    DFEventProperty.itemQuantity: 5
};
final items = [item];
final param = {
    DFEventProperty.items: items
};
Dfinery.logEvent(eventName: DFEvent.removeCart, properties: param);
```

#### 표준 이벤트 속성

| 이름                      | 타입   | 설명                   | 필수 |
| ----------------------- | ---- | -------------------- | -- |
| `DFEventProperty.items` | List | [상품](#item_property) | ✅  |

## 커스텀 이벤트

사용자가 직접 임의의 이벤트 명칭과 속성을 입력하여 반영하는 이벤트입니다. 표준 이벤트에도 디파이너리 콘솔에서 커스텀 속성을 추가하여 사용할 수 있습니다.

**속성이 없을 경우**

```dart
Dfinery.logEvent(eventName: "CUSTOM_EVENT_NAME");
```

**속성이 있을 경우**

```dart
final param = {
    'CUSTOM_PROPERTY_KEY': 'CUSTOM_PROPERTY_VALUE'
};
Dfinery.logEvent(eventName: 'CUSTOM_EVENT_NAME', properties: param);
```

## 날짜 및 시간 형식 속성 입력하기

날짜 및 시간 형식은 [DateTime](https://api.dart.dev/stable/2.19.6/dart-core/DateTime-class.html) 형태로 입력해야합니다. 입력한 값은 TimeZone 정보를 포함하여 입력됩니다.

```dart
final item = {
    "custom_item_property": DateTime.now()
};
final items = [item];
final param = {
    "custom_property": DateTime.now()
};
Dfinery.logEvent(eventName: 'CUSTOM_EVENT', properties: param);
```