React에서 Buzzvil CPE/CPA 연동하기 – 실제 사례 기반 구현 가이드

 

글을 작성하는 이유

최근 회사에서 이벤트 페이지를 제작하면서 Buzzvil 광고를 연동할 일이 생겼다.

Buzzvil에서 제공하는 공식 JavaScript 가이드를 참고하면 기본적인 연동 예시는 잘 나와 있다.

하지만 문제는, React 환경에서 어떻게 이 코드를 넣고, 어떤 타이밍에 초기화하고, 어떤 시점에 track을 호출해야 하는지에 대한 자료가 거의 없다는 것.

그래서 이번 글에서는 React 기반 웹 애플리케이션에서 Buzzvil을 연동하는 방법을 실제 사용 예제와 함께 정리해보려 한다.

기본적인 연동 구조

Buzzvil 연동은 두 가지 단계로 나눠져 있다.

1. 초기화 단계 (init) – 광고 랜딩 페이지에서 Buzzvil 스크립트를 초기화.
2. 전환 완료 단계 (track) – 사용자가 특정 행동(예: 신청 완료)을 했을 때 Buzzvil에 전환을 보고.

커스텀 훅으로 정리하기

React에서는 이 두 과정을 각각 명확히 분리해 관리하는 것이 편해 보였고,

그래서 나는 아래와 같이 useBuzzvil 훅으로 추상화했다:

// useBuzzvil.ts
const useBuzzvil = () => {
  const initBuzzvil = () => {
    if (!window.bzDataLayer) {
      window.bzDataLayer = [];
    }

    const bzq = function () {
      window.bzDataLayer?.push(arguments);
    };

    // 추적 함수 등록
    window.bzq = bzq;

    // 초기화
    bzq('init', process.env.NEXT_PUBLIC_BZ_ID as string);
  };

  const trackCompleteAction = () => {
    if (typeof window.bzq === 'function') {
      window.bzq('track', { action: 'bz_action_complete' });
    }
  };

  return {
    initBuzzvil,
    trackCompleteAction,
  };
};

export default useBuzzvil;

 

초기화

Buzzvil은 광고를 통해 유입된 페이지에서 init을 실행해야 한다.

따라서 해당 랜딩 페이지의 useEffect에서 아래와 같이 호출한다:

import useBuzzvil from '@/hooks/useBuzzvil';

const EventLandingPage = () => {
  const { initBuzzvil } = useBuzzvil();

  useEffect(() => {
    initBuzzvil();
  }, []);

  return (
    <div>
      {/* 이벤트 내용 */}
    </div>
  );
};

 

랜딩 페이지와 신청 완료 지점에서 여러 페이지의 이동이 있다면 전환되는 각 페이지 내에서 위 코드처럼 useEffect와 함께 호출하면 된다.

전환 완료

이벤트 신청을 완료한 후 track을 호출하여 전환을 기록한다.

나는 아래처럼 폼 전송 성공 콜백 안에서 trackCompleteAction()을 호출했다:

const { trackCompleteAction } = useBuzzvil();

const onSubmit = handleSubmit(
  data => {
    if (userTypeTestResultId) {
      applyEvent(
        {
          testId,
          data: {
            userTypeTestResultId,
            name: data.name,
            phone: data.phone,
            email: data.email,
          },
        },
        {
          onSuccess: () => {
            trackCompleteAction(); // ✅ 전환 완료 트래킹
            setIsApplied(true);
            reset();
          },
          onError: err => {
            // 에러 처리
          },
        }
      );
    }
  },
  errors => {
    showToast('정확한 정보를 기재해 주세요', 'error');
  }
);

 

마무리

Buzzvil의 공식 문서만 보면 단순한 JS 코드 몇 줄이지만,

실제로 React 환경에서 연동하려면 초기화 타이밍, 스크립트 선언, 전환 추적 위치 등을 명확히 구분해서 설계해야 한다.

 

이 글이 React에서 Buzzvil을 연동하고자 하는 개발자에게 도움이 되었으면 한다.

만약 서버사이드 렌더링 환경(예: Next.js)에서 클라이언트 사이드 코드만 안전하게 실행하고 싶다면 typeof window !== "undefined" 같은 가드도 추가할 수 있다.