### Querying Documentation via HTTP GET

Source: https://toss-ads.gitbook.io/guide/a-d/creative-guidelines.md

Perform an HTTP GET request to the documentation URL with 'ask' and 'goal' parameters to retrieve specific information.

```http
GET https://toss-ads.gitbook.io/guide/a-d/creative-guidelines.md?ask=<question>&goal=<endgoal>
```

--------------------------------

### Querying Documentation via HTTP GET

Source: https://toss-ads.gitbook.io/guide/a-d/app-install/banner-guide.md

GitBook 문서에서 정보를 동적으로 조회하기 위해 사용하는 HTTP GET 요청 예시입니다.

```http
GET https://toss-ads.gitbook.io/guide/a-d/app-install/banner-guide.md?ask=<question>&goal=<endgoal>
```

--------------------------------

### GET /guide/intro.md

Source: https://toss-ads.gitbook.io/guide/intro

Performs a dynamic query against the documentation to retrieve answers, excerpts, and sources based on a specific question and optional goal.

```APIDOC
## GET /guide/intro.md

### Description
Retrieves information from the documentation by providing a natural language question and an optional end goal.

### Method
GET

### Endpoint
https://toss-ads.gitbook.io/guide/intro.md

### Parameters
#### Query Parameters
- **ask** (string) - Required - The specific, self-contained question to ask the documentation.
- **goal** (string) - Optional - The broader end goal to help tailor the response.

### Response
#### Success Response (200)
- **answer** (string) - A direct answer to the question.
- **excerpts** (array) - Relevant excerpts from the documentation.
- **sources** (array) - Sources used to generate the answer.
```

--------------------------------

### GET /guide/account.md

Source: https://toss-ads.gitbook.io/guide/account

Queries the documentation for specific information using a natural language question and an optional goal context.

```APIDOC
## GET /guide/account.md

### Description
Queries the documentation dynamically by providing a specific question and an optional goal to receive a tailored answer with relevant excerpts.

### Method
GET

### Endpoint
https://toss-ads.gitbook.io/guide/account.md

### Parameters
#### Query Parameters
- **ask** (string) - Required - The specific, self-contained question to ask the documentation.
- **goal** (string) - Optional - The broader end goal to help tailor the response context.
```

--------------------------------

### GET /guide/review.md

Source: https://toss-ads.gitbook.io/guide/review

Queries the documentation for specific information using a natural language question and an optional goal.

```APIDOC
## GET /guide/review.md

### Description
Queries the documentation dynamically to retrieve answers, relevant excerpts, and sources based on a provided question.

### Method
GET

### Endpoint
https://toss-ads.gitbook.io/guide/review.md

### Parameters
#### Query Parameters
- **ask** (string) - Required - The specific, self-contained question in natural language.
- **goal** (string) - Optional - The broader end goal to help tailor the response.
```

--------------------------------

### GET /guide/billing.md

Source: https://toss-ads.gitbook.io/guide/billing

Queries the documentation for specific information using natural language questions.

```APIDOC
## GET /guide/billing.md

### Description
Queries the documentation dynamically by providing a natural language question. This is useful for retrieving information not explicitly detailed on the current page.

### Method
GET

### Endpoint
https://toss-ads.gitbook.io/guide/billing.md

### Parameters
#### Query Parameters
- **ask** (string) - Required - The specific, self-contained question to ask the documentation.
- **goal** (string) - Optional - The broader end goal to help tailor the response context.
```

--------------------------------

### GET /guide/targeting/list.md

Source: https://toss-ads.gitbook.io/guide/llms.txt

Performs a natural language query against the documentation index to retrieve an answer and relevant sources.

```APIDOC
## GET /guide/targeting/list.md

### Description
Perform an HTTP GET request on the documentation index to ask a specific question and optionally provide an end goal for context.

### Method
GET

### Endpoint
https://toss-ads.gitbook.io/guide/targeting/list.md

### Parameters
#### Query Parameters
- **ask** (string) - Required - The immediate question to ask, written in natural language.
- **goal** (string) - Optional - Describes the broader end goal to help tailor the answer.
```

--------------------------------

### Test Landing URL Example

Source: https://toss-ads.gitbook.io/guide/tracking/tosspixel/preservationguide.md

Use this URL format to verify that the tcid parameter is correctly passed to the landing page.

```http
https://www.example.com/?tcid=t2_test_6def583292221593d7951f7f9d454bc6e2e624d1dd
```

--------------------------------

### GET /guide/reports.md

Source: https://toss-ads.gitbook.io/guide/reports

Performs a dynamic query against the documentation page to retrieve answers and relevant excerpts based on a user question.

```APIDOC
## GET /guide/reports.md

### Description
Queries the documentation dynamically to get answers to specific questions, optionally providing a goal to tailor the response.

### Method
GET

### Endpoint
https://toss-ads.gitbook.io/guide/reports.md

### Parameters
#### Query Parameters
- **ask** (string) - Required - The specific, self-contained question to ask.
- **goal** (string) - Optional - The broader end goal to help tailor the answer.
```

--------------------------------

### GET /targeting.md

Source: https://toss-ads.gitbook.io/guide/targeting

Queries the documentation for specific information regarding targeting configurations using natural language.

```APIDOC
## GET /targeting.md

### Description
Queries the documentation dynamically by asking a question to retrieve information or context about targeting settings.

### Method
GET

### Endpoint
https://toss-ads.gitbook.io/guide/targeting.md

### Parameters
#### Query Parameters
- **ask** (string) - Required - The specific, self-contained question written in natural language.
- **goal** (string) - Optional - The broader end goal to help tailor the response.

### Response
#### Success Response (200)
- **answer** (string) - A direct answer to the question.
- **excerpts** (array) - Relevant excerpts and sources from the documentation.
```

