> For the complete documentation index, see [llms.txt](https://docs.hackle.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hackle.io/imweb/events.md).

# 아임웹 이벤트 설명

## 아임웹 이벤트 설명 <a href="#imweb-event-description" id="imweb-event-description"></a>

{% hint style="info" %}
아임웹 연동 시 자동으로 수집되는 식별자와 사용자 속성, 이벤트를 정리했어요.

* 쇼핑몰 방문자의 로그인 여부에 따른 식별자 정보
* 쇼핑몰 회원 정보 기반으로 설정되는 사용자 속성 정보
* 쇼핑몰 유저의 행동에 대해 자동으로 수집되는 이벤트
  {% endhint %}

### 식별자 <a href="#identifiers" id="identifiers"></a>

<table><thead><tr><th width="154.6171875">식별자 이름</th><th>설명</th><th>예시</th></tr></thead><tbody><tr><td><code>userId</code></td><td>쇼핑몰에 로그인한 사용자는 이 식별자가 있어요.<br>아임웹 회원 ID(<code>memberUid</code>)와 동일한 값이며, 보통 이메일 형식이에요.</td><td><code>test_member@imweb.me</code></td></tr><tr><td><code>deviceId</code></td><td>쇼핑몰에 로그인하지 않은 사용자는 이 식별자만을 가져요.</td><td><code>5c5350475b5c555747594745063e.1774861304941</code></td></tr></tbody></table>

{% hint style="info" %}
사용자 식별자 관리하기에서 더 자세한 내용을 볼 수 있어요.
{% endhint %}

### 사용자 속성 <a href="#user-properties" id="user-properties"></a>

#### 페이지 접속 시 수집되는 속성 <a href="#page-visit-properties" id="page-visit-properties"></a>

사용자가 쇼핑몰 페이지에 접속한 시점의 값을 수집해요.

{% hint style="warning" %}
이 속성은 마지막으로 사용자가 쇼핑몰에 접속한 시점의 값입니다.
{% endhint %}

<details>

<summary>사용자 속성 보기</summary>

<table data-full-width="true"><thead><tr><th width="280">속성명</th><th>설명</th><th>예시</th></tr></thead><tbody><tr><td><code>__hackle__isimweb</code></td><td>아임웹 연동 유저임을 표시하는 값이에요. 항상 <code>true</code> 예요.</td><td><code>true</code></td></tr><tr><td><code>unit_code</code></td><td>아임웹 유닛 코드예요.</td><td><code>u2026092184d08946e2c63</code></td></tr><tr><td><code>member_id</code></td><td>회원 ID (<code>userId</code> 값과 동일)</td><td><code>test_member@imweb.me</code></td></tr><tr><td><code>last_visit_page</code></td><td>직전에 방문한 페이지 이름이에요.</td><td><code>mypage</code></td></tr><tr><td><code>last_visit_date</code></td><td>마지막 방문 일자 (yyyyMMdd 형식)</td><td><code>20260930</code></td></tr><tr><td><code>last_login_date</code></td><td>마지막 로그인 일자 (yyyyMMdd 형식)</td><td><code>20261001</code></td></tr></tbody></table>

</details>

{% hint style="info" %}
**수집되지 않는 속성이 있나요?**

모든 정보는 아임웹에서 제공해주는 값을 바탕으로 수집하고 있어요.

사용자 속성이 수집되지 않는다면 쇼핑몰의 회원가입 항목이 **필수**로 설정되어 있는지 확인해주세요.
{% endhint %}

#### 실시간으로 업데이트되는 속성 <a href="#realtime-updated-properties" id="realtime-updated-properties"></a>

사용자가 특정 행동을 한 직후에 바로 수집되는 속성이에요.

<details>

<summary>사용자 속성 보기</summary>

<table data-full-width="true"><thead><tr><th width="280">속성명</th><th>설명</th><th>예시</th></tr></thead><tbody><tr><td><code>join_datetime</code></td><td>가입 시각 (yyyy-MM-dd HH:mm:ss 형식)</td><td><code>2026-09-03 10:22:11</code></td></tr><tr><td><code>join_date</code></td><td>가입 일자 (yyyy-MM-dd 형식)</td><td><code>2026-09-03</code></td></tr><tr><td><code>join_date_num</code></td><td>가입 일자 (yyyyMMdd 형식)</td><td><code>20260903</code></td></tr><tr><td><code>join_month_day</code></td><td>가입 월일 (MM-dd 형식)</td><td><code>09-03</code></td></tr><tr><td><code>join_year</code></td><td>가입 연도 (yyyy 형식)</td><td><code>2026</code></td></tr><tr><td><code>name</code></td><td>회원 이름</td><td><code>홍길동</code></td></tr><tr><td><code>email</code></td><td>이메일 주소<br>가입 시점에 수집하며, 이후 회원 정보가 바뀌어도 갱신되지 않아요.</td><td><code>test_member@imweb.me</code></td></tr><tr><td><code>gender</code></td><td>성별 (아임웹에서 제공하는 값 그대로)<br>가입 시점에 수집하며, 이후 회원 정보가 바뀌어도 갱신되지 않아요.</td><td>-</td></tr><tr><td><code>birth_date</code></td><td>생년월일 (yyyy-MM-dd 형식)</td><td><code>1990-01-01</code></td></tr><tr><td><code>birth_date_num</code></td><td>생년월일 (yyyyMMdd 형식)</td><td><code>19900101</code></td></tr><tr><td><code>birth_month_day</code></td><td>생일 월일 (MM-dd 형식)</td><td><code>01-01</code></td></tr><tr><td><code>birth_year</code></td><td>출생 연도 (yyyy 형식)</td><td><code>1990</code></td></tr><tr><td>전화번호</td><td>회원 전화번호예요. E.164 형식으로 변환해 전화번호 속성으로 저장해요.<br>회원 탈퇴 시, 그리고 전화번호가 비어 있거나 변환할 수 없을 때는 삭제돼요.</td><td><code>+821012345678</code></td></tr><tr><td><code>sms</code></td><td>SMS 수신 동의 여부</td><td><code>true</code></td></tr><tr><td><code>third_party_agree</code></td><td>제3자 제공 동의 여부</td><td><code>true</code></td></tr><tr><td><code>grade_code</code></td><td>회원 등급 코드</td><td><code>g20250124563854a652d54</code></td></tr><tr><td><code>available_point</code></td><td>보유 적립금</td><td><code>"9000"</code></td></tr><tr><td><code>cart_last_added_date</code></td><td>마지막으로 장바구니에 상품을 담은 일자 (yyyy-MM-dd 형식)</td><td><code>2026-09-03</code></td></tr><tr><td><code>cart_last_added_date_num</code></td><td>마지막으로 장바구니에 상품을 담은 일자 (yyyyMMdd 형식)</td><td><code>20260903</code></td></tr></tbody></table>

</details>

#### 주기적으로 업데이트되는 속성 <a href="#periodically-updated-properties" id="periodically-updated-properties"></a>

{% hint style="warning" %}
핵클 서버가 주기적으로 정보를 수집하여 사용자 속성을 업데이트해요. 수집을 위해서는 핵클 팀에 별도로 연락해주세요.
{% endhint %}

<details>

<summary>사용자 속성 보기</summary>

<table data-full-width="true"><thead><tr><th width="280">속성명</th><th>설명</th><th>예시</th></tr></thead><tbody><tr><td><code>order_gross_first_date</code></td><td>첫 주문 일자 (yyyy-MM-dd 형식)<br>취소·반품은 반영하지 않아요.</td><td><code>2025-03-11</code></td></tr><tr><td><code>order_gross_last_date</code></td><td>마지막 주문 일자 (yyyy-MM-dd 형식)<br>취소·반품은 반영하지 않아요.</td><td><code>2026-09-07</code></td></tr><tr><td><code>order_gross_total_count</code></td><td>누적 주문 건수<br>취소·반품은 반영하지 않아요.</td><td><code>7</code></td></tr><tr><td><code>order_gross_total_price_amount</code></td><td>누적 주문 금액<br>취소·반품은 반영하지 않아요.</td><td><code>312000</code></td></tr><tr><td><code>order_gross_total_payment_amount</code></td><td>누적 실 결제 금액<br>취소·반품은 반영하지 않아요.</td><td><code>289000</code></td></tr><tr><td><code>cp_{couponCode}_issued_date</code></td><td>쿠폰별 발급일 (yyyy-MM-dd 형식)</td><td><code>2026-09-01</code></td></tr><tr><td><code>cp_{couponCode}_expire_date</code></td><td>쿠폰별 만료일 (yyyy-MM-dd 형식)<br>기한이 없는 쿠폰은 수집하지 않아요.</td><td><code>2026-09-30</code></td></tr><tr><td><code>cp_{couponCode}_used_date</code></td><td>쿠폰별 사용일 (yyyy-MM-dd 형식)<br>사용하지 않은 쿠폰은 수집하지 않아요.</td><td><code>2026-09-07</code></td></tr><tr><td><code>cp_{couponCode}_use_flag</code></td><td>쿠폰별 사용 여부</td><td><code>false</code></td></tr></tbody></table>

</details>

### 이벤트 <a href="#events" id="events"></a>

아임웹 연동 시 쇼핑몰에서 일어나는 사용자 행동을 핵클이 자동으로 수집하는 이벤트예요. 아래 대분류별로 정리했어요.

{% hint style="info" %}
각 이벤트에 표기된 정보의 의미예요.

* **수집 시점** — `실시간`은 사용자 행동 발생 즉시, `주기적 발행(배치)`은 핵클 서버가 주기적으로 수집하여 발행해요.
* **인앱메시지** — `가능`으로 표기된 이벤트는 인앱메시지의 시작 이벤트로 사용할 수 있어요.
* **비회원 발송** — `지원`으로 표기된 이벤트는 이벤트 기반 캠페인(카카오/문자, 사용자 여정)에서 쇼핑몰 비회원에게도 카톡/문자를 발송할 수 있어요. 해당 기능 사용을 위해서는 핵클 팀에 문의해 주세요.

각 이벤트의 **이벤트 속성**은 `이벤트 속성 보기`를 펼쳐 확인할 수 있어요.
{% endhint %}

{% hint style="info" %}
**모든 이벤트에 함께 수집되는 속성**

* 브라우저에서 수집하는 이벤트에는 `is_login`(로그인 여부), `is_mobile`(모바일 여부), `triggeredBy`(`SDK` 고정)가 함께 수집돼요.
* 아임웹 서버에서 수집하는 이벤트에는 `unit_code`(유닛 코드), `member_id`(회원 ID)가 함께 수집돼요.
* 값이 비어 있는 속성(`null`, 빈 문자열, 빈 배열)은 수집하지 않아요.
  {% endhint %}

{% hint style="warning" %}
아임웹 쇼핑몰의 구조적인 제약으로 인앱메시지 시작 이벤트로 사용할 수 없는 이벤트가 있어요.

* 브라우저가 아닌 아임웹 서버에서 발생하는 이벤트
* 이벤트가 발생한 직후 아임웹이 새로운 페이지로 이동시키는 이벤트

자세한 내용은 아임웹 FAQ를 참고해주세요.
{% endhint %}

### 기본 이벤트 <a href="#basic-events" id="basic-events"></a>

핵클 SDK가 기본으로 수집하는 이벤트예요. 특정 페이지나 세션 단위 행동을 파악할 때 사용해요.

#### $page\_view

모든 페이지 진입 시 수집돼요.

**수집 시점** 실시간 · **인앱메시지** 가능 · **비회원 발송** 미지원

<details>

<summary>이벤트 속성 보기</summary>

| 속성명          | 설명     | 타입/형식  | 예시 |
| ------------ | ------ | ------ | -- |
| `$page_name` | 페이지 이름 | String | -  |

</details>

#### $engagement

브라우저의 활성 상태가 변경될 때 수집돼요.

**수집 시점** 실시간 · **인앱메시지** 가능 · **비회원 발송** 미지원

<details>

<summary>이벤트 속성 보기</summary>

| 속성명                   | 설명              | 타입/형식  | 예시 |
| --------------------- | --------------- | ------ | -- |
| `$page_name`          | 페이지 이름          | String | -  |
| `$engagement_time_ms` | 페이지 활성 시간 (밀리초) | Number | -  |

</details>

#### $session\_start

세션이 시작될 때 수집돼요.

**수집 시점** 실시간 · **인앱메시지** 가능 · **비회원 발송** 미지원

#### $session\_end

세션이 종료될 때 수집돼요.

**수집 시점** 실시간 · **인앱메시지** 가능 · **비회원 발송** 미지원

{% hint style="info" %}
핵클 SDK가 자동으로 수집하는 기본 속성들은 핵클 속성을 참고해주세요.
{% endhint %}

### 화면 이벤트 <a href="#screen-events" id="screen-events"></a>

쇼핑몰의 주요 페이지에 진입하거나 페이지를 스크롤할 때 수집되는 이벤트예요.

{% hint style="info" %}
`page_name`은 현재 페이지를 구분하는 값이에요. `home` / `product` / `cart` / `checkout` / `completed_order` / `mypage` / `login` / `search` 중 하나이며, 페이지를 판별하지 못하면 이벤트를 수집하지 않아요.

`pre_page_name`은 직전에 본 페이지의 `page_name`이며, 첫 방문이면 수집되지 않아요.
{% endhint %}

#### view\_home

쇼핑몰 홈 진입 시 수집돼요.

**수집 시점** 실시간 · **인앱메시지** 가능 · **비회원 발송** 미지원

<details>

<summary>이벤트 속성 보기</summary>

| 속성명             | 설명           | 타입/형식  | 예시        |
| --------------- | ------------ | ------ | --------- |
| `page_name`     | 현재 페이지 이름    | String | `home`    |
| `pre_page_name` | 직전에 본 페이지 이름 | String | `product` |

</details>

#### view\_product

상품 상세 페이지 진입 시 수집돼요.

**수집 시점** 실시간 · **인앱메시지** 가능 · **비회원 발송** 미지원

<details>

<summary>이벤트 속성 보기</summary>

| 속성명             | 설명           | 타입/형식  | 예시        |
| --------------- | ------------ | ------ | --------- |
| `page_name`     | 현재 페이지 이름    | String | `product` |
| `pre_page_name` | 직전에 본 페이지 이름 | String | `home`    |
| `product_id`    | 상품번호         | Number | `12`      |

</details>

#### view\_cart

장바구니 페이지 진입 시 수집돼요.

**수집 시점** 실시간 · **인앱메시지** 가능 · **비회원 발송** 미지원

<details>

<summary>이벤트 속성 보기</summary>

| 속성명             | 설명                                                           | 타입/형식     | 예시         |
| --------------- | ------------------------------------------------------------ | --------- | ---------- |
| `page_name`     | 현재 페이지 이름                                                    | String    | `cart`     |
| `pre_page_name` | 직전에 본 페이지 이름                                                 | String    | `product`  |
| `product_ids`   | <p>장바구니에 담긴 상품번호 목록<br>장바구니 정보를 3초 안에 불러오지 못하면 수집되지 않아요.</p> | Number\[] | `[12, 34]` |

</details>

#### view\_checkout

주문서 페이지 진입 시 수집돼요.

**수집 시점** 실시간 · **인앱메시지** 가능 · **비회원 발송** 미지원

<details>

<summary>이벤트 속성 보기</summary>

| 속성명             | 설명           | 타입/형식  | 예시                  |
| --------------- | ------------ | ------ | ------------------- |
| `page_name`     | 현재 페이지 이름    | String | `checkout`          |
| `pre_page_name` | 직전에 본 페이지 이름 | String | `cart`              |
| `order_id`      | 주문번호         | String | `"202609299969458"` |

</details>

#### view\_completed\_order

결제 완료 페이지 진입 시 수집돼요.

**수집 시점** 실시간 · **인앱메시지** 가능 · **비회원 발송** 미지원

<details>

<summary>이벤트 속성 보기</summary>

| 속성명                    | 설명                         | 타입/형식                 | 예시                           |
| ---------------------- | -------------------------- | --------------------- | ---------------------------- |
| `page_name`            | 현재 페이지 이름                  | String                | `completed_order`            |
| `pre_page_name`        | 직전에 본 페이지 이름               | String                | `checkout`                   |
| `order_id`             | 주문번호                       | String                | `"202609299969458"`          |
| `price`                | 상품 금액                      | Number                | `15000`                      |
| `discounted_amount`    | 실 결제 금액                    | Number                | `13000`                      |
| `delivery_fee_amount`  | 배송비 (기본·추가·도서산간 배송비의 합)    | Number                | `3500`                       |
| `is_coupon_used_order` | 쿠폰 사용 주문 여부                | Boolean               | `false`                      |
| `total_quantity`       | 주문한 상품의 총 수량               | Number                | `3`                          |
| `items_count`          | 주문 상품 라인 수                 | Number                | `2`                          |
| `product_ids`          | 주문한 상품번호 목록                | Number\[]             | `[1, 2]`                     |
| `product_names`        | 주문한 상품명 목록                 | String\[]             | `["The Kick", "The matcha"]` |
| `currency`             | 통화                         | String                | `KRW`                        |
| `payment_method`       | 결제수단 코드 (아임웹에서 제공하는 값 그대로) | String                | `OPM01`                      |
| `is_first_order`       | 첫 주문 여부                    | Boolean               | `false`                      |
| `order_datetime`       | 주문 시각                      | `yyyy-MM-dd HH:mm:ss` | `2026-09-29 18:26:39`        |
| `order_date`           | 주문 일자                      | `yyyyMMdd`            | `20260929`                   |

</details>

#### view\_mypage

마이페이지 진입 시 수집돼요.

**수집 시점** 실시간 · **인앱메시지** 가능 · **비회원 발송** 미지원

<details>

<summary>이벤트 속성 보기</summary>

| 속성명             | 설명           | 타입/형식  | 예시       |
| --------------- | ------------ | ------ | -------- |
| `page_name`     | 현재 페이지 이름    | String | `mypage` |
| `pre_page_name` | 직전에 본 페이지 이름 | String | `home`   |

</details>

#### view\_login

로그인 페이지 진입 시 수집돼요.

**수집 시점** 실시간 · **인앱메시지** 가능 · **비회원 발송** 미지원

<details>

<summary>이벤트 속성 보기</summary>

| 속성명             | 설명           | 타입/형식  | 예시      |
| --------------- | ------------ | ------ | ------- |
| `page_name`     | 현재 페이지 이름    | String | `login` |
| `pre_page_name` | 직전에 본 페이지 이름 | String | `home`  |

</details>

#### view\_search

검색 결과 페이지 진입 시 수집돼요.

**수집 시점** 실시간 · **인앱메시지** 가능 · **비회원 발송** 미지원

<details>

<summary>이벤트 속성 보기</summary>

| 속성명             | 설명           | 타입/형식  | 예시       |
| --------------- | ------------ | ------ | -------- |
| `page_name`     | 현재 페이지 이름    | String | `search` |
| `pre_page_name` | 직전에 본 페이지 이름 | String | `home`   |

</details>

#### scroll\_home

홈에서 스크롤 깊이가 5% 단위에 도달할 때마다 수집돼요. 각 단계는 한 번씩만 수집돼요.

**수집 시점** 실시간 · **인앱메시지** 가능 · **비회원 발송** 미지원

<details>

<summary>이벤트 속성 보기</summary>

| 속성명     | 설명                    | 타입/형식  | 예시     |
| ------- | --------------------- | ------ | ------ |
| `depth` | 스크롤 깊이 (%) · 5 \~ 100 | String | `"20"` |

</details>

#### scroll\_product

상품 상세에서 스크롤 깊이가 5% 단위에 도달할 때마다 수집돼요. 각 단계는 한 번씩만 수집돼요.

**수집 시점** 실시간 · **인앱메시지** 가능 · **비회원 발송** 미지원

<details>

<summary>이벤트 속성 보기</summary>

| 속성명          | 설명                    | 타입/형식  | 예시     |
| ------------ | --------------------- | ------ | ------ |
| `product_id` | 상품번호                  | Number | `12`   |
| `depth`      | 스크롤 깊이 (%) · 5 \~ 100 | String | `"20"` |

</details>

### 회원 이벤트 <a href="#member-events" id="member-events"></a>

#### signup

회원가입이 완료될 때 수집돼요. 아임웹 서버에서 발생하는 이벤트예요.

**수집 시점** 실시간 · **인앱메시지** 미지원 · **비회원 발송** 미지원

<details>

<summary>이벤트 속성 보기</summary>

| 속성명         | 설명        | 타입/형식  | 예시                       |
| ----------- | --------- | ------ | ------------------------ |
| `unit_code` | 아임웹 유닛 코드 | String | `u2025012465b0fbe8ce0dy` |
| `member_id` | 회원 ID     | String | `test_member@imweb.me`   |

</details>

{% hint style="info" %}
회원가입이 완료되면 회원 정보를 함께 조회해 `join_*`, `name`, `email`, `gender`, `birth_*`, 전화번호, `sms`, `third_party_agree`, `grade_code`, `available_point` 사용자 속성을 설정해요.

회원 일괄 등록으로 생성된 회원은 이 이벤트가 수집되지 않아요.
{% endhint %}

#### signup\_web

회원가입 양식을 제출할 때 수집돼요. 가입 성공 여부와 관계없이 제출 시점에 수집돼요.

**수집 시점** 실시간 · **인앱메시지** 미지원 · **비회원 발송** 미지원

<details>

<summary>이벤트 속성 보기</summary>

| 속성명             | 설명                           | 타입/형식                 | 예시                    |
| --------------- | ---------------------------- | --------------------- | --------------------- |
| `join_method`   | 가입 방식 (`general` / `social`) | String                | `general`             |
| `join_date`     | 가입 일자                        | `yyyyMMdd`            | `20260930`            |
| `join_datetime` | 가입 시각                        | `yyyy-MM-dd HH:mm:ss` | `2026-09-30 18:26:39` |

</details>

#### login\_web

로그인한 직후 첫 페이지에서 수집돼요.

**수집 시점** 실시간 · **인앱메시지** 가능 · **비회원 발송** 미지원

<details>

<summary>이벤트 속성 보기</summary>

| 속성명              | 설명     | 타입/형식                 | 예시                     |
| ---------------- | ------ | --------------------- | ---------------------- |
| `login_date`     | 로그인 일자 | `yyyyMMdd`            | `20260930`             |
| `login_datetime` | 로그인 시각 | `yyyy-MM-dd HH:mm:ss` | `2026-09-30 18:26:39`  |
| `member_id`      | 회원 ID  | String                | `test_member@imweb.me` |

</details>

### 장바구니 이벤트 <a href="#cart-events" id="cart-events"></a>

#### click\_add\_to\_cart

상품 상세에서 장바구니 담기를 클릭할 때 수집돼요.

**수집 시점** 실시간 · **인앱메시지** 가능 · **비회원 발송** 미지원

<details>

<summary>이벤트 속성 보기</summary>

| 속성명          | 설명                               | 타입/형식  | 예시                         |
| ------------ | -------------------------------- | ------ | -------------------------- |
| `product_id` | 상품번호                             | Number | `12`                       |
| `cart_type`  | 장바구니 타입 (`normal` / `regularly`) | String | `normal`                   |
| `source`     | 호출된 아임웹 함수 경로                    | String | `SITE_SHOP_DETAIL.addCart` |

</details>

#### add\_to\_cart

장바구니에 상품을 담았을 때 수집돼요. 아임웹 서버에서 발생하는 이벤트예요.

**수집 시점** 실시간 · **인앱메시지** 미지원 · **비회원 발송** 미지원

<details>

<summary>이벤트 속성 보기</summary>

| 속성명          | 설명        | 타입/형식  | 예시                       |
| ------------ | --------- | ------ | ------------------------ |
| `unit_code`  | 아임웹 유닛 코드 | String | `u2025012465b0fbe8ce0dy` |
| `product_id` | 상품번호      | Number | `1001`                   |
| `quantity`   | 담은 수량     | Number | `2`                      |

</details>

#### add\_to\_cart\_items

장바구니에 담은 상품을 상품 단위로 수집해요. 한 번에 상품 1개가 담기므로 `add_to_cart`와 1:1로 수집돼요. 아임웹 서버에서 발생하는 이벤트예요.

**수집 시점** 실시간 · **인앱메시지** 미지원 · **비회원 발송** 미지원

<details>

<summary>이벤트 속성 보기</summary>

| 속성명                 | 설명        | 타입/형식  | 예시                       |
| ------------------- | --------- | ------ | ------------------------ |
| `unit_code`         | 아임웹 유닛 코드 | String | `u2025012465b0fbe8ce0dy` |
| `product_id`        | 상품번호      | Number | `1001`                   |
| `option_id`         | 옵션 코드     | String | `O2024092566f3726054a3a` |
| `option_name`       | 옵션명       | String | `색상`                     |
| `option_value_id`   | 옵션값 코드    | String | `O202409254e3180103a548` |
| `option_value_name` | 옵션값명      | String | `100`                    |
| `quantity`          | 담은 수량     | Number | `2`                      |

</details>

### 주문 이벤트 <a href="#order-events" id="order-events"></a>

#### click\_buy\_product

상품 상세에서 바로 구매를 클릭할 때 수집돼요.

**수집 시점** 실시간 · **인앱메시지** 미지원 · **비회원 발송** 미지원

<details>

<summary>이벤트 속성 보기</summary>

| 속성명             | 설명                       | 타입/형식  | 예시        |
| --------------- | ------------------------ | ------ | --------- |
| `page_name`     | 현재 페이지 이름                | String | `product` |
| `product_id`    | 상품번호                     | Number | `12`      |
| `checkout_type` | 주문 방식 (아임웹에서 제공하는 값 그대로) | String | `normal`  |

</details>

#### click\_buy\_cart

장바구니에서 구매를 클릭할 때 수집돼요.

**수집 시점** 실시간 · **인앱메시지** 미지원 · **비회원 발송** 미지원

<details>

<summary>이벤트 속성 보기</summary>

| 속성명             | 설명                                        | 타입/형식  | 예시                       |
| --------------- | ----------------------------------------- | ------ | ------------------------ |
| `page_name`     | 현재 페이지 이름                                 | String | `cart`                   |
| `purchase_unit` | 구매 단위 (`single` 바로 구매 / `selected` 선택 구매) | String | `selected`               |
| `items_count`   | 구매하는 상품 종류 수                              | Number | `1`                      |
| `cart_code`     | 장바구니 코드                                   | String | `c20260921f8c9c5a4f9c65` |
| `checkout_type` | 주문 방식 (아임웹에서 제공하는 값 그대로)                  | String | `normal`                 |

</details>

#### complete\_order

주문이 생성될 때 수집돼요. 아임웹 서버에서 발생하는 이벤트예요.

**수집 시점** 실시간 · **인앱메시지** 미지원 · **비회원 발송** 미지원

<details>

<summary>이벤트 속성 보기</summary>

| 속성명                         | 설명                           | 타입/형식                 | 예시                       |
| --------------------------- | ---------------------------- | --------------------- | ------------------------ |
| `unit_code`                 | 아임웹 유닛 코드                    | String                | `u2025012465b0fbe8ce0dy` |
| `order_id`                  | 주문번호                         | String                | `"202503073069582"`      |
| `external_order_id`         | 판매 채널 주문번호                   | String                | `202503073069582`        |
| `sale_channel`              | 판매 채널                        | String                | `IMWEB`                  |
| `member_id`                 | 회원 ID                        | String                | `test_member@imweb.me`   |
| `is_member`                 | 회원 주문 여부 (항상 `true`)         | Boolean               | `true`                   |
| `order_device`              | 주문 디바이스                      | String                | `PC`                     |
| `is_first_order`            | 첫 주문 여부                      | Boolean               | `true`                   |
| `is_gift`                   | 선물 주문 여부                     | Boolean               | `false`                  |
| `buyer_name`                | 주문자명                         | String                | `홍길동`                    |
| `buyer_email`               | 주문자 이메일                      | String                | `test_member@imweb.me`   |
| `currency`                  | 통화                           | String                | `KRW`                    |
| `total_order_amount`        | 주문 금액                        | String                | `"1000000"`              |
| `total_payment_amount`      | 실 결제 금액                      | String                | `"1000000"`              |
| `total_discount_amount`     | 총 할인 금액                      | String                | `"0"`                    |
| `total_point_used_amount`   | 사용 적립금                       | String                | `"0"`                    |
| `total_delivery_fee_amount` | 배송비                          | String                | `"3000"`                 |
| `payment_method`            | 결제수단 (아임웹에서 제공하는 값 그대로)      | String                | `BANKTRANSFER`           |
| `payment_status`            | 결제 상태 (아임웹에서 제공하는 값 그대로)     | String                | `PAYMENT_COMPLETE`       |
| `deposit_expire_datetime`   | 입금 기한 시각 (무통장 입금일 때만 수집돼요.)  | `yyyy-MM-dd HH:mm:ss` | `2025-08-07 10:44:32`    |
| `deposit_expire_date`       | 입금 기한 일자                     | `yyyy-MM-dd`          | `2025-08-07`             |
| `product_ids`               | 주문한 상품번호 목록                  | Number\[]             | `[1001, 1002]`           |
| `product_summary`           | 첫 상품명과 나머지 건수                | String                | `상품명 외 1건`               |
| `product_names`             | 주문한 상품명 목록                   | String\[]             | `["상품명"]`                |
| `items_count`               | 주문 상품 라인 수                   | Number                | `2`                      |
| `order_datetime`            | 주문 시각                        | `yyyy-MM-dd HH:mm:ss` | `2025-03-07 10:00:00`    |
| `order_date`                | 주문 일자                        | `yyyy-MM-dd`          | `2025-03-07`             |
| `payment_datetime`          | 결제 완료 시각 (결제가 완료됐을 때만 수집돼요.) | `yyyy-MM-dd HH:mm:ss` | `2025-08-06 10:44:32`    |
| `payment_date`              | 결제 완료 일자                     | `yyyy-MM-dd`          | `2025-08-06`             |

</details>

{% hint style="info" %}
비회원 주문은 이 이벤트가 수집되지 않아요. 같은 주문에 대해 이벤트가 중복으로 수집되지도 않아요.
{% endhint %}

#### complete\_order\_items

주문이 생성될 때 주문 상품 라인마다 수집돼요. 아임웹 서버에서 발생하는 이벤트예요.

**수집 시점** 실시간 · **인앱메시지** 미지원 · **비회원 발송** 미지원

<details>

<summary>이벤트 속성 보기</summary>

`complete_order`의 이벤트 속성을 모두 포함하고, 아래 속성이 추가돼요.

| 속성명             | 설명       | 타입/형식  | 예시                    |
| --------------- | -------- | ------ | --------------------- |
| `product_id`    | 상품번호     | Number | `1001`                |
| `product_name`  | 상품명      | String | `상품명`                 |
| `order_item_id` | 주문 상품 번호 | String | `202503073069582-001` |
| `quantity`      | 수량       | Number | `1`                   |
| `option_name`   | 옵션명      | String | `사이즈, 색상`             |
| `option_value`  | 옵션값      | String | `S, 블랙`               |

</details>

#### ready\_shipping

주문이 배송대기 상태가 될 때 배송 섹션마다 수집돼요. 아임웹 서버에서 발생하는 이벤트예요.

**수집 시점** 실시간 · **인앱메시지** 미지원 · **비회원 발송** 미지원

<details>

<summary>이벤트 속성 보기</summary>

`complete_order`의 이벤트 속성을 모두 포함하고, 아래 속성은 배송 섹션 기준으로 다시 수집돼요.

| 속성명                 | 설명                     | 타입/형식     | 예시                       |
| ------------------- | ---------------------- | --------- | ------------------------ |
| `unit_code`         | 아임웹 유닛 코드              | String    | `u2025012465b0fbe8ce0dy` |
| `order_id`          | 주문번호                   | String    | `"202503073069582"`      |
| `external_order_id` | 판매 채널 주문번호             | String    | `202503073069582`        |
| `sale_channel`      | 판매 채널                  | String    | `IMWEB`                  |
| `member_id`         | 회원 ID                  | String    | `test_member@imweb.me`   |
| `is_member`         | 회원 주문 여부 (항상 `true`)   | Boolean   | `true`                   |
| `product_ids`       | 이 배송 섹션의 상품번호 목록       | Number\[] | `[1001]`                 |
| `product_summary`   | 이 배송 섹션의 첫 상품명과 나머지 건수 | String    | `상품명`                    |
| `product_names`     | 이 배송 섹션의 상품명 목록        | String\[] | `["상품명"]`                |
| `items_count`       | 이 배송 섹션의 상품 라인 수       | Number    | `1`                      |

</details>

{% hint style="info" %}
교환 배송은 이 이벤트가 수집되지 않아요.
{% endhint %}

#### ready\_shipping\_items

주문이 배송대기 상태가 될 때 상품 라인마다 수집돼요. 아임웹 서버에서 발생하는 이벤트예요.

**수집 시점** 실시간 · **인앱메시지** 미지원 · **비회원 발송** 미지원

<details>

<summary>이벤트 속성 보기</summary>

`ready_shipping`의 이벤트 속성을 모두 포함하고, 아래 속성이 추가돼요.

| 속성명             | 설명       | 타입/형식  | 예시                    |
| --------------- | -------- | ------ | --------------------- |
| `product_id`    | 상품번호     | Number | `1001`                |
| `product_name`  | 상품명      | String | `상품명`                 |
| `order_item_id` | 주문 상품 번호 | String | `202503073069582-001` |
| `quantity`      | 수량       | Number | `1`                   |
| `option_name`   | 옵션명      | String | `사이즈, 색상`             |
| `option_value`  | 옵션값      | String | `S, 블랙`               |

</details>

#### start\_shipping

배송이 시작될 때 배송 섹션마다 수집돼요. 아임웹 서버에서 발생하는 이벤트예요.

**수집 시점** 실시간 · **인앱메시지** 미지원 · **비회원 발송** 미지원

<details>

<summary>이벤트 속성 보기</summary>

`complete_order`의 이벤트 속성을 모두 포함하고, 아래 속성은 배송 섹션 기준으로 다시 수집돼요.

| 속성명                    | 설명                      | 타입/형식     | 예시                       |
| ---------------------- | ----------------------- | --------- | ------------------------ |
| `unit_code`            | 아임웹 유닛 코드               | String    | `u2025012465b0fbe8ce0dy` |
| `order_id`             | 주문번호                    | String    | `"202503073069582"`      |
| `external_order_id`    | 판매 채널 주문번호              | String    | `202503073069582`        |
| `sale_channel`         | 판매 채널                   | String    | `IMWEB`                  |
| `member_id`            | 회원 ID                   | String    | `test_member@imweb.me`   |
| `is_member`            | 회원 주문 여부 (항상 `true`)    | Boolean   | `true`                   |
| `product_ids`          | 이 배송 섹션의 상품번호 목록        | Number\[] | `[1001]`                 |
| `product_summary`      | 이 배송 섹션의 첫 상품명과 나머지 건수  | String    | `상품명`                    |
| `product_names`        | 이 배송 섹션의 상품명 목록         | String\[] | `["상품명"]`                |
| `items_count`          | 이 배송 섹션의 상품 라인 수        | Number    | `1`                      |
| `tracking_number`      | 송장번호 (등록되어 있을 때만 수집돼요.) | String    | `123456789012`           |
| `shipping_company_idx` | 아임웹 택배사 번호              | Number    | `1`                      |

</details>

{% hint style="info" %}
교환 배송은 이 이벤트가 수집되지 않아요.
{% endhint %}

#### start\_shipping\_items

배송이 시작될 때 상품 라인마다 수집돼요. 아임웹 서버에서 발생하는 이벤트예요.

**수집 시점** 실시간 · **인앱메시지** 미지원 · **비회원 발송** 미지원

<details>

<summary>이벤트 속성 보기</summary>

`start_shipping`의 이벤트 속성을 모두 포함하고, 아래 속성이 추가돼요.

| 속성명             | 설명       | 타입/형식  | 예시                    |
| --------------- | -------- | ------ | --------------------- |
| `product_id`    | 상품번호     | Number | `1001`                |
| `product_name`  | 상품명      | String | `상품명`                 |
| `order_item_id` | 주문 상품 번호 | String | `202503073069582-001` |
| `quantity`      | 수량       | Number | `1`                   |
| `option_name`   | 옵션명      | String | `사이즈, 색상`             |
| `option_value`  | 옵션값      | String | `S, 블랙`               |

</details>

#### complete\_shipping

배송이 완료될 때 배송 섹션마다 수집돼요. 아임웹 서버에서 발생하는 이벤트예요.

**수집 시점** 실시간 · **인앱메시지** 미지원 · **비회원 발송** 미지원

<details>

<summary>이벤트 속성 보기</summary>

`complete_order`의 이벤트 속성을 모두 포함하고, 아래 속성은 배송 섹션 기준으로 다시 수집돼요.

| 속성명                    | 설명                      | 타입/형식     | 예시                       |
| ---------------------- | ----------------------- | --------- | ------------------------ |
| `unit_code`            | 아임웹 유닛 코드               | String    | `u2025012465b0fbe8ce0dy` |
| `order_id`             | 주문번호                    | String    | `"202503073069582"`      |
| `external_order_id`    | 판매 채널 주문번호              | String    | `202503073069582`        |
| `sale_channel`         | 판매 채널                   | String    | `IMWEB`                  |
| `member_id`            | 회원 ID                   | String    | `test_member@imweb.me`   |
| `is_member`            | 회원 주문 여부 (항상 `true`)    | Boolean   | `true`                   |
| `product_ids`          | 이 배송 섹션의 상품번호 목록        | Number\[] | `[1001]`                 |
| `product_summary`      | 이 배송 섹션의 첫 상품명과 나머지 건수  | String    | `상품명`                    |
| `product_names`        | 이 배송 섹션의 상품명 목록         | String\[] | `["상품명"]`                |
| `items_count`          | 이 배송 섹션의 상품 라인 수        | Number    | `1`                      |
| `tracking_number`      | 송장번호 (등록되어 있을 때만 수집돼요.) | String    | `123456789012`           |
| `shipping_company_idx` | 아임웹 택배사 번호              | Number    | `1`                      |

</details>

{% hint style="info" %}
교환 배송은 이 이벤트가 수집되지 않아요.
{% endhint %}

#### complete\_shipping\_items

배송이 완료될 때 상품 라인마다 수집돼요. 아임웹 서버에서 발생하는 이벤트예요.

**수집 시점** 실시간 · **인앱메시지** 미지원 · **비회원 발송** 미지원

<details>

<summary>이벤트 속성 보기</summary>

`complete_shipping`의 이벤트 속성을 모두 포함하고, 아래 속성이 추가돼요.

| 속성명             | 설명       | 타입/형식  | 예시                    |
| --------------- | -------- | ------ | --------------------- |
| `product_id`    | 상품번호     | Number | `1001`                |
| `product_name`  | 상품명      | String | `상품명`                 |
| `order_item_id` | 주문 상품 번호 | String | `202503073069582-001` |
| `quantity`      | 수량       | Number | `1`                   |
| `option_name`   | 옵션명      | String | `사이즈, 색상`             |
| `option_value`  | 옵션값      | String | `S, 블랙`               |

</details>

#### click\_cancel\_order

주문 취소를 신청할 때 수집돼요.

**수집 시점** 실시간 · **인앱메시지** 미지원 · **비회원 발송** 미지원

<details>

<summary>이벤트 속성 보기</summary>

| 속성명             | 설명    | 타입/형식  | 예시                  |
| --------------- | ----- | ------ | ------------------- |
| `order_id`      | 주문번호  | String | `"202609299969458"` |
| `cancel_reason` | 취소 사유 | String | `INTENT_CHANGED`    |
| `order_type`    | 주문 타입 | String | -                   |

</details>

#### cancel\_order

주문 취소가 완료될 때 취소 섹션마다 수집돼요. 아임웹 서버에서 발생하는 이벤트예요.

**수집 시점** 실시간 · **인앱메시지** 미지원 · **비회원 발송** 미지원

<details>

<summary>이벤트 속성 보기</summary>

`complete_order`의 이벤트 속성을 모두 포함하고, 아래 속성이 추가돼요. 취소 금액은 아임웹에서 제공하지 않아 수집하지 않아요.

| 속성명                      | 설명                   | 타입/형식                 | 예시                       |
| ------------------------ | -------------------- | --------------------- | ------------------------ |
| `unit_code`              | 아임웹 유닛 코드            | String                | `u2025012465b0fbe8ce0dy` |
| `order_id`               | 주문번호                 | String                | `"202503073069582"`      |
| `external_order_id`      | 판매 채널 주문번호           | String                | `202503073069582`        |
| `sale_channel`           | 판매 채널                | String                | `IMWEB`                  |
| `member_id`              | 회원 ID                | String                | `test_member@imweb.me`   |
| `is_member`              | 회원 주문 여부 (항상 `true`) | Boolean               | `true`                   |
| `cancel_product_ids`     | 취소한 상품번호 목록          | Number\[]             | `[1001]`                 |
| `cancel_product_summary` | 취소한 첫 상품명과 나머지 건수    | String                | `상품명`                    |
| `cancel_product_names`   | 취소한 상품명 목록           | String\[]             | `["상품명"]`                |
| `cancel_items_count`     | 취소한 상품 라인 수          | Number                | `1`                      |
| `cancel_datetime`        | 취소 완료 시각             | `yyyy-MM-dd HH:mm:ss` | `2026-09-01 10:00:00`    |
| `cancel_date`            | 취소 완료 일자             | `yyyy-MM-dd`          | `2026-09-01`             |
| `cancel_reason`          | 취소 사유                | String                | `취소 사유`                  |
| `cancel_reason_detail`   | 취소 사유 상세             | String                | `취소 사유 상세`               |

</details>

#### cancel\_order\_items

주문 취소가 완료될 때 상품 라인마다 수집돼요. 아임웹 서버에서 발생하는 이벤트예요.

**수집 시점** 실시간 · **인앱메시지** 미지원 · **비회원 발송** 미지원

<details>

<summary>이벤트 속성 보기</summary>

`cancel_order`의 이벤트 속성을 모두 포함하고, 아래 속성이 추가돼요.

| 속성명               | 설명       | 타입/형식  | 예시                    |
| ----------------- | -------- | ------ | --------------------- |
| `product_id`      | 상품번호     | Number | `1001`                |
| `product_name`    | 상품명      | String | `상품명`                 |
| `order_item_id`   | 주문 상품 번호 | String | `202503073069582-001` |
| `quantity`        | 수량       | Number | `1`                   |
| `option_name`     | 옵션명      | String | `사이즈, 색상`             |
| `option_value`    | 옵션값      | String | `S, 블랙`               |
| `cancel_quantity` | 취소 수량    | Number | `1`                   |

</details>

#### click\_return\_order

반품을 신청할 때 수집돼요.

**수집 시점** 실시간 · **인앱메시지** 미지원 · **비회원 발송** 미지원

<details>

<summary>이벤트 속성 보기</summary>

| 속성명             | 설명    | 타입/형식  | 예시                  |
| --------------- | ----- | ------ | ------------------- |
| `order_id`      | 주문번호  | String | `"202609299969458"` |
| `return_reason` | 반품 사유 | String | `PRODUCT_UNSATIS`   |

</details>

#### return\_order

주문 반품이 완료될 때 반품 섹션마다 수집돼요. 아임웹 서버에서 발생하는 이벤트예요.

**수집 시점** 실시간 · **인앱메시지** 미지원 · **비회원 발송** 미지원

<details>

<summary>이벤트 속성 보기</summary>

`complete_order`의 이벤트 속성을 모두 포함하고, 아래 속성이 추가돼요. 반품 금액은 아임웹에서 제공하지 않아 수집하지 않아요.

| 속성명                      | 설명                   | 타입/형식                 | 예시                       |
| ------------------------ | -------------------- | --------------------- | ------------------------ |
| `unit_code`              | 아임웹 유닛 코드            | String                | `u2025012465b0fbe8ce0dy` |
| `order_id`               | 주문번호                 | String                | `"202503073069582"`      |
| `external_order_id`      | 판매 채널 주문번호           | String                | `202503073069582`        |
| `sale_channel`           | 판매 채널                | String                | `IMWEB`                  |
| `member_id`              | 회원 ID                | String                | `test_member@imweb.me`   |
| `is_member`              | 회원 주문 여부 (항상 `true`) | Boolean               | `true`                   |
| `return_product_ids`     | 반품한 상품번호 목록          | Number\[]             | `[1001]`                 |
| `return_product_summary` | 반품한 첫 상품명과 나머지 건수    | String                | `상품명`                    |
| `return_product_names`   | 반품한 상품명 목록           | String\[]             | `["상품명"]`                |
| `return_items_count`     | 반품한 상품 라인 수          | Number                | `1`                      |
| `return_datetime`        | 반품 완료 시각             | `yyyy-MM-dd HH:mm:ss` | `2026-09-01 10:00:00`    |
| `return_date`            | 반품 완료 일자             | `yyyy-MM-dd`          | `2026-09-01`             |
| `return_reason`          | 반품 사유                | String                | `반품 사유`                  |
| `return_reason_detail`   | 반품 사유 상세             | String                | `반품 사유 상세`               |

</details>

#### return\_order\_items

주문 반품이 완료될 때 상품 라인마다 수집돼요. 아임웹 서버에서 발생하는 이벤트예요.

**수집 시점** 실시간 · **인앱메시지** 미지원 · **비회원 발송** 미지원

<details>

<summary>이벤트 속성 보기</summary>

`return_order`의 이벤트 속성을 모두 포함하고, 아래 속성이 추가돼요.

| 속성명               | 설명       | 타입/형식  | 예시                    |
| ----------------- | -------- | ------ | --------------------- |
| `product_id`      | 상품번호     | Number | `1001`                |
| `product_name`    | 상품명      | String | `상품명`                 |
| `order_item_id`   | 주문 상품 번호 | String | `202503073069582-001` |
| `quantity`        | 수량       | Number | `1`                   |
| `return_quantity` | 반품 수량    | Number | `1`                   |

</details>

#### click\_exchange\_order

교환을 신청할 때 수집돼요.

**수집 시점** 실시간 · **인앱메시지** 미지원 · **비회원 발송** 미지원

<details>

<summary>이벤트 속성 보기</summary>

| 속성명               | 설명    | 타입/형식  | 예시                  |
| ----------------- | ----- | ------ | ------------------- |
| `order_id`        | 주문번호  | String | `"202609299969458"` |
| `exchange_reason` | 교환 사유 | String | `PRODUCT_UNSATIS`   |

</details>

{% hint style="warning" %}
교환은 신청 시점의 `click_exchange_order` 만 수집돼요. 교환 승인·교환 배송은 아임웹에서 제공하지 않아 수집하지 않아요.
{% endhint %}

### 기타 이벤트 <a href="#other-events" id="other-events"></a>

#### click\_wishlist

찜하기를 추가하거나 해제할 때 수집돼요. 장바구니 페이지에서는 수집되지 않아요.

**수집 시점** 실시간 · **인앱메시지** 가능 · **비회원 발송** 미지원

<details>

<summary>이벤트 속성 보기</summary>

| 속성명               | 설명                        | 타입/형식  | 예시                       |
| ----------------- | ------------------------- | ------ | ------------------------ |
| `page_name`       | 현재 페이지 이름                 | String | `product`                |
| `product_code`    | 상품 코드                     | String | `S201801295a6e17e03a333` |
| `product_id`      | 상품번호 (상품 상세에서만 수집돼요.)     | Number | `12`                     |
| `wishlist_action` | 찜하기 동작 (`add` / `delete`) | String | `add`                    |

</details>

#### click\_download\_coupon

쿠폰을 다운로드할 때 수집돼요.

**수집 시점** 실시간 · **인앱메시지** 가능 · **비회원 발송** 미지원

<details>

<summary>이벤트 속성 보기</summary>

| 속성명            | 설명                                                                                                                                                            | 타입/형식     | 예시                           |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | ---------------------------- |
| `page_name`    | 현재 페이지 이름                                                                                                                                                     | String    | `product`                    |
| `source`       | <p>다운로드가 일어난 위치<br><code>detailPageDownCoupon</code> 상품 상세<br><code>downloadEntireCoupon</code> 전체 받기<br><code>mypage\_down\_use\_coupon</code> 쿠폰함 개별 받기</p> | String    | `detailPageDownCoupon`       |
| `coupon_codes` | 다운로드한 쿠폰 코드 목록                                                                                                                                                | String\[] | `["c20250124f19b3a713d31a"]` |

</details>

### 커스텀 이벤트 <a href="#custom-events" id="custom-events"></a>

플러그인이 자동으로 수집해주는 이벤트 외에 커스텀 이벤트를 생성할 수 있어요.

#### GTM 연동

아임웹에서 커스텀 이벤트를 생성할 때는 GTM(Google Tag Manager)을 활용하는 것을 권장드려요.

기존에 사용하고 있던 `트리거` 나 `태그`가 있다면 이를 활용해 핵클로 이벤트를 전송할 수 있어요.

자세한 내용은 GTM 연동을 참고해주세요.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.hackle.io/imweb/events.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
