카페24 픽셀 연동

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

직접 구축한 자사몰은 자사몰 설치 가이드, 메이크샵은 메이크샵 설치 가이드를 참고해 주세요.

전환 추적 코드 생성하기

토스 픽셀을 설치하려면 전환 코드가 필요해요.

전환 코드는 토스애즈 대시보드에서 발급할 수 있고, 광고계정마다 고유하게 부여돼요.

전환 코드 발급 방법은 전환 코드 발급 가이드를 참고해 주세요.

카페 24 디자인 편집기 진입

카페24 관리자 센터에 접속

좌측 메뉴에서 디자인 (PC/모바일) 탭을 클릭해주세요.

디자인 대시보드에서 HTML 수정 하기

디자인 대시보드에서 토스 픽셀을 설치할 쇼핑몰의 디자인 편집을 클릭한 뒤,

좌측 하단의 HTML 수정 버튼을 눌러 코드 편집기를 열어 주세요.

디자인과 모바일 디자인을 모두 운영 중이라면, 두 디자인 모두에 동일하게 토스 픽셀을 설치해야 해요.

스크립트 내용은 PC와 모바일 동일해요.

지원 이벤트

토스 픽셀이 지원하는 이벤트는 다음과 같아요.

이벤트

메서드명

삽입 위치

페이지 방문

pageView()

모든 페이지

회원가입

signUp()

회원가입 완료 페이지

상품 상세 조회

productView()

상품 상세 페이지

장바구니 담기

addToCart()

장바구니 추가 버튼 클릭 시

구매

purchase()

구매 완료 페이지

커스텀 이벤트

custom()

자유롭게 정의

모든 이벤트의 파라미터는 선택사항이에요.
파라미터 없이 메서드만 호출해도 정상 수집돼요.
- 다만, 파라미터를 함께 전달하면 광고 성과를 더 정확하게 분석할 수 있어요.

토스 픽셀 설치하기

SDK 스크립트 설치

카페24의 공통 레이아웃 파일(layout.html)을 열어 <head> 태그 안에 아래 스크립트를 추가해 주세요.
SDK 스크립트는 사이트 전체에서 한 번만 로딩하면 돼요. 각 이벤트 코드마다 다시 넣을 필요는 없어요.

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

페이지 방문 (pageView)

같은 layout.html 파일에서, <body>태그 안에 아래 스크립트를 추가해주세요.

<!-- Toss Pixel 페이지 방문 이벤트 -->
<script>
    // '전환 코드' 대신 생성한 전환코드 값을 넣어주세요
    TossPixel('전환 코드').pageView();
</script>

예시 코드에서 '전화 코드' 텍스트가 있는 자리에 발급 받으신 전환 추적 코드를 넣어주세요.
변경 후에는 반드시 디자인 편집기 상단의 [저장] 버튼을 클릭해야 적용돼요.

공통 레이아웃을 사용하지 않는 페이지

쇼핑몰의 모든 페이지가 공통 레이아웃(layout.html)을 사용하지 않을 수도 있어요.
개별 페이지의 HTML 파일을 열어 공통 레이아웃 포함 코드가 없다면, 해당 페이지의 HTML 파일에 위 두 스크립트(SDK 스크립트 설치 + 페이지 방문)를 직접 추가해 주세요.

위와 같은 코드가 보인다면 기본 설정된 공통 레이아웃을 사용하는 페이지에요. 별도로 스크립트를 추가 하지 않아도 돼요.

반면 위처럼 기본 공통 레이아웃과 다른 레이아웃 파일이 보이거나, @layout 으로 시작하는 파일이 없다면 해당 페이지 HTML 파일의 <head>에 SDK 설치 스크립트를, <body> 안에 페이지 방문 이벤트 스크립트를 각각 추가해 주세요.

회원가입 결과 파일(/member/join_result.html)을 열어 <body>태그 안에 아래 스크립트를 추가해 주세요.

<!-- Toss Pixel 회원가입 이벤트 -->
<script>
    // '전환 코드' 대신 생성한 전환코드 값을 넣어주세요
    TossPixel('전환 코드').signUp();
</script>

상품 상세 페이지 조회 (productView)

상품 상세 파일(/product/detail.html)을 열어 스크립트를 추가해야 해요.
이 스크립트는 반드시 module="product_detail" 속성이 포함된 HTML 태그 안쪽에 추가해야 해요. 이 모듈 안에서만 카페24가 제공하는 상품 변수({$product_no}, {$name} 등)가 정상적으로 치환돼요.

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

{$product_no}, {$name} 등은 카페24가 각 모듈에서 제공하는 치환 변수로, 그대로 입력하면 실제 페이지에서 상품 데이터로 자동 변환돼요. 자세한 내용은 카페24 치환 변수 문서를 참고해 주세요.