--------------------------------

### GET /guide/catalog.md

Source: https://toss-ads.gitbook.io/guide/catalog

현재 문서 페이지를 대상으로 질문을 던져 관련 정보와 소스를 동적으로 조회합니다.

```APIDOC
## GET /guide/catalog.md

### Description
현재 문서 페이지를 대상으로 질문을 던져 관련 정보와 소스를 동적으로 조회합니다.

### Method
GET

### Endpoint
https://toss-ads.gitbook.io/guide/catalog.md

### Parameters
#### Query Parameters
- **ask** (string) - Required - 질문 내용
- **goal** (string) - Optional - 최종 목표
```

--------------------------------

### GitBook 문서 동적 쿼리 요청

Source: https://toss-ads.gitbook.io/guide/a-d/purchase/banner-guide.md

HTTP GET 요청을 통해 특정 페이지에 대한 질문을 수행하고 관련 문서를 검색합니다.

```http
GET https://toss-ads.gitbook.io/guide/a-d/purchase/banner-guide.md?ask=<question>&goal=<endgoal>
```

--------------------------------

### 카탈로그 문서 질의 API 호출

Source: https://toss-ads.gitbook.io/guide/catalog/spec.md

GitBook 문서 내에서 특정 정보를 검색하기 위해 HTTP GET 요청을 수행합니다.

```http
GET https://toss-ads.gitbook.io/guide/catalog/spec.md?ask=<question>&goal=<endgoal>
```

--------------------------------

### Track Subscribe Events

Source: https://toss-ads.gitbook.io/guide/tracking/tosspixel/preservationguide-1.md

Call this function when a user starts a subscription or requests notifications.

```html
<script>
  TossPixel('전환 코드').subscribe({
    lead_type: "Newsletter",
    custom_param1: "push_opt_in",
    custom_param2: "app"
  });
</script>
```

--------------------------------

### GitBook 문서 쿼리 요청

Source: https://toss-ads.gitbook.io/guide/reward/shortform/data.md

HTTP GET 요청을 통해 문서 내에서 특정 질문에 대한 답변을 동적으로 조회합니다.

```http
GET https://toss-ads.gitbook.io/guide/reward/shortform/data.md?ask=<question>&goal=<endgoal>
```

--------------------------------

### 타겟 조합 정보 조회 API 호출

Source: https://toss-ads.gitbook.io/guide/targeting/combinations.md

GitBook 문서 내에서 특정 정보를 찾기 위해 HTTP GET 요청을 수행하는 방법입니다.

```http
GET https://toss-ads.gitbook.io/guide/targeting/combinations.md?ask=<question>&goal=<endgoal>
```

--------------------------------

### 광고 반응 타겟 정보 조회

Source: https://toss-ads.gitbook.io/guide/targeting/retarget.md

HTTP GET 요청을 통해 현재 페이지의 문맥 내에서 특정 질문에 대한 답변을 조회합니다.

```http
GET https://toss-ads.gitbook.io/guide/targeting/retarget.md?ask=<question>&goal=<endgoal>
```

--------------------------------

### 맞춤 보고서 문서 쿼리하기

Source: https://toss-ads.gitbook.io/guide/reports/report.md

HTTP GET 요청을 통해 현재 페이지의 문서 내용을 동적으로 질의할 수 있습니다.

```http
GET https://toss-ads.gitbook.io/guide/reports/report.md?ask=<question>&goal=<endgoal>
```

--------------------------------

### 문서 쿼리를 위한 HTTP GET 요청

Source: https://toss-ads.gitbook.io/guide/tracking/tag/code_generation.md

GitBook 문서 페이지에 대해 특정 질문을 던지고 응답을 받기 위한 API 호출 예시입니다.

```http
GET https://toss-ads.gitbook.io/guide/tracking/tag/code_generation.md?ask=<question>&goal=<endgoal>
```

--------------------------------

### 문서 정보 동적 쿼리 요청

Source: https://toss-ads.gitbook.io/guide/reward/money-notifications/data.md

HTTP GET 요청을 통해 문서 내에서 특정 질문에 대한 답변과 관련 정보를 검색합니다.

```http
GET https://toss-ads.gitbook.io/guide/reward/money-notifications/data.md?ask=<question>&goal=<endgoal>
```

--------------------------------

### 전환 추적 코드 관련 정보 조회

Source: https://toss-ads.gitbook.io/guide/tracking/tag/privacy_control.md

현재 페이지의 정보를 바탕으로 추가적인 질문을 수행하기 위한 HTTP GET 요청 예시입니다.

```http
GET https://toss-ads.gitbook.io/guide/tracking/tag/privacy_control.md?ask=<question>&goal=<endgoal>
```

--------------------------------

### 전환 추적 타겟 정보 조회 API 요청

Source: https://toss-ads.gitbook.io/guide/targeting/switch.md

HTTP GET 요청을 통해 특정 페이지의 전환 추적 타겟 관련 정보를 질의합니다.

```http
GET https://toss-ads.gitbook.io/guide/targeting/switch.md?ask=<question>&goal=<endgoal>
```

--------------------------------

### 숏폼 광고 정보 조회 API 요청

Source: https://toss-ads.gitbook.io/guide/reward/shortform.md

특정 페이지에 대해 질문하거나 추가 정보를 얻기 위해 HTTP GET 요청을 수행합니다.

```http
GET https://toss-ads.gitbook.io/guide/reward/shortform.md?ask=<question>&goal=<endgoal>
```

--------------------------------

### 문서 검색을 위한 HTTP GET 요청

