> For the complete documentation index, see [llms.txt](https://toss-ads.gitbook.io/guide/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://toss-ads.gitbook.io/guide/tracking/tosspixel/24.md).

# 카페24 픽셀 연동

카페24 쇼핑몰에 토스 픽셀을 설치하는 방법을 안내해요.

카페24 쇼핑몰에는 주요 전환 이벤트와 상품·주문 정보를 자동으로 수집하는 **카페24용 토스 픽셀 로더 설치를 권장해요.** 이벤트별 코드를 직접 작성해야 하는 경우에만 이 페이지 하단의 [수동 설치](#undefined-3)를 이용해 주세요.

직접 구축한 자사몰은 [자사몰 픽셀 연동](/guide/tracking/tosspixel/preservationguide-1.md), 메이크샵은 [메이크샵 픽셀 연동](/guide/tracking/tosspixel/makeshop.md)을 참고해 주세요.

## 권장 설치: 카페24용 토스 픽셀 로더

토스 픽셀 로더를 공통 레이아웃에 한 번 설치하면 페이지와 이벤트마다 코드를 직접 작성하지 않아도 카페24의 주요 전환 이벤트를 자동으로 수집할 수 있어요.

{% hint style="info" %}

## 전환 추적 코드 발급하기

* **토스 픽셀**은 [전환 추적 코드 생성하기 가이드](https://toss-ads.gitbook.io/guide/tracking/tag/code_generation)에 따라 **전환 추적 코드를 생성한 후에 사용**할 수 있어요. 발급받은 전환 추적 코드는 반드시 따옴표(`' '` 또는 `" "`)로 감싸서 스크립트에 입력해 주세요. 
* 예시의 `'전환 코드'` 부분을 발급받은 실제 값으로 바꾸고, 따옴표는 그대로 유지해 주세요.
  {% endhint %}

### 자동으로 수집하는 이벤트

| 이벤트명     | 호출 메서드                                                                          | 수집 시점                                 |
| -------- | ------------------------------------------------------------------------------- | ------------------------------------- |
| 페이지 방문   | `pageView`                                                                      | 토스 픽셀 로더가 설치된 페이지를 조회할 때              |
| 상품 상세 조회 | `productView`                                                                   | 카페24 상품 상세 페이지에서 상품 정보를 확인할 수 있을 때    |
| 장바구니 담기  | `addToCart`                                                                     | 카페24에서 장바구니 담기가 완료됐을 때                |
| 회원가입     | `signUp`                                                                        | 회원가입 완료 페이지에서 회원 정보를 확인할 수 있을 때       |
| 구매       | `purchase`                                                                      | 주문 완료 페이지에서 주문번호와 주문 정보를 확인할 수 있을 때   |
| 간편결제 구매  | <p><code>purchase</code><br><code>purchase\_type: naverpay, kakaopay</code></p> | 상품 상세 또는 장바구니에서 네이버페이·카카오페이 버튼을 클릭할 때 |

토스 픽셀 로더는 카페24가 제공하는 페이지·상품·주문 정보를 이용해 이벤트와 파라미터를 자동으로 구성해요.

### 1. 카페24 어드민에서 설치하기

{% stepper %}
{% step %}
**카페24 관리자센터에서 디자인 메뉴 선택하기**

카페24 관리자센터에 접속하여 왼쪽 메뉴에서 **디자인(PC/모바일)**&#xC744; 선택해 주세요.

<figure><img src="https://1103230780-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6C6VnjnrKC0ixISOKw0d%2Fuploads%2F4upf2f9YTS6oboEM1wKs%2Fimage.png?alt=media&amp;token=bf0249b4-b214-4ce4-89c1-101a8cff2c6c" alt="카페24 관리자센터의 디자인(PC/모바일) 메뉴" width="253"><figcaption></figcaption></figure>
{% endstep %}

{% step %}
**HTML 수정 열기**

토스 픽셀을 설치할 쇼핑몰의 **디자인 편집**을 누른 뒤 **HTML 수정**을 선택해 주세요.

<figure><img src="https://1103230780-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6C6VnjnrKC0ixISOKw0d%2Fuploads%2FRRNG1qLJHVovScmzwf2f%2Fimage.png?alt=media&amp;token=083f2e50-c806-4208-936a-b8032c93927c" alt="카페24 디자인 편집 화면의 HTML 수정 버튼" width="256"><figcaption></figcaption></figure>

{% hint style="info" %}
PC 디자인과 모바일 디자인을 모두 운영한다면 두 디자인에 각각 설치해야 해요. 사용하는 스크립트는 같아요.
{% endhint %}
{% endstep %}
{% endstepper %}

### 2. 토스 픽셀 로더 설치하기

공통 레이아웃 파일인 `layout.html`을 열고 `<head>` 태그 안에 아래 스크립트를 추가해 주세요.

{% code overflow="wrap" %}

```html
<!-- Toss Pixel Loader -->
<script defer src="https://static.toss.im/lex/pixel-loader.js?conversion_id=1234567890"></script>
```

{% endcode %}

URL의 `1234567890`을 토스애즈에서 발급한 실제 전환 추적 코드로 바꿔 주세요.

예를 들어 전환 추적 코드가 `1234567890`이라면 다음과 같이 입력해요.

{% code overflow="wrap" %}

```html
<script defer src="https://static.toss.im/lex/pixel-loader.js?conversion_id=1234567890"></script>
```

{% endcode %}

입력을 마치면 디자인 편집기 상단의 **저장**을 눌러 주세요.

### 3. 공통 레이아웃을 사용하지 않는 페이지 확인하기

쇼핑몰의 모든 페이지가 공통 `layout.html`을 사용하지 않을 수도 있어요.

개별 페이지가 다른 레이아웃을 사용하거나 공통 레이아웃을 사용하지 않는다면 해당 레이아웃 또는 페이지의 `<head>` 태그 안에도 같은 토스 픽셀 로더 스크립트를 추가해 주세요.

해당 페이지가 공통 레이아웃을 이미 사용한다면 스크립트를 다시 추가하지 않아도 돼요. 토스 픽셀 로더는 페이지당 한 번만 설치해 주세요.

### 기존 수동 설치에서 토스 픽셀 로더로 변경하기

기존 가이드에 따라 `v1.js`와 이벤트별 `TossPixel(...)` 코드를 직접 설치했다면 토스 픽셀 로더를 추가하기 전에 기존 토스 픽셀 스크립트를 모두 삭제해 주세요.

1. 공통 레이아웃과 개별 페이지에 설치된 기존 SDK 로드 코드를 확인해 주세요.
2. 기존 공통 스크립트와 `pageView()`, `purchase()`, `addToCart()`, `productView()`, `signUp()` 등 표준 이벤트 스크립트를 모두 제거해 주세요.
3. 토스 픽셀 로더 스크립트를 설치해 주세요.
4. [픽셀 이벤트 테스트 가이드](/guide/tracking/tosspixel/pixel_event_test.md)에 따라 주요 이벤트를 다시 테스트해 주세요.

{% hint style="danger" %}
토스 픽셀 로더와 기존 수동 표준 이벤트 코드를 함께 설치하면 전환 수치가 중복되거나 정확하게 집계되지 않을 수 있어요. 반드시 기존 공통 스크립트와 이벤트 스크립트를 모두 삭제한 뒤 토스 픽셀 로더를 설치해 주세요.
{% endhint %}

직접 만든 커스텀 이벤트가 있다면 아래의 수동 설치 방식으로 커스텀 이벤트를 설치해 주세요.

## 수동 설치

토스 픽셀 로더가 지원하지 않는 이벤트를 수집하거나 이벤트와 파라미터를 직접 구성해야 할 때 사용하는 설치 방식이에요. 일반적인 카페24 쇼핑몰은 위의 [카페24용 토스 픽셀 로더](#id-24)를 이용해 주세요.

{% hint style="warning" %}
아래 수동 이벤트 코드는 토스 픽셀 로더가 설치된 상태에서 실행해 주세요. 토스 픽셀 로더가 `TossPixel`을 제공하므로 별도의 SDK 로드 코드를 추가하지 않아도 돼요. 토스 픽셀 로더가 자동으로 수집하는 표준 이벤트는 수동으로 다시 호출하지 마세요.
{% endhint %}

### 1. 커스텀 이벤트

표준 이벤트로 분류되지 않는 전환을 추적할 때 사용해요. 추적하려는 페이지나 동작에 다음과 같이 이벤트명을 직접 지정할 수 있어요.

{% code overflow="wrap" %}

```html
<!-- Toss Pixel 커스텀 이벤트 -->
<script>
    TossPixel('전환 코드').custom('BUTTON_CLICK', {
        event_id: "고유 값",
    });
</script>
```

{% endcode %}

| 파라미터        | 타입     | 필수 여부 | 설명                                      |
| ----------- | ------ | ----- | --------------------------------------- |
| `eventName` | string | 필수    | 이벤트명. 예: `BUTTON_CLICK`, `WISHLIST_ADD` |
| `params`    | object | 선택    | 이벤트에 포함할 추가 데이터                         |

### 2. 커스텀 프로퍼티

모든 표준 이벤트와 커스텀 이벤트에 `custom_param1`부터 `custom_param5`까지 추가할 수 있어요. 표준 파라미터로 표현하기 어려운 캠페인 구분값, 프로모션 코드, A/B 테스트 그룹, 유입 경로 등을 전달할 때 사용해 주세요.

{% code overflow="wrap" %}

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

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

{% endcode %}

## 설치 확인

### 1. Toss Pixel Helper에서 확인하기

[Toss Pixel Helper](https://chromewebstore.google.com/detail/toss-pixel-helper/kbbggbgnfmbpjpaieklnbbjfkjkkpcbi)를 설치한 뒤 쇼핑몰에 접속해 픽셀이 활성화되는지 확인해 주세요.

아래 행동을 실제로 수행하고 이벤트가 한 번씩 발생하는지 확인해 주세요.

* PC와 모바일에서 페이지 방문
* 상품 상세 페이지 조회
* 장바구니 담기
* 회원가입 완료
* 테스트 주문 및 주문 완료

### 2. 토스애즈에서 수집 확인하기

토스애즈의 픽셀 이벤트 테스트에서 동일한 전환 추적 코드를 선택하고 테스트한 이벤트가 수집되는지 확인해 주세요.

브라우저에서 이벤트가 발생했는지는 Toss Pixel Helper로, 토스애즈에 이벤트가 수집됐는지는 [픽셀 이벤트 수집 확인하기](/guide/tracking/tosspixel/pixel_event.md)에서 확인할 수 있어요.

## 문제 해결

### 픽셀이 감지되지 않아요

* 토스 픽셀 로더를 설치했다면 URL의 `conversion_id`가 실제 전환 추적 코드와 일치하는지 확인해 주세요.
* PC와 모바일 디자인 양쪽에 모두 설치했는지 확인해 주세요.

### 구매 이벤트는 보이지만 매출액이나 통화가 보이지 않아요

* 수동 설치 코드에 `revenue`와 `currency`가 포함됐는지 확인해 주세요.
* 토스 픽셀 로더로 변경한다면 기존 공통 스크립트와 이벤트 스크립트를 모두 삭제한 뒤 설치해 주세요.
* 테스트 주문 후 구매 이벤트에 매출액과 통화가 함께 수집되는지 다시 확인해 주세요.

### 같은 이벤트가 두 번 발생해요

* 토스 픽셀 로더와 기존 수동 이벤트 코드가 함께 설치돼 있는지 확인해 주세요.
* 같은 페이지 또는 버튼에 표준 이벤트 호출 코드가 중복으로 설치돼 있는지 확인해 주세요.
* 중복 코드를 제거한 뒤 다시 테스트해 주세요.

## 자주 묻는 질문

### PC와 모바일 디자인에 각각 설치해야 하나요?

네. 카페24의 PC 디자인과 모바일 디자인은 별도의 HTML 파일을 사용할 수 있으므로 두 디자인 모두 확인해 주세요. 사용하는 스크립트는 같아요.

### 토스 픽셀 로더를 설치하면 이벤트별 코드를 따로 넣어야 하나요?

아니요. 토스 픽셀 로더가 지원하는 표준 이벤트는 별도 코드를 넣지 않아도 돼요. 지원하지 않는 이벤트나 직접 정의한 커스텀 이벤트에는 수동 코드가 필요할 수 있어요.

### 기존 수동 설치 코드를 그대로 둬도 되나요?

아니요. 기존 표준 이벤트 코드를 그대로 둔 상태에서 토스 픽셀 로더를 설치하면 전환 수치가 정확하게 집계되지 않을 수 있어요. 기존 공통 스크립트와 표준 이벤트 스크립트를 모두 삭제한 뒤 토스 픽셀 로더를 설치해 주세요.

### 카페24 디자인을 변경하면 다시 설치해야 하나요?

디자인을 복사하거나 새 디자인으로 교체하면 픽셀 코드가 함께 복사되지 않을 수 있어요. 디자인 변경 후 PC와 모바일의 공통 레이아웃에서 스크립트가 유지되는지 다시 확인해 주세요.

### 수동 설치로 다른 이벤트도 설치할 수 있나요?

가능해요. 토스 픽셀 로더가 자동 수집하지 않는 이벤트는 카페24 디자인 편집기에서 이벤트가 발생하는 페이지를 찾아 수동으로 설치해 주세요. 이벤트의 파라미터 상세 스펙은 [자사몰 픽셀 연동의 이벤트 스크립트 예시](/guide/tracking/tosspixel/preservationguide-1.md#undefined-1)를 참고해 주세요.


---

# 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://toss-ads.gitbook.io/guide/tracking/tosspixel/24.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.