장바구니 추가 (addToCart)

장바구니 담기 이벤트도 상품 상세 파일(/product/detail.html)에서 설정해요.
- 아래 방법을 따라 장바구니 버튼을 클릭하는 시점에 이벤트가 발생하도록 설정해 주세요.
장바구니 버튼 찾기
- 먼저 장바구니 버튼에 해당하는 HTML 태그의 위치를 찾아 주세요.
  - 장바구니 버튼은 module="product_action" 속성이 포함된 HTML 태그 안에 위치해요.
  - 장바구니 버튼은 onclick="{$action_basket}" 속성을 갖고 있어요.
  - 보통 "장바구니" 또는 "CART"라는 텍스트가 표시되어 있어요.
이벤트 스크립트 추가
- 장바구니 버튼 태그 아래 스크립트를 추가해 주세요.

<script>
(function() {
  var actionBasket = "{$action_basket}";
  var btn = Array.from(document.querySelectorAll('[onclick]')).find(function(el) {
    return el.getAttribute('onclick') === actionBasket;
  });
  if (btn) {
    btn.addEventListener('click', function() {
      TossPixel('전환 코드').addToCart({
        product_id: "{$product_no}",
        product_name: "{$name}",
        price: "{$product_sale_price}",
        currency: "{$price_unit_tail}"
      });
    });
  }
})();
</script>

구매 완료 (purchase)

주문 완료 파일(/order/order_result.html)을 열고 아래 가이드에 따라 설정해 주세요.

공통 레이아웃 확인
- 주문 완료 파일은 경우에 따라 공통 레이아웃을 사용하지 않을 수 있어요.
  - 공통 레이아웃을 사용하지 않는다면 주문 완료 파일(/order/order_result.html)에 SDK 스크립트와 페이지 방문 이벤트를 직접 추가해야 해요.
상품 목록 변수 선언

주문 완료 파일에서 <body> </body>태그안 최상단에 상품 목록을 담는 아래 스크립트를 넣어주세요.

<!-- Toss Pixel 구매 상품 목록 변수 -->
<script>
    var tossPixelOrderProducts = [];
</script>

상품 데이터 수집

카페24 주문 완료 파일에서 상품은 상품 모듈 단위로 반복 출력돼요. 각 상품 모듈에 아래 스크립트를 반복해 추가해 주세요.
기본 배송 상품 모듈은 <div module="Order_normalresultlist"> 태그 아래 반복되는 <div class="prdBox"> 태그에요. 상품 모듈을 찾아 각 모듈에 아래 스크립트를 추가해 주세요.

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

쇼핑몰에 개별 배송 상품이나 해외 배송 상품이 있다면 아래와 같이 스크립트를 추가해 주세요. 스크립트는 기본 배송 상품과 동일해요.

개별 배송 상품 <div module="Order_individualresultlist"> 태그 아래 반복되는 <div class="prdBox"> 태그에 스크립트 추가
해외 배송 상품 <div module="Order_oversearesultlist"> 태그 아래 반복되는 <div class="prdBox"> 태그에 스크립트 추가

구매 이벤트 전송

주문 완료 파일(/order/order_result.html)에서 module="Order_result" 속성이 포함된 태그를 찾은 뒤, 그 태그의 닫는 태그(</...> ) 바로 위에 아래 구매 이벤트 코드를 붙여 넣어 주세요.

<!-- Toss Pixel 구매 완료 이벤트 -->
<script>
    // '전환 코드' 대신 생성한 전환코드 값을 넣어주세요
    TossPixel('전환 코드').purchase({
        order_id: "{$order_id}",
        products: tossPixelOrderProducts,
        revenue: "{$total_order_price_original}",
        total_quantity: tossPixelOrderProducts.reduce(function(acc, cur) {
            return acc + Number(cur.quantity);
        }, 0),
        currency: "{$product_revenue_ref}"
    });
</script>

간편 결제 연동

네이버페이, 페이코 등 간편결제 버튼을 통한 구매를 추적할 때 사용해요
purchase 이벤트와 동일한 파라미터를 사용해요.

네이버페이, 페이코 결제 연동을 한 경우에만 진행해 주세요.

네이버페이 (purchase, purchase_type: “naverpay”)
- 상품 상세 파일(/product/detail.html)의 module="product_detail" 속성이 포함된 HTML 태그 안쪽에 아래 스크립트를 추가해 주세요.
  - purchase 이벤트와 동일한 파라미터를 사용해요.