Source: https://toss-ads.gitbook.io/guide/a-d/features.md

현재 페이지 URL에 ask 및 goal 파라미터를 추가하여 문서 내 정보를 동적으로 조회합니다.

```http
GET https://toss-ads.gitbook.io/guide/a-d/features.md?ask=<question>&goal=<endgoal>
```

--------------------------------

### 토스애즈 문서 질의 API 호출

Source: https://toss-ads.gitbook.io/guide/account/account-1.md

HTTP GET 요청을 통해 현재 문서 페이지에 대한 질문을 수행하고 관련 정보를 조회합니다.

```http
GET https://toss-ads.gitbook.io/guide/account/account-1.md?ask=<question>&goal=<endgoal>
```

--------------------------------

### 라이브 마켓 문서 질의 API 요청

Source: https://toss-ads.gitbook.io/guide/reward/liveshopping.md

HTTP GET 요청을 통해 라이브 마켓 문서에 대해 질문하고 답변을 얻을 수 있습니다.

```http
GET https://toss-ads.gitbook.io/guide/reward/liveshopping.md?ask=<question>&goal=<endgoal>
```

--------------------------------

### TossPixel.signUp()

Source: https://toss-ads.gitbook.io/guide/tracking/tosspixel/preservationguide-1.md

Tracks a user sign-up event.

```APIDOC
## TossPixel.signUp()

### Description
Tracks when a user completes the sign-up process.

### Method
JavaScript SDK Method

### Parameters
- **custom_param1/2** (string) - Optional - Custom tracking parameters.
```

--------------------------------

### 토스 픽셀 이벤트 메서드

Source: https://toss-ads.gitbook.io/guide/tracking/tosspixel.md

토스 픽셀 SDK에서 제공하는 이벤트 추적 메서드 목록입니다. 각 메서드는 웹사이트 내 특정 사용자 행동을 기록합니다.

```APIDOC
## 토스 픽셀 이벤트 메서드

### 설명
웹사이트 내 사용자 행동을 추적하기 위해 호출하는 SDK 메서드입니다.

### 메서드 목록
- **purchase()** - 결제 및 주문 완료(매출 발생)
- **signUp()** - 회원가입 완료
- **lead()** - 상담 신청, 양식 제출
- **productView()** - 상품/콘텐츠 상세 페이지 조회
- **addToCart()** - 장바구니 상품 추가
- **initiateCheckout()** - 결제/주문 페이지 진입
- **install()** - 앱 설치 완료
- **appOpen()** - 앱 실행
- **search()** - 서비스 내 검색 결과 조회
- **signIn()** - 로그인 완료
- **pageView()** - 페이지 방문
- **viewHome()** - 홈 화면 방문
- **firstPurchase()** - 첫 구매 완료
- **getOffer()** - 쿠폰 다운로드 / 혜택 수령
- **addToWishlist()** - 상품 위시리스트 추가
- **subscribe()** - 알림 신청 / 구독 시작
- **appDeeplinkOpen()** - 딥링크를 통한 앱 실행
- **preRegister()** - 사전 예약 / 런칭 전 등록
- **viewLimit()** - 대출/보험료 한도 조회
- **applyScreening()** - 가심사 조회 / 적격 확인
- **adImpression()** - 광고 노출 (매출 발생)
- **custom()** - 자유롭게 정의 가능한 커스텀 이벤트
```

--------------------------------

### TossPixel.initiateCheckout()

Source: https://toss-ads.gitbook.io/guide/tracking/tosspixel/preservationguide-1.md

Tracks when a user enters the checkout or order page.

```APIDOC
## TossPixel.initiateCheckout()

### Description
Tracks the initiation of the checkout process.

### Method
JavaScript SDK Method

### Parameters
- **order_id** (string) - Required - Order identifier.
- **revenue** (number) - Required - Total order value.
- **products** (array) - Required - List of products in checkout.
```

--------------------------------

### TossPixel.signIn()

Source: https://toss-ads.gitbook.io/guide/tracking/tosspixel/preservationguide-1.md

Tracks user login events.

```APIDOC
## TossPixel.signIn()

### Description
Tracks when a user successfully logs in.

### Method
JavaScript SDK Method
```

--------------------------------

### TossPixel.firstPurchase()

Source: https://toss-ads.gitbook.io/guide/tracking/tosspixel/preservationguide-1.md

Tracks the first purchase event.

```APIDOC
## TossPixel.firstPurchase()

### Description
Tracks the first successful purchase by a user.
```

--------------------------------

### TossPixel.getOffer()

Source: https://toss-ads.gitbook.io/guide/tracking/tosspixel/preservationguide-1.md

Tracks coupon downloads or benefit claims.

```APIDOC
## TossPixel.getOffer()

### Description
Tracks when a user downloads a coupon or claims an offer.
```

--------------------------------

### TossPixel.viewHome()

Source: https://toss-ads.gitbook.io/guide/tracking/tosspixel/preservationguide-1.md

Tracks visits to the home page.

```APIDOC
## TossPixel.viewHome()

### Description
Tracks when a user visits the home screen.
```

--------------------------------

### 카탈로그 광고 정보 조회 API 요청

Source: https://toss-ads.gitbook.io/guide/review/catalog.md

문서 내 정보를 동적으로 조회하기 위해 사용하는 HTTP GET 요청 예시입니다.

```http
GET https://toss-ads.gitbook.io/guide/review/catalog.md?ask=<question>&goal=<endgoal>
```

--------------------------------

### 웹훅 서명 검증 가이드

Source: https://toss-ads.gitbook.io/guide/tracking/webhook.md

