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

# 타겟팅 설정

> React Native SDK에서 타겟팅을 설정하는 방법을 안내합니다.

## 개요

타겟팅 설정을 통해 특정 사용자 그룹에게 맞춤 광고를 노출할 수 있습니다. Adrop SDK는 **오디언스 타겟팅** 방식을 제공합니다.

* **오디언스 타겟팅**: 사용자의 속성(프로퍼티)을 기반으로 광고를 노출합니다.

<Note>
  타겟팅 데이터를 수집하려면 광고 로드 전에 프로퍼티를 설정해야 합니다.
</Note>

***

## UID 설정 (선택 사항)

사용자 식별자(UID)를 설정하여 크로스 플랫폼 간 타겟팅 데이터를 공유할 수 있습니다. UID 설정은 선택 사항입니다.

### 사용법

```typescript theme={null}
import { Adrop } from 'adrop-ads-react-native'

// 사용자 로그인 후 (선택 사항)
Adrop.setUID("user_123")

// 사용자 로그아웃 시
Adrop.setUID("")
```

### 파라미터

| 파라미터  | 타입       | 설명                        |
| ----- | -------- | ------------------------- |
| `uid` | `string` | 사용자 고유 식별자 (예: 서비스 회원 ID) |

<Warning>
  UID는 SHA-256으로 해시되어 전송됩니다. 개인정보(이메일, 전화번호 등)를 직접 전달하지 마세요.
</Warning>

<Note>
  로그아웃 시 빈 문자열(`""`)을 전달하여 UID를 초기화하세요.
</Note>

***

## 오디언스 타겟팅

사용자의 속성 정보(프로퍼티)를 수집하여 특정 사용자 그룹에게 광고를 노출합니다.

### 프로퍼티 설정

`AdropMetrics.setProperty()` 메서드를 사용하여 사용자의 속성 정보를 수집합니다.

```typescript theme={null}
import { AdropMetrics } from 'adrop-ads-react-native'

// 문자열 프로퍼티
AdropMetrics.setProperty("membership_level", "premium")

// 숫자 프로퍼티
AdropMetrics.setProperty("booking_count", 15)

// 불린 프로퍼티
AdropMetrics.setProperty("is_subscriber", true)

// null 전달 (프로퍼티 제거)
AdropMetrics.setProperty("membership_level", null)
```

### 프로퍼티 조회

`AdropMetrics.properties()`를 사용하여 현재 설정된 모든 프로퍼티를 조회할 수 있습니다.

```typescript theme={null}
import { AdropMetrics } from 'adrop-ads-react-native'

const currentProperties = await AdropMetrics.properties()
console.log(currentProperties)
// { membership_level: "premium", booking_count: 15, ... }
```

<ParamField body="properties()" type="() => Promise<Record<string, any>>">
  현재 설정된 모든 프로퍼티를 키-값 객체로 반환합니다. 설정된 프로퍼티가 없으면 빈 객체를 반환합니다.
</ParamField>

### 파라미터

| 파라미터    | 타입       | 설명                                     |
| ------- | -------- | -------------------------------------- |
| `key`   | `string` | 프로퍼티 키 (최대 64자)                        |
| `value` | `any`    | 프로퍼티 값 (string, number, boolean, null) |

<Warning>
  * 프로퍼티 키는 최대 64자까지 가능합니다.
  * 문자열 값은 최대 256자까지 가능합니다.
  * 숫자 값은 최대 9007199254740991까지 가능합니다.
  * 최대 256개의 프로퍼티를 설정할 수 있습니다.
</Warning>

### 기본 프로퍼티

Adrop SDK는 타겟팅을 위한 기본 프로퍼티를 제공합니다. `AdropProperties`와 `AdropGender` enum을 사용하여 값을 설정합니다.

#### 나이 (생일)

생일 정보를 전달하면 자동으로 나이가 계산됩니다.

```typescript theme={null}
import { AdropMetrics } from 'adrop-ads-react-native'
import { AdropProperties } from 'adrop-ads-react-native'

// 연도만 (yyyy)
AdropMetrics.setProperty(AdropProperties.BIRTH, "1990")

// 연월 (yyyyMM)
AdropMetrics.setProperty(AdropProperties.BIRTH, "199003")

// 연월일 (yyyyMMdd)
AdropMetrics.setProperty(AdropProperties.BIRTH, "19900315")
```

**날짜 포맷**

| 포맷         | 예시         | 설명  |
| ---------- | ---------- | --- |
| `yyyy`     | "1990"     | 연도만 |
| `yyyyMM`   | "199003"   | 연월  |
| `yyyyMMdd` | "19900315" | 연월일 |

#### 성별

```typescript theme={null}
import { AdropMetrics } from 'adrop-ads-react-native'
import { AdropProperties, AdropGender } from 'adrop-ads-react-native'

// 남성
AdropMetrics.setProperty(AdropProperties.GENDER, AdropGender.MALE)

// 여성
AdropMetrics.setProperty(AdropProperties.GENDER, AdropGender.FEMALE)

// 그 외
AdropMetrics.setProperty(AdropProperties.GENDER, AdropGender.OTHER)

// 미확인
AdropMetrics.setProperty(AdropProperties.GENDER, AdropGender.UNKNOWN)
```