<script type="text/javascript">
    (function () {
        const NPay_BUTTON_SELECTOR = '.npay_btn_pay';

        function bindNPayButtonClick(nPayButton) {
            if (nPayButton.dataset._npayBound) {
                return;
            }

            nPayButton.dataset._npayBound = 'true';
            nPayButton.addEventListener('click', function () {
                // '전환 코드' 대신 생성한 전환코드 값을 넣어주세요
                TossPixel('전환 코드').purchase({
                    purchase_type: "naverpay",
                    product_id: "{$product_no}",
                    product_name: "{$name}",
                    revenue: "{$product_sale_price}",
                    price: "{$product_sale_price}",
                    currency: "{$price_unit_tail}",
                });
            });
        }

        const observer = new MutationObserver(() => {
            document.querySelectorAll(NPay_BUTTON_SELECTOR).forEach(bindNPayButtonClick);
        });

        observer.observe(document.body, { childList: true, subtree: true });
    })();
</script>

커스텀 이벤트

표준 이벤트로 분류되지 않는 전환을 추적할 때 사용해요.
이벤트 이름을 직접 지정할 수 있으며, 표준 이벤트와 동일한 파라미터를 사용할 수 있어요.
추적하려는 전환이 발생하는 페이지의 파일에 아래 스크립트를 추가해 주세요.

<!-- Toss Pixel 커스텀 이벤트 -->
<script>
    // '전환 코드' 대신 생성한 전환코드 값을 넣어주세요
    TossPixel('전환 코드').custom('BUTTON_CLICK', {
        product_id: "{$product_no}",
        product_name: "{$name}",
        price: "{$product_sale_price}",
        currency: "{$price_unit_tail}"
    });
</script>

두 번째 인자에는 product_id, price, currency 등 표준 이벤트에서 사용하는 파라미터를 전달할 수 있어요.

파라미터

타입

필수

설명

eventName (첫 번째 인자)

string

필수

이벤트 이름 (예: "BUTTON_CLICK", "WISHLIST_ADD")

params (두 번째 인자)

object

선택

이벤트에 포함할 추가 데이터

커스텀 프로퍼티

모든 이벤트(표준 이벤트, 커스텀 이벤트)에 custom_param1 ~ custom_param5를 추가할 수 있어요.
product_id, price 같은 표준 파라미터로 표현하기 어려운 추가 정보를 전달할 때 사용해요.
- 예를 들어, 캠페인 구분값, 프로모션 코드, A/B 테스트 그룹, 유입 경로 등 필요에 따라 정의한 값을 담을 수 있어요.

<!-- 표준 이벤트에 커스텀 프로퍼티 추가 -->
<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>

커스텀 프로퍼티는 최대 5개까지 사용할 수 있고, 표준 파라미터와 함께 하나의 객체로 전달해 주세요.

프로퍼티

타입

설명

custom_param1

string

커스텀 프로퍼티 1

custom_param2

string

커스텀 프로퍼티 2

custom_param3

string

커스텀 프로퍼티 3

custom_param4

string

커스텀 프로퍼티 4

custom_param5

string

커스텀 프로퍼티 5

설치 확인

토스 픽셀이 정상적으로 설치되었는지 아래 방법으로 확인할 수 있어요.

Toss Pixel Helper 크롬 확장프로그램

Toss Pixel Helper를 설치하면, 현재 페이지에서 수집된 토스 픽셀 이벤트를 실시간으로 확인할 수 있어요.

자세한 사용 방법은 픽셀 이벤트 수집 확인하기 페이지를 참고해주세요.

자주 묻는 질문

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

A. PC 디자인과 모바일 디자인은 별도의 HTML 파일을 사용하므로, 두 디자인 모두에 동일하게 설치해야 해요. 스크립트 내용은 동일해요.

Q. 파라미터를 보내지 않아도 되나요?

A. 가능해요. 모든 파라미터는 선택사항이에요. 메서드만 호출해도 정상 수집돼요. 다만, 파라미터를 함께 전달하면 광고 성과를 더 정확하게 분석할 수 있어요.

Q. 리드 수집 이벤트도 사용할 수 있나요?

A. 가능해요. 카페24 디자인 편집기에서 리드 제출이 발생하는 페이지의 파일을 찾아 스크립트를 추가해 주세요. lead() 이벤트의 파라미터 상세 스펙은 자사몰 설치 가이드를 참고해 주세요.

이전자사몰 픽셀 연동 다음메이크샵 픽셀 연동

마지막 업데이트 14일 전

좋은 오후입니다

전환 추적 코드 생성하기

카페 24 디자인 편집기 진입

지원 이벤트

토스 픽셀 설치하기

SDK 스크립트 설치

페이지 방문 (pageView)

공통 레이아웃을 사용하지 않는 페이지

회원 가입 (signUp)

상품 상세 페이지 조회 (productView)

장바구니 추가 (addToCart)

구매 완료 (purchase)

상품 데이터 수집

구매 이벤트 전송

간편 결제 연동

커스텀 이벤트

커스텀 프로퍼티

설치 확인

자주 묻는 질문