웹훅 요청의 무결성을 보장하기 위한 서명 검증 로직입니다. 요청 헤더의 타임스탬프와 서명을 사용하여 요청이 변조되지 않았는지 확인합니다.

```APIDOC
## 웹훅 서명 검증

### 설명
토스애즈로부터 전달받은 웹훅 요청의 유효성을 검증합니다. 요청 본문과 타임스탬프를 사용하여 HMAC-SHA256 서명을 생성하고, 헤더의 `X-TossAds-Signature`와 비교합니다.

### 검증 단계
1. **타임스탬프 확인**: `X-TossAds-Timestamp`와 현재 시간의 차이가 300초(5분) 이내인지 확인합니다.
2. **서명 생성**: `{timestamp}.{body}` 문자열을 시크릿 키로 HMAC-SHA256 해싱합니다.
3. **서명 비교**: 헤더의 `X-TossAds-Signature` 값과 생성한 서명을 대조합니다. 다중 서명(콤마로 구분)이 전달될 경우, 하나라도 일치하면 유효한 것으로 간주합니다.

### 헤더
- **X-TossAds-Timestamp** (string) - 요청 발생 시간(Unix timestamp)
- **X-TossAds-Signature** (string) - HMAC-SHA256 서명 값 (예: v1=ab12cd34...)
```

--------------------------------

### preRegister()

Source: https://toss-ads.gitbook.io/guide/tracking/tosspixel/preservationguide-1.md

Tracks a pre-registration or pre-launch sign-up event.

```APIDOC
## preRegister()

### Description
Call this method when a pre-registration or pre-launch sign-up is completed.

### Parameters
- **params** (object) - Required - An object containing event details such as product_id, product_name, lead_type, and custom parameters.
```

--------------------------------

### SDK 스크립트 로드

Source: https://toss-ads.gitbook.io/guide/tracking/tosspixel/24.md

카페24의 layout.html 파일 내 <head> 태그 안에 추가하여 사이트 전체에서 SDK를 로드합니다.

```typescript
<!-- Toss Pixel SDK 로드 -->
<script src="https://static.toss.im/lex/v1.js"></script>
```

--------------------------------

### 토스 픽셀 SDK 스크립트 설치

Source: https://toss-ads.gitbook.io/guide/tracking/tosspixel/preservationguide-1.md

모든 페이지의 <head> 태그 내에 SDK 스크립트를 추가합니다. async 또는 defer 속성을 사용하지 마세요.

```javascript
<head>
    <!-- 기존 태그들 -->
    <script src="https://static.toss.im/lex/v1.js"></script>
</head>
```

--------------------------------

### TossPixel.productView()

Source: https://toss-ads.gitbook.io/guide/tracking/tosspixel/preservationguide-1.md

Tracks when a user views a product or content detail page.

```APIDOC
## TossPixel.productView()

### Description
Tracks the viewing of a specific product or content detail page.

### Method
JavaScript SDK Method

### Parameters
- **product_id** (string) - Required - Unique product identifier.
- **product_name** (string) - Required - Name of the product.
- **category_id/name** (string) - Optional - Category information.
- **price** (number) - Optional - Product price.
- **currency** (string) - Optional - Currency code.
```

--------------------------------

### 머니알림 문서 조회 API 호출

Source: https://toss-ads.gitbook.io/guide/reward/money-notifications.md

현재 페이지의 URL을 사용하여 머니알림 관련 정보를 동적으로 조회하는 HTTP GET 요청 예시입니다.

```http
GET https://toss-ads.gitbook.io/guide/reward/money-notifications.md?ask=<question>&goal=<endgoal>
```

--------------------------------

### TossPixel.lead()

Source: https://toss-ads.gitbook.io/guide/tracking/tosspixel/preservationguide-1.md

Tracks lead generation events like form submissions or consultations.

```APIDOC
## TossPixel.lead()

### Description
Tracks when a lead is captured, such as a consultation request or form submission.

### Method
JavaScript SDK Method

### Parameters
- **lead_type** (string) - Required - The type of lead (e.g., Consultation, Event, TestDrive).
- **custom_param1/2** (string) - Optional - Custom tracking parameters.
```

--------------------------------

### SDK 스크립트 설치

Source: https://toss-ads.gitbook.io/guide/tracking/tosspixel/preservationguide-1.md

모든 페이지의 <head> 태그 안에 토스 픽셀 SDK 스크립트를 추가하여 픽셀을 초기화합니다.

```APIDOC
## SDK 스크립트 설치

### Description
모든 페이지에 공통으로 적용되는 레이아웃 파일의 <head> 태그 안에 아래 스크립트를 추가합니다. SDK는 사이트 전체에서 한 번만 로딩하면 됩니다.

### Implementation
```html
<head>
    <script src="https://static.toss.im/lex/v1.js"></script>
</head>
```

### Notes
- SDK 스크립트에는 async 또는 defer 속성을 사용하지 마세요.
- 이벤트 코드보다 먼저 로딩되어야 합니다.
```

--------------------------------

### TossPixel.subscribe()

Source: https://toss-ads.gitbook.io/guide/tracking/tosspixel/preservationguide-1.md

Tracks subscription or notification opt-in events.

```APIDOC
## TossPixel.subscribe()

### Description
Tracks when a user starts a subscription or opts into notifications.
```

--------------------------------

### TossPixel.addToWishlist()

Source: https://toss-ads.gitbook.io/guide/tracking/tosspixel/preservationguide-1.md

Tracks when a user adds an item to their wishlist.

```APIDOC
## TossPixel.addToWishlist()

### Description
Tracks the addition of a product to the user's wishlist.
```

--------------------------------

### Track Pre-registration Event

