# 데이터 타입

Marketap은 사용자의 정보를 식별하고 분석하기 위한 다양한 종류의 데이터 타입을 지원합니다. 이 섹션에서는 지원하는 데이터 타입의 목록과 형식에 대해 설명합니다.

## 타입이 일치하지 않는 경우 <a href="#invalid-type" id="invalid-type"></a>

마켓탭은 타입에 맞지 않은 데이터가 들어온 경우, **값 없음(null)으로 처리**합니다. 예를 들어,

정수형으로 지정된 item\_count 속성에 대해, 아래와 같이 이벤트를 전송하게 되면, item\_count에 있는 속성 값은 누락되어 조회시 `null`로 표기됩니다.

```javascript
mtap.track('view_items', {
    item_count: '100',
 })
```

{% hint style="danger" %}
**반드시 전송한 데이터가 콘솔에 정의된 데이터 타입과 일치하는지 확인해주세요! 마켓탭은 누락된 속성을 따로 저장하지 않습니다.**
{% endhint %}

***

## 지원하는 데이터 타입 <a href="#supported-types" id="supported-types"></a>

### String

* 텍스트 데이터를 저장하는 가장 기본적인 타입입니다.
* 예시:

```json
{ "mkt_name": "John Doe", "user_message": "Hello, Marketap!" }
```

### Int

* 정수형 데이터를 다룰 때 사용합니다. 상품 수량 등 정수로 표현 가능한 데이터를 저장할 수 있습니다.
* 예시:

```json
{ "items_in_cart": 3 }
```

### Double

* 소수점을 포함하는 데이터를 표현할 때 사용합니다. 가격, 비율 등의 데이터를 저장할 수 있습니다.
* 예시:

```json
{ "mkt_revenue": 19.99, "conversion_rate": 0.25 }
```

### Datetime

* 이벤트 발생 시각, 예약 시간 등을 표현할 때 사용합니다. UTC 기반 ISO 8601 형식을 따릅니다.

```json
{ "created_at": "2025-01-22T10:00:00Z", "reserved_at": "2025-02-02T10:00:00Z" }
```

### Date

* 생일 등 날짜를 표현할 때 사용합니다.
* ISO 8601 표준에 따라 Date 데이터를 Timezone을 포함하지 않는 YYYY-MM-DD 형식으로 저장합니다.

{% hint style="danger" %}
허용되지 않는 형식

* YYYY/MM/DD, MM-DD-YYYY, DD-MM-YYYY와 같은 변형된 날짜 형식은 허용되지 않습니다.

* 시간 및 시간대가 포함된 형식(1990-05-15T00:00:00Z)은 저장 불가합니다.
  {% endhint %}

* 예시:

```json
{ "mkt_birth": "1990-05-15" }
```

<details>

<summary>Date 타입과 시간대(Timezone)에 대한 처리 방식</summary>

Marketap은 Date 데이터를 저장할 때 시간대(Timezone)를 포함하지 않는 것을 기본 원칙으로 합니다. 생일(Birth Date)을 예로 들어, 시간대 없이 YYYY-MM-DD 형식으로 저장하며, 시간대 처리는 조회 및 연산 (오디언스 조건 설정 등) 시 동적으로 적용합니다.

**왜 시간대를 포함하지 않는가?**

1\. 생일은 하루 단위 데이터입니다

생일은 특정 시간과 무관하게 “날짜”로 인식되며, 전 세계적으로 동일한 날짜를 유지해야 합니다. 예를 들어, “1990년 5월 15일”은 어떤 시간대에서도 변하지 않는 정보입니다.

2\. 데이터의 일관성 유지

시간대를 포함하여 저장하면, 다른 시간대에서 동일한 생일 정보가 왜곡되거나 혼란이 생길 수 있습니다. 예를 들어, UTC 기준으로 저장된 생일이 특정 시간대에서는 하루 전날로 보일 가능성이 있습니다.

3\. 불필요한 복잡성 최소화

시간대를 저장하면 불필요한 데이터 복잡성이 증가합니다. 대신, 시간대 처리는 조회 시점에 동적으로 적용하는 것이 효율적입니다.

</details>

### Array\<String>

* 여러 개의 문자열 데이터를 저장할 수 있습니다. 태그, 카테고리, 키워드 리스트 등에 적합합니다.
* 예시

```json
{ "tags": ["marketing", "sdk", "data"] }
```

### Array\<Item>

Marketap에서는 Array\<Item> 타입을 통해 여러 개의 아이템 항목을 표현할 수 있도록 지원하고 있습니다. 이 타입은 이벤트와 유저 속성에서 사용 가능하며, 두 경우에 따라 동작 방식과 제한 사항이 다릅니다.

#### 이벤트에서 Array\<Item>

* 사용 가능 범위: Array\<Item> 타입은 이벤트에 자유롭게 사용할 수 있으며, 기본 속성 외에 추가 속성을 정의하여 유연하게 확장할 수 있습니다.
* 예시:

```json
{ 
  "mkt_items": [
    {
      "mkt_product_id": "12345",
      "mkt_product_name": "Example Product",
      "mkt_custom_field": "Custom Value"  // 추가 속성
    }
  ]
}
```

#### 유저 속성에서 Array\<Item>