**성별 값 상수**

| 상수                    | 값     | 설명  |
| --------------------- | ----- | --- |
| `AdropGender.MALE`    | `"M"` | 남성  |
| `AdropGender.FEMALE`  | `"F"` | 여성  |
| `AdropGender.OTHER`   | `"O"` | 그 외 |
| `AdropGender.UNKNOWN` | `"U"` | 미확인 |

#### 나이 직접 설정

생일 대신 나이를 직접 설정할 수도 있습니다.

```typescript theme={null}
import { AdropMetrics } from 'adrop-ads-react-native'
import { AdropProperties } from 'adrop-ads-react-native'

AdropMetrics.setProperty(AdropProperties.AGE, 30)
```

<Note>
  `BIRTH`와 `AGE` 중 하나만 설정하면 됩니다. 둘 다 설정된 경우 `BIRTH`가 우선됩니다.
</Note>

### 커스텀 프로퍼티

서비스에 맞는 커스텀 프로퍼티를 설정할 수 있습니다. 커스텀 프로퍼티는 [애드컨트롤 콘솔](https://console.adrop.io)의 **타겟팅** 메뉴에서 먼저 정의해야 합니다.

```typescript theme={null}
import { AdropMetrics } from 'adrop-ads-react-native'

// 로컬 액티비티 앱 예시
AdropMetrics.setProperty("region", "Seoul")
AdropMetrics.setProperty("booking_count", 5)

// 쇼핑몰 앱 예시
AdropMetrics.setProperty("membership_tier", "gold")
AdropMetrics.setProperty("total_purchase_amount", 1500000)

// 미디어 앱 예시
AdropMetrics.setProperty("favorite_genre", "drama")
AdropMetrics.setProperty("is_premium_subscriber", true)
```

<Warning>
  커스텀 프로퍼티 이름은 콘솔에서 정의한 이름과 정확히 일치해야 합니다. 대소문자를 구분합니다.
</Warning>

### 프로퍼티 사용 예시

사용자가 앱에 로그인할 때 프로퍼티를 설정하는 예시입니다.

```typescript theme={null}
import React, { useEffect } from 'react'
import { AdropMetrics } from 'adrop-ads-react-native'
import { AdropProperties, AdropGender } from 'adrop-ads-react-native'

const ProfileScreen = () => {
  useEffect(() => {
    // 사용자 정보 가져오기
    const user = getUserInfo()

    // 기본 프로퍼티 설정
    AdropMetrics.setProperty(AdropProperties.BIRTH, user.birthDate)
    AdropMetrics.setProperty(AdropProperties.GENDER, user.gender)

    // 커스텀 프로퍼티 설정
    AdropMetrics.setProperty("membership_level", user.membershipLevel)
    AdropMetrics.setProperty("total_booking_count", user.bookingCount)
  }, [])

  return (
    // 화면 컴포넌트
  )
}

export default ProfileScreen
```

***

## 이벤트 트래킹

사용자 행동 이벤트를 추적하여 사용자 활동 기반의 오디언스를 구축할 수 있습니다. `AdropMetrics.sendEvent()`를 사용하여 이벤트를 전송합니다.

<Note>
  `logEvent()`는 deprecated되었습니다. `sendEvent()`를 사용하세요.
</Note>

### 이벤트 전송

```typescript theme={null}
import { AdropMetrics } from 'adrop-ads-react-native'

// 단순 이벤트 (파라미터 없음)
AdropMetrics.sendEvent('app_open')

// 파라미터가 있는 이벤트
AdropMetrics.sendEvent('view_item', {
  item_id: 'SKU-123',
  item_name: 'Widget',
  item_category: 'Electronics',
  brand: 'BrandX',
  price: 29900,
})
```

### 다중 아이템 이벤트

여러 아이템이 포함된 이벤트(예: purchase, begin\_checkout)의 경우, 파라미터에 `items` 배열을 전달합니다.

```typescript theme={null}
import { AdropMetrics } from 'adrop-ads-react-native'

AdropMetrics.sendEvent('purchase', {
  tx_id: 'TXN-20240101-001',
  currency: 'KRW',
  items: [
    {
      item_id: 'SKU-001',
      item_name: '상품A',
      item_category: 'Electronics',
      brand: 'BrandX',
      price: 29900,
      quantity: 1,
    },
    {
      item_id: 'SKU-002',
      item_name: '상품B',
      price: 15000,
      quantity: 2,
    },
  ],
})
```

### 지원되는 이벤트 예시

| 이벤트 이름            | 설명       | 주요 파라미터                                                                                    |
| ----------------- | -------- | ------------------------------------------------------------------------------------------ |
| `app_open`        | 앱 열기     | —                                                                                          |
| `sign_up`         | 회원가입     | `method`                                                                                   |
| `push_clicks`     | 푸시 알림 클릭 | `campaign_id`                                                                              |
| `page_view`       | 페이지 조회   | `page_id`, `page_category`, `page_url`                                                     |
| `click`           | 요소 클릭    | `element_id`, `element_type`, `target_url`                                                 |
| `view_item`       | 아이템 조회   | `item_id`, `item_name`, `item_category`, `brand`, `price`                                  |
| `view_content`    | 콘텐츠 조회   | `content_id`, `content_name`, `content_type`                                               |
| `add_to_wishlist` | 위시리스트 추가 | `item_id`, `item_name`, `item_category`, `brand`, `price`                                  |
| `add_to_cart`     | 장바구니 추가  | `item_id`, `item_name`, `item_category`, `brand`, `price`, `quantity`, `value`, `currency` |
| `begin_lead_form` | 리드 폼 시작  | `form_id`, `form_name`, `form_type`, `form_destination`                                    |
| `generate_lead`   | 리드 생성    | `form_id`, `form_name`, `form_type`, `form_destination`, `value`, `currency`               |
| `begin_checkout`  | 결제 시작    | `currency`, `items`                                                                        |
| `purchase`        | 구매 완료    | `tx_id`, `currency`, `items`                                                               |

<Note>
  * 이벤트 이름은 1\~64자여야 합니다.
  * 파라미터 키는 1\~64자여야 합니다.
  * 문자열 파라미터 값은 최대 1024자까지 가능합니다.
</Note>

***

## 모범 사례

### 1. 프로퍼티 설정

```typescript theme={null}
// ✅ 올바른 예시
AdropMetrics.setProperty("membership_level", "premium")
// 광고 로드...

// ❌ 잘못된 예시
// 광고 로드...
AdropMetrics.setProperty("membership_level", "premium") // 광고 로드 후 설정하면 타겟팅이 적용되지 않음
```

### 2. 프로퍼티는 변경될 때마다 업데이트

```typescript theme={null}
import { AdropMetrics } from 'adrop-ads-react-native'

const App = () => {
  useEffect(() => {
    // 앱 시작 시 초기 프로퍼티 설정
    updateUserProperties()
  }, [])

  const onUserPurchaseComplete = (purchaseAmount: number) => {
    // 구매 완료 시 프로퍼티 업데이트
    const currentTotal = getCurrentTotalPurchase()
    AdropMetrics.setProperty("total_purchase_amount", currentTotal + purchaseAmount)
  }

  const onMembershipUpgrade = (newTier: string) => {
    // 멤버십 업그레이드 시 프로퍼티 업데이트
    AdropMetrics.setProperty("membership_tier", newTier)
  }

  // ...
}
```

### 3. 프로퍼티 초기화

```typescript theme={null}
import { AdropMetrics } from 'adrop-ads-react-native'

const onUserLogout = () => {
  // 프로퍼티 초기화
  AdropMetrics.setProperty("membership_level", null)
  AdropMetrics.setProperty("total_booking_count", null)
}
```

***

## 관련 문서

<CardGroup cols={2}>
  <Card title="오디언스 타겟팅 만들기" icon="users" href="/ko/targeting/audience">
    콘솔에서 오디언스 타겟팅 생성하기
  </Card>

  <Card title="타겟팅 판매하기" icon="won-sign" href="/ko/targeting/sell">
    타겟팅 판매하기
  </Card>

  <Card title="배너 광고" icon="rectangle-ad" href="/ko/sdk/react-native/banner">
    배너 광고 구현하기
  </Card>

  <Card title="네이티브 광고" icon="mobile" href="/ko/sdk/react-native/native">
    네이티브 광고 구현하기
  </Card>
</CardGroup>

***

## FAQ

<AccordionGroup>
  <Accordion title="UID를 설정하지 않으면 타겟팅 광고가 노출되지 않나요?">
    UID 설정은 선택 사항입니다. UID를 설정하지 않아도 프로퍼티 기반 타겟팅은 정상적으로 동작합니다. UID는 크로스 플랫폼 간 타겟팅 데이터를 공유할 때 유용합니다.
  </Accordion>

  <Accordion title="프로퍼티를 설정했는데 콘솔에서 데이터가 보이지 않아요.">
    프로퍼티 데이터는 수집 후 최대 24시간 내에 콘솔에 반영됩니다. 데이터가 표시되지 않는 경우:

    1. 콘솔에서 프로퍼티가 올바르게 정의되었는지 확인하세요.
    2. SDK에서 전달하는 프로퍼티 키가 콘솔과 정확히 일치하는지 확인하세요 (대소문자 구분).
    3. `AdropMetrics.setProperty()`가 광고 로드 전에 호출되는지 확인하세요.
  </Accordion>

  <Accordion title="프로퍼티 값을 삭제하려면 어떻게 하나요?">
    프로퍼티 값에 `null`을 전달하면 해당 프로퍼티가 삭제됩니다:

    ```typescript theme={null}
    AdropMetrics.setProperty("membership_level", null)
    ```
  </Accordion>

  <Accordion title="배열 타입의 프로퍼티를 설정할 수 있나요?">
    React Native SDK에서는 배열 타입은 현재 직접 지원하지 않습니다. 필요한 경우 문자열로 변환하여 전달하거나, 여러 개의 개별 프로퍼티로 나누어 설정하세요.
  </Accordion>
</AccordionGroup>