Source: https://toss-ads.gitbook.io/guide/tracking/tosspixel/preservationguide-1.md

Call this method when a pre-registration or pre-launch sign-up is completed.

```html
<script>
  TossPixel('전환 코드').preRegister({
    product_id: "PRD_PRE_001",
    product_name: "신규 멤버십",
    lead_type: "Preorder",
    custom_param1: "launch_campaign"
  });
</script>
```

--------------------------------

### Toss Pixel Parameters Reference

Source: https://toss-ads.gitbook.io/guide/tracking/tosspixel.md

A list of supported parameters for Toss Pixel events. All parameters are optional and should be replaced with actual data.

```APIDOC
## Toss Pixel Parameters

### Description
This table lists the parameters that can be sent with Toss Pixel events to enhance tracking precision. All parameters are optional.

### Parameters
- **order_id** (String) - Optional - Order ID
- **product_id** (String) - Optional - Product ID
- **product_name** (String) - Optional - Product name
- **category_id** (String) - Optional - Product category ID
- **category_name** (String) - Optional - Product category name
- **price** (Number) - Optional - Product price
- **quantity** (Number) - Optional - Product quantity
- **revenue** (Number) - Optional - Total revenue
- **total_quantity** (Number) - Optional - Total quantity
- **currency** (String) - Optional - Currency (ISO 4217 format, e.g., KRW, USD)
- **purchase_type** (String) - Optional - Payment method
- **lead_type** (String) - Optional - Lead type
- **products** (Array) - Optional - List of products
- **custom_param1** (String) - Optional - Custom Parameter 1
- **custom_param2** (String) - Optional - Custom Parameter 2
- **custom_param3** (String) - Optional - Custom Parameter 3
- **custom_param4** (String) - Optional - Custom Parameter 4
- **custom_param5** (String) - Optional - Custom Parameter 5
```

--------------------------------

### TossPixel.purchase()

Source: https://toss-ads.gitbook.io/guide/tracking/tosspixel/preservationguide-1.md

Tracks a completed purchase or order event.

```APIDOC
## TossPixel.purchase()

### Description
Tracks a purchase event when an order is successfully completed.

### Method
JavaScript SDK Method

### Parameters
- **order_id** (string) - Required - Unique identifier for the order.
- **revenue** (number) - Required - Total revenue amount.
- **total_quantity** (number) - Required - Total number of items purchased.
- **currency** (string) - Required - Currency code (e.g., KRW).
- **purchase_type** (string) - Optional - Payment method type.
- **products** (array) - Optional - List of product objects.
- **custom_param1/2** (string) - Optional - Custom tracking parameters.
```

--------------------------------

### TossPixel.addToCart()

Source: https://toss-ads.gitbook.io/guide/tracking/tosspixel/preservationguide-1.md

Tracks when a user adds an item to their shopping cart.

```APIDOC
## TossPixel.addToCart()

### Description
Tracks the action of adding a product to the shopping cart.

### Method
JavaScript SDK Method

### Parameters
- **revenue** (number) - Required - Total value of items in cart.
- **total_quantity** (number) - Required - Total quantity of items.
- **currency** (string) - Required - Currency code.
- **products** (array) - Required - List of product objects.
```

--------------------------------

### TossPixel('전환 코드').addToCart()

Source: https://toss-ads.gitbook.io/guide/tracking/tosspixel/makeshop.md

Tracks the 'Add to Cart' event when a user clicks the cart button on the product detail page.

```APIDOC
## TossPixel('전환 코드').addToCart()

### Description
Tracks when a user adds a product to their shopping cart.

### Parameters
- **product_id** (string) - Required - The unique identifier of the product.
- **product_name** (string) - Required - The name of the product.
- **price** (number) - Required - The price of the product.
- **currency** (string) - Required - The currency code (e.g., KRW).

### Request Example
```javascript
TossPixel('전환 코드').addToCart({
  product_id: "12345",
  product_name: "Sample Product",
  price: 10000,
  currency: "KRW"
});
```
```

--------------------------------

### TossPixel.pageView()

Source: https://toss-ads.gitbook.io/guide/tracking/tosspixel/preservationguide-1.md

Tracks page visits.

```APIDOC
## TossPixel.pageView()

### Description
Tracks a general page visit.
```

--------------------------------

### 토스 픽셀 이벤트에 커스텀 프로퍼티 추가하기

Source: https://toss-ads.gitbook.io/guide/tracking/tosspixel/24.md

표준 이벤트와 커스텀 이벤트 호출 시 객체 내에 custom_param1부터 custom_param5까지의 속성을 포함하여 전달합니다.

```javascript
<!-- 표준 이벤트에 커스텀 프로퍼티 추가 -->
<script>
    // '전환 코드' 대신 생성한 전환코드 값을 넣어주세요
    TossPixel('전환 코드').purchase({
        total_price: "{$total_order_price_original}",
        currency: "{$product_total_price_ref}",
        custom_param1: "summer_sale",
        custom_param2: "landing_A"
    });
</script>

<!-- 커스텀 이벤트에 커스텀 프로퍼티 추가 -->
<script>
    // '전환 코드' 대신 생성한 전환코드 값을 넣어주세요
    TossPixel('전환 코드').custom('BUTTON_CLICK', {
        product_id: "{$product_no}",
        custom_param1: "cta_top",
        custom_param2: "variant_B"
    });
</script>
```

--------------------------------

### 상품 상세 페이지 조회 이벤트 추적

Source: https://toss-ads.gitbook.io/guide/tracking/tosspixel/makeshop.md

상품 상세 페이지 파일 하단에 추가하여 상품 정보를 포함한 productView 이벤트를 전송합니다. 메이크샵의 변수 치환 기능을 활용하여 상품 데이터를 동적으로 가져옵니다.

```html
<script>
    // Toss Pixel 상품 상세 조회 이벤트 수집
    var priceElement = '<!--/price_sell/-->';
    var tempDiv = document.createElement('div');
    tempDiv.innerHTML = priceElement;
    var priceText = tempDiv.textContent || tempDiv.innerText || priceElement;
    var priceValue = parseInt(priceText.replace(/[^0-9]/g, ''), 10) || 0;
    // '전환 코드' 대신 생성한 전환코드 값을 넣어주세요
    TossPixel('전환 코드').productView({
        product_id: "<!--/number/-->",
        product_name: "<!--/name/-->",
        price: priceValue,
        currency: "<!--/currency_name/-->"
    });
</script>
```

--------------------------------

### Track Sign Up Events

Source: https://toss-ads.gitbook.io/guide/tracking/tosspixel/preservationguide-1.md

Call this function when a user registration is completed.

```html
<script>
  TossPixel('전환 코드').signUp({
    custom_param1: "email",
    custom_param2: "normal_signup"
  });
</script>
```

--------------------------------

### Track First Purchase Events

Source: https://toss-ads.gitbook.io/guide/tracking/tosspixel/preservationguide-1.md

Call this function when a user completes their first purchase.

```html
<script>
  TossPixel('전환 코드').firstPurchase({
    order_id: "ORDER_20260423_0002",
    revenue: 39000,
    total_quantity: 1,
    currency: "KRW",
    purchase_type: "CARD",
    products: [
      {
        product_id: "P12345",
        product_name: "오가닉 코튼 티셔츠",
        category_id: "C100",
        category_name: "상의",
        price: 39000,
        quantity: 1
      }
    ],
    custom_param1: "new_buyer"
  });
</script>
```

--------------------------------

### Kotlin (Spring Boot) 웹훅 서명 검증

Source: https://toss-ads.gitbook.io/guide/tracking/webhook.md

Spring Boot 환경에서 raw 바이트를 수신하여 HMAC-SHA256 서명을 검증하고 타임스탬프를 확인하는 예제입니다.

```kotlin
import javax.crypto.Mac
import javax.crypto.spec.SecretKeySpec
import java.security.MessageDigest
import java.time.Instant
import kotlin.math.abs

// 토스애즈 대시보드에서 발급받은 시크릿 키 (환경변수 등으로 주입)
@Value("${toss-ads.webhook.secret-key}")
private lateinit var secretKey: String

/**
 * 웹훅 수신 엔드포인트.
 * body는 raw bytes로 수신해야 한다. JSON 파싱 후 재직렬화하면 바이트가 달라져 서명 검증에 실패한다.
 */
@PostMapping("/webhook/toss-ads")
fun receiveWebhook(
    @RequestHeader("X-TossAds-Timestamp") timestamp: String,
    @RequestHeader("X-TossAds-Signature") signature: String,
    @RequestBody body: ByteArray,
): ResponseEntity<String> {

    // 1. 서명 입력 조립: "{timestamp}.{body}"
    val signingInput = "${timestamp}.".toByteArray() + body

    // 2. HMAC-SHA256 계산 (소문자 hex)
    val mac = Mac.getInstance("HmacSHA256")
    mac.init(SecretKeySpec(secretKey.toByteArray(), "HmacSHA256"))
    val expected = mac.doFinal(signingInput).joinToString("") { "%02x".format(it) }

    // 3. 헤더의 서명을 콤마로 split → 하나라도 매치하면 통과 (듀얼 시그니처 대응)
    val isValid = signature.split(",").any { part ->
        val sigValue = part.trim().substringAfter("=")
        MessageDigest.isEqual(expected.toByteArray(), sigValue.toByteArray())
    }
    if (!isValid) {
        return ResponseEntity.status(401).body("Invalid signature")
    }

    // 4. 서명이 유효한 것을 확인한 뒤에야 타임스탬프를 신뢰할 수 있다.
    //    서명에 타임스탬프가 포함되어 있으므로, 서명 통과 = 타임스탬프 미조작 보장.
    //    이후 ±5분 검증으로 replay attack 방어.
    val requestTime = timestamp.toLongOrNull()
        ?: return ResponseEntity.badRequest().body("Invalid timestamp")
    if (abs(Instant.now().epochSecond - requestTime) > 300) {
        return ResponseEntity.status(401).body("Timestamp expired")
    }

    // 5. 검증 통과 — 페이로드 파싱 후 처리
    val payload = objectMapper.readValue(body, Map::class.java)
    // lead_id를 기준으로 중복 처리한 뒤 저장하세요.
    return ResponseEntity.ok("OK")
}
```

--------------------------------

### TossPixel('전환 코드').purchase()

Source: https://toss-ads.gitbook.io/guide/tracking/tosspixel/makeshop.md

Tracks the completion of an order on the order confirmation page.

```APIDOC
## TossPixel('전환 코드').purchase()

### Description
Tracks a successful purchase event, including order details and product list.

### Parameters
- **order_id** (string) - Required - The unique order identifier.
- **products** (array) - Required - List of purchased products.
- **revenue** (number) - Required - Total revenue of the order.
- **total_quantity** (number) - Required - Total number of items purchased.

### Request Example
```javascript
TossPixel('전환 코드').purchase({
  order_id: "ORD-001",
  products: [{ product_id: "1", product_name: "Item", quantity: 1, price: 10000, options: ["Red"] }],
  revenue: 10000,
  total_quantity: 1
});
```
```

--------------------------------

### Track Initiate Checkout Events