* 사용 가능 범위: Array\<Item>은 유저 속성에서 제한적으로 지원되며, `mkt_cart`와 `mkt_wish_list` 속성에서만 사용 가능합니다.

{% hint style="danger" %}
유저 속성의 Array\<Item>은 고정된 속성만 지원하며, 커스텀 속성을 추가할 수 없습니다.
{% endhint %}

* 예시:

```json
{
  "mkt_cart": [
    {
      "mkt_product_id": "12345",
      "mkt_product_name": "Example Product",
      "mkt_product_price": 100.0,
      "mkt_quantity": 2
      // "mkt_custom_field" : "Custom Value" << 불가능
    }
  ],
  "mkt_wish_list": [
    {
      "mkt_product_id": "67890",
      "mkt_product_name": "Wishlist Product",
      "mkt_product_price": 50.0
    }
  ]
}
```

#### 기본 속성

* Marketap에서 지원하는 Item의 기본 속성입니다.

<table><thead><tr><th>아이템 속성 이름</th><th width="324">설명</th><th>타입</th></tr></thead><tbody><tr><td>mkt_product_id</td><td>상품의 고유 ID</td><td>STRING</td></tr><tr><td>mkt_product_name</td><td>상품 이름</td><td>STRING</td></tr><tr><td>mkt_product_price</td><td>상품 가격</td><td>DOUBLE</td></tr><tr><td>mkt_quantity</td><td>구매한 상품의 수량</td><td>INT</td></tr><tr><td>mkt_discount</td><td>상품에 적용된 할인 금액</td><td>DOUBLE</td></tr><tr><td>mkt_category1</td><td>상품 카테고리 1</td><td>STRING</td></tr><tr><td>mkt_category2</td><td>상품 카테고리 2</td><td>STRING</td></tr><tr><td>mkt_category3</td><td>상품 카테고리 3</td><td>STRING</td></tr><tr><td>mkt_category4</td><td>상품 카테고리 4</td><td>STRING</td></tr><tr><td>mkt_category5</td><td>상품 카테고리 5</td><td>STRING</td></tr><tr><td>mkt_brand</td><td>상품의 브랜드</td><td>STRING</td></tr><tr><td>mkt_variant</td><td>상품 세부 선택사항 (예: 사이즈, 추가옵션 등)</td><td>STRING</td></tr><tr><td>mkt_option_price</td><td>옵션추가로 인한 가격</td><td>DOUBLE</td></tr><tr><td>mkt_created_datetime</td><td>상품을 추가한 시간</td><td>DATETIME</td></tr><tr><td>mkt_bundle_info</td><td>상품에 포함된 번들 정보</td><td>STRING</td></tr><tr><td>mkt_shipping_info</td><td>상품의 배송 정보</td><td>STRING</td></tr></tbody></table>

### Array\<Coupon>

Array 타입은 유저 속성에서만 지원되며, 아이템(Item) 속성과 동일하게 필드 추가 또는 제거가 불가능합니다. Array은 유저와 연관된 쿠폰 정보를 저장하는 데 사용되며, 고정된 필드 구조를 따릅니다.

{% hint style="danger" %}

* 유저 속성의 Array\<Coupon>은 고정된 속성만 지원하며, 커스텀 속성을 추가할 수 없습니다.
* 이벤트에서는 해당 속성을 사용할 수 없습니다.
  {% endhint %}

#### 기본 속성

<table><thead><tr><th>쿠폰 속성 이름</th><th width="249">설명</th><th>타입</th></tr></thead><tbody><tr><td>mkt_coupon_id</td><td>쿠폰 ID</td><td>STRING</td></tr><tr><td>mkt_coupon_name</td><td>쿠폰명</td><td>STRING</td></tr><tr><td>mkt_issue_id</td><td>쿠폰 발급 ID</td><td>STRING</td></tr><tr><td>mkt_used_coupon</td><td>쿠폰 사용여부</td><td>BOOLEAN</td></tr><tr><td>mkt_coupon_expired_at</td><td>쿠폰 만료일자</td><td>DATETIME</td></tr><tr><td>mkt_coupon_issued_at</td><td>쿠폰 발급일자</td><td>DATETIME</td></tr><tr><td>mkt_category1</td><td>카테고리1</td><td>STRING</td></tr><tr><td>mkt_category2</td><td>카테고리2</td><td>STRING</td></tr><tr><td>mkt_category3</td><td>카테고리3</td><td>STRING</td></tr><tr><td>mkt_category4</td><td>카테고리4</td><td>STRING</td></tr><tr><td>mkt_category5</td><td>카테고리5</td><td>STRING</td></tr></tbody></table>

* 예시:

```json
{
  "mkt_coupons": [
    {
      "coupon_id": "COUPON123",
      "coupon_name": "10% Off",
      "coupon_discount": 10.0,
      "mkt_coupon_expired_at": "2025-12-31T23:59:59Z",
      "mkt_coupon_issued_at": "2025-01-01T09:00:00Z"
    },
    {
      "coupon_id": "COUPON456",
      "coupon_name": "Free Shipping",
      "coupon_discount": 0.0,
      "mkt_coupon_expired_at": "2025-06-30T23:59:59Z",
      "mkt_coupon_issued_at": "2025-01-15T08:00:00Z"
    }
  ]
}
```