Source: https://toss-ads.gitbook.io/guide/tracking/tosspixel/preservationguide-1.md

Call this function when a user enters the checkout or order page.

```html
<script>
  TossPixel('전환 코드').initiateCheckout({
    order_id: "ORDER_20260423_0001",
    revenue: 78000,
    total_quantity: 2,
    currency: "KRW",
    products: [
      {
        product_id: "P12345",
        product_name: "오가닉 코튼 티셔츠",
        category_id: "C100",
        category_name: "상의",
        price: 39000,
        quantity: 1
      },
      {
        product_id: "P67890",
        product_name: "와이드 데님 팬츠",
        category_id: "C200",
        category_name: "하의",
        price: 39000,
        quantity: 1
      }
    ],
    custom_param1: "checkout_page"
  });
</script>
```

--------------------------------

### viewLimit()

Source: https://toss-ads.gitbook.io/guide/tracking/tosspixel/preservationguide-1.md

Tracks the completion of a loan or insurance limit inquiry.

```APIDOC
## viewLimit()

### Description
Call this method when a loan or insurance limit inquiry is completed.

### Parameters
- **params** (object) - Required - An object containing event details such as lead_type and custom parameters.
```

--------------------------------

### Collect Product Data

Source: https://toss-ads.gitbook.io/guide/tracking/tosspixel/24.md

Add this script within each product module in the order completion file to collect product details.

```javascript
<script>
    tossPixelOrderProducts.push({
        product_id: "{$product_no}",
        product_name:"{$product_name}",
        quantity: "{$product_quantity}",
        price:"{$product_price}",
        options: ["{$option_detail_str}"],
    });
</script>
```

--------------------------------

### TossPixel.search()

Source: https://toss-ads.gitbook.io/guide/tracking/tosspixel/preservationguide-1.md

Tracks search queries performed within the service.

```APIDOC
## TossPixel.search()

### Description
Tracks search result views.

### Method
JavaScript SDK Method

### Parameters
- **category_id/name** (string) - Optional - Category context.
- **custom_param1/2** (string) - Optional - Search query or context.
```

--------------------------------

### Track Offer Retrieval Events

Source: https://toss-ads.gitbook.io/guide/tracking/tosspixel/preservationguide-1.md

Call this function when a user downloads a coupon or receives a benefit.

```html
<script>
  TossPixel('전환 코드').getOffer({
    custom_param1: "WELCOME10",
    custom_param2: "download_coupon"
  });
</script>
```

--------------------------------

### Track Home View Events

Source: https://toss-ads.gitbook.io/guide/tracking/tosspixel/preservationguide-1.md

Call this function when a user visits the home screen.

```html
<script>
  TossPixel('전환 코드').viewHome({
    custom_param1: "main_home",
    custom_param2: "logged_in"
  });
</script>
```

--------------------------------

### 앱 스킴 등록하기

Source: https://toss-ads.gitbook.io/guide/a-d/app-install/link-guide.md

iOS의 Info.plist와 Android의 AndroidManifest.xml에 커스텀 URL 스킴을 등록하는 설정입니다.

```xml
<key>CFBundleURLTypes</key>
<array>
  <dict>
    <key>CFBundleURLSchemes</key>
    <array><string>brandapp</string></array>
  </dict>
</array>
```

```xml
<intent-filter>
  <action android:name="android.intent.action.VIEW" />
  <category android:name="android.intent.category.DEFAULT" />
  <category android:name="android.intent.category.BROWSABLE" />
  <data android:scheme="brandapp" />
</intent-filter>
```

--------------------------------

### pageView()

Source: https://toss-ads.gitbook.io/guide/tracking/tosspixel/preservationguide-1.md

Tracks page views, typically used in SPA environments.

```APIDOC
## pageView()

### Description
Call this method when the route changes in an SPA environment to track page views.
```

--------------------------------

### 상품 상세 조회 이벤트 추적

Source: https://toss-ads.gitbook.io/guide/tracking/tosspixel/24.md

상품 상세 파일(/product/detail.html)의 module="product_detail" 태그 안쪽에 추가합니다.

```javascript
<!-- Toss Pixel 상품 상세 조회 이벤트 -->
<script>
    // '전환 코드' 대신 생성한 전환코드 값을 넣어주세요
    TossPixel('전환 코드').productView({
        product_id: "{$product_no}",
        product_name: "{$name}",
        price: "{$product_sale_price}",
        currency: "{$price_unit_tail}"
    });
</script>
```

--------------------------------

### 이벤트 스크립트 호출

Source: https://toss-ads.gitbook.io/guide/tracking/tosspixel/preservationguide-1.md

전환이 발생하는 지점에 토스 픽셀 이벤트 메서드를 호출하여 데이터를 수집합니다.

```APIDOC
## 이벤트 스크립트 호출

### Description
전환이 발생하는 지점에 토스 픽셀 이벤트 메서드를 호출합니다. 모든 파라미터는 선택사항이며, 메서드만 호출해도 정상 수집됩니다.

### Supported Methods
- purchase(): 결제 및 주문 완료
- signUp(): 회원가입 완료
- lead(): 상담 신청, 양식 제출
- productView(): 상품/콘텐츠 상세 페이지 조회
- addToCart(): 장바구니 상품 추가
- initiateCheckout(): 결제/주문 페이지 진입
- search(): 서비스 내 검색 결과 조회
- signIn(): 로그인 완료
- pageView(): 페이지 방문
- viewHome(): 홈 화면 방문
- firstPurchase(): 첫 구매 완료
- getOffer(): 쿠폰 다운로드 / 혜택 수령
- addToWishlist(): 상품 위시리스트 추가
- subscribe(): 알림 신청 / 구독 시작
- preRegister(): 사전 예약 / 런칭 전 등록
- viewLimit(): 대출/보험료 한도 조회
- applyScreening(): 가심사 조회 / 적격 확인
- custom(): 자유롭게 정의 가능한 커스텀 이벤트

### Parameters
- order_id (String): 주문 ID
- product_id (String): 상품 ID
- product_name (String): 상품명
- category_id (String): 상품 카테고리 ID
- category_name (String): 상품 카테고리명
- price (Number): 상품 가격
- quantity (Number): 상품 개수
- revenue (Number): 전체 상품 가격
- total_quantity (Number): 전체 상품 개수
- currency (String): 통화 (ISO 4217)
- purchase_type (String): 결제 수단
- lead_type (String): 리드 유형
- products (Array): 상품 목록
- custom_param1~5 (String): 커스텀 파라미터
```

--------------------------------

### 랜딩 페이지 링크 형식 예시

Source: https://toss-ads.gitbook.io/guide/review/creativeguide.md

광고 집행 시 트래킹 유실 방지를 위해 숏링크 대신 UTM 파라미터가 포함된 원본 링크를 사용해야 합니다.

```jsx
<https://smart.link/d50fy6vjvwh>

<https://bit.ly/3QMVc>
```

```jsx
<https://tossadsplatform.oopy.io/2312promotion?utm_source=promodetail&utm_medium=openads&utm_campaign=2312promotion>
```

--------------------------------

### iOS Universal Link 처리

Source: https://toss-ads.gitbook.io/guide/a-d/app-install/link-guide.md

Swift에서 onContinueUserActivity를 사용하여 유입된 Universal Link를 처리하는 코드입니다.

```swift
.onContinueUserActivity(NSUserActivityTypeBrowsingWeb) { activity in
    guard let url = activity.webpageURL else { return }
    // url == https://go.brand.com/event/123
    router.handle(url)
}
```

--------------------------------

### Track Product View Events

Source: https://toss-ads.gitbook.io/guide/tracking/tosspixel/preservationguide-1.md

Call this function when a user views a product or content detail page.

```html
<script>
  TossPixel('전환 코드').productView({
    product_id: "P12345",
    product_name: "오가닉 코튼 티셔츠",
    category_id: "C100",
    category_name: "상의",
    price: 39000,
    currency: "KRW"
  });
</script>
```

--------------------------------

### Track Sign In Events

Source: https://toss-ads.gitbook.io/guide/tracking/tosspixel/preservationguide-1.md

Call this function when a user login is completed.

```html
<script>
  TossPixel('전환 코드').signIn({
    custom_param1: "email",
    custom_param2: "existing_user"
  });
</script>
```

--------------------------------

### 앱 내부 라우팅 구현하기

Source: https://toss-ads.gitbook.io/guide/a-d/app-install/link-guide.md

앱으로 전달된 커스텀 URL 스킴을 처리하여 특정 화면으로 라우팅하는 로직입니다.

```swift
.onOpenURL { url in
    // url == brandapp://event/123
    guard url.scheme == "brandapp" else { return }
    router.handle(host: url.host, path: url.path)
}
```

```kotlin
// onCreate / onNewIntent
val data: Uri? = intent?.data        // brandapp://event/123
if (data?.scheme == "brandapp") {
    router.handle(data.host, data.pathSegments)
}
```

--------------------------------

### TossPixel Custom Properties

Source: https://toss-ads.gitbook.io/guide/tracking/tosspixel/makeshop.md

How to include custom parameters in standard and custom event tracking calls.

```APIDOC
## TossPixel Custom Properties

### Description
Custom properties allow you to send additional information that cannot be captured by standard parameters. You can add up to 5 custom parameters (custom_param1 through custom_param5) to any event.

### Parameters
- **custom_param1** (string) - Optional - Custom property 1
- **custom_param2** (string) - Optional - Custom property 2
- **custom_param3** (string) - Optional - Custom property 3
- **custom_param4** (string) - Optional - Custom property 4
- **custom_param5** (string) - Optional - Custom property 5

### Usage Example (Standard Event)
```javascript
TossPixel('전환 코드').purchase({
    revenue: "{$total_order_price_original}",
    currency: "{$product_revenue_ref}",
    custom_param1: "summer_sale",
    custom_param2: "landing_A"
});
```

### Usage Example (Custom Event)
```javascript
TossPixel('전환 코드').custom('BUTTON_CLICK', {
    product_id: "{$product_no}",
    custom_param1: "cta_top",
    custom_param2: "variant_B"
});
```
```

--------------------------------

### TossPixel('전환 코드').custom()

Source: https://toss-ads.gitbook.io/guide/tracking/tosspixel/makeshop.md

Tracks custom events that do not fall under standard event categories.

```APIDOC
## TossPixel('전환 코드').custom()

### Description
Tracks a custom event with a user-defined name and optional parameters.

### Parameters
- **eventName** (string) - Required - The name of the custom event (e.g., "BUTTON_CLICK").
- **params** (object) - Optional - Additional data to include with the event.

### Request Example
```javascript
TossPixel('전환 코드').custom('BUTTON_CLICK', {
  product_id: "12345",
  product_name: "Sample Product",
  price: 10000,
  currency: "KRW"
});
```
```

--------------------------------

### applyScreening()

Source: https://toss-ads.gitbook.io/guide/tracking/tosspixel/preservationguide-1.md

Tracks the completion of a pre-screening or eligibility check.

```APIDOC
## applyScreening()

### Description
Call this method when a pre-screening or eligibility check is completed.

### Parameters
- **params** (object) - Required - An object containing event details such as lead_type and custom parameters.
```