Communitygithub.com

ooiyeefei/ccc

웹사이트에 메타 픽셀(페이스북/인스타그램 광고 추적)을 설정하고 리드(Lead), 완전한 등록(CompleteRegistration), 구매(Purchase)와 같은 전환 이벤트를 종단간(End-to-End)으로 실행합니다. 비즈니스 스위트/이벤트 매니저에서 픽셀/데이터셋 ID를 찾거나 생성하고, 기본 코드를 설치하고, 표준 이벤트를 실행하고, 광고를 시작하기 전에 메타 픽셀 헬퍼로 확인하는 과정을 안내합니다.

ccc란 무엇인가요?

이 스킬은 개발자나 마케터가 메타(페이스북/인스타그램) 광고 전환 추적을 위해 웹사이트에 메타 픽셀을 설정하는 전체 과정을 안내하는 전문 기술 번역입니다. 픽셀과 컨버전스 API(CAPI) 사이의 결정, 데이터 카테고리 선언이라는 두 가지 주요 함정을 미리 알려주며, 사용자가 이미 어느 단계까지 진행했는지(페이스북 페이지, 비즈니스 스위트, 픽셀 ID 등)를 먼저 물어보고 시작합니다. 이 스킬은 Cursor, Claude Code, Codex 등 모든 AI 어시스턴트 플랫폼에서 사용할 수 있도록 설계되었으며, SKILL.md 문서를 기반으로 픽셀/데이터셋 생성, 기본 코드 설치, 표준 이벤트 실행(Lead, CompleteRegistration, Purchase), 메타 픽셀 헬퍼를 통한 검증까지 단계별로 설명합니다. 특히 사용자가 이미 가지고 있는 리소스를 재활용하고 불필요한 계정 생성 과정을 반복하지 않도록 하며, 개인 식별 정보(PII)를 브라우저 픽셀을 통해 전송하지 말아야 하는 중요 규칙을 강조합니다.

지원 대상~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/ooiyeefei/ccc/tree/HEAD/skills/meta-pixel-setup

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

미리보기

스킬 README에서

ccc preview

문서

메타 픽셀 설정

웹사이트에서 실제 전환을 추적하는 메타 픽셀을 설정하고 검증하여, 페이스북/인스타그램 광고 최적화가 학습할 진정한 데이터를 확보합니다. 사람들이 흔히 어려워하는 두 가지 부분을 이 스킬이 먼저 알려줍니다: 픽셀 vs 컨버전스 API 결정 (메타의 마법사는 더 무거운 쪽을 적극적으로 권장합니다)과 선언할 데이터 카테고리 (잘못 선택하면 광고 실적이 제한될 수 있습니다).

용어 참고: 메타는 UI에서 "픽셀"을 "데이터셋" 으로 이름을 바꿨습니다. 데이터셋에는 픽셀과 그 데이터셋 ID = 픽셀 ID (~15–16자리 숫자)가 포함됩니다. 두 단어를 동일한 것으로 취급하세요.

사용자의 현재 상황부터 시작하세요

설정은 체인과 같습니다: 페이스북 페이지 → 비즈니스 포트폴리오 → 이벤트 매니저 → 픽셀/데이터셋 (ID 획득) → 사이트에 기본 코드 → 전환 이벤트 → 확인. 사용자는 중간 어딘가에서 시작합니다. 먼저 물어보고 그 위치에 맞게 진행하세요 — 이미 있는 것을 다시 만들지 마세요 (비즈니스에 이미 픽셀이 있는 경우가 많습니다; 데이터를 두 군데로 분산시키지 말고 재사용하세요).

질문 (사용자가 말한 내용에 맞게 조정):

  1. 페이스북 페이지와 메타 비즈니스 스위트 / 비즈니스 포트폴리오가 이미 설정되어 있나요?
  2. 이미 픽셀 / 데이터셋(이벤트 매니저에서)이 있나요? 있다면 데이터셋 ID(~16자리 숫자)가 무엇인가요? 붙여넣어 주세요 — 그것만 있으면 될 수도 있습니다.
  3. 중요한 하나의 전환은 무엇인가요 (리드/대기자 명단 제출, 가입, 구매)? 광고가 이 전환을 목표로 최적화됩니다.
  4. 사이트의 스택 + 도메인(Next.js, 일반 HTML, WordPress, Shopify) — 코드를 어떻게 삽입할지 결정합니다.

이미 데이터셋 ID와 페이지가 있다면, 설치 단계(§3)로 바로 건너뛰세요. 이미 완료한 계정 생성 과정을 다시 안내하지 마세요.

결정 1: 픽셀만 사용할까, 아니면 + 컨버전스 API를 추가할까? (픽셀만으로 시작하세요)

메타의 설정 마법사는 "컨버전스 API 및 메타 픽셀 (권장)"을 반짝이는 통계와 함께 보여줍니다. 무턱대고 선택하지 마세요. 다음은 정직한 장단점입니다:

  • 메타 픽셀 (브라우저) — 사이트에 있는 코드 스니펫이 방문자의 브라우저에서 이벤트를 전송합니다. 간단하고, 백엔드가 필요 없으며, 지금 당장 작동합니다. 출시에 필요한 전부입니다.
  • 컨버전스 API (CAPI) — 서버가 메타에 직접 이벤트를 전송합니다. 서버 간 통신이며, "개발자 지원 필요" 하고, 실제로 도움이 되려면 고객 PII(이메일, 전화번호, IP) 를 메타로 보내 매칭해야 합니다. 더 많은 개발 작업 및 더 큰 개인정보 보호/규정 준수 부담(GDPR/PDPA/CCPA)이 따릅니다.

따라서: 브라우저 픽셀로 출시하세요. 나중에 브라우저 신호 손실(광고 차단기, iOS ATT)이 실질적으로 실적에 영향을 미치고 PII/동의 문제를 해결한 경우에만 CAPI를 추가하세요. CAPI는 출시 후 최적화 단계로 취급하고, 설정 단계로 취급하지 마세요. CAPI를 연결하기 전에 반드시 references/conversions-api.md를 읽으세요 — 실수로 개인 데이터를 메타에 보내는 것을 방지하기 위해 존재합니다.

결정 2: 데이터셋 "카테고리" — 명확하게 해당되지 않으면 비워 두세요

데이터셋을 생성할 때 메타는 "해당되는 카테고리를 선택"하도록 요청합니다. 이것은 금융/건강/민감 제품에 대한 함정입니다. 대화 상자에서 경고합니다: "카테고리와 위치에 따라 데이터 공유가 제한되거나 차단될 수 있습니다." "금융 서비스", "경제적 취약성", "개인적 어려움", "국적" 과 같은 카테고리는 메타의 제한적 데이터 처리를 촉발하여 광고 최적화를 제한하거나 차단할 수 있습니다.

규칙: 자신을 정확하고 불가피하게 설명하고, 이것이 데이터를 제한한다는 것을 이해하는 경우에만 카테고리를 선택하세요. 예산 관리/생산성/SaaS 도구는 소프트웨어이지 "금융 서비스"가 아닙니다 (해당 카테고리는 대출 기관, 신용 보고서, 소비자 금융을 위한 것입니다). 확실하지 않은 경우 카테고리를 비워 두세요 (선택 사항입니다) — 비어 있으면 제한이 없음을 의미하며, 이것이 일반적인 대기자 명단/가입 테스트에 필요한 것입니다.

1. 픽셀/데이터셋 생성 또는 찾기 (ID 획득)

이벤트 매니저에서:

  1. 왼쪽 레일 → 데이터 연결 (녹색 +) → 웹 → 메타 픽셀 → 연결. (또는 데이터셋이 이미 있다면 클릭하세요 — ID가 이름 바로 아래에 있습니다.)
  2. 비즈니스 이름을 따서 이름을 지정하세요 (예: "Acme Web"). 카테고리는 결정 2를 참조하세요 (보통 비워 둡니다).
  3. 데이터셋 ID를 복사하세요 — 이름 아래에 있는 ~16자리 숫자입니다. 나중에 이벤트 매니저 → 데이터셋에서도 항상 볼 수 있습니다.
  4. 컨버전스 API vs 픽셀만 선택하는 "웹사이트 설정/연결" 마법사가 시작되면 닫거나 건너뛸 수 있습니다. ID만 있으면 됩니다; 코드는 수동으로 삽입합니다(§3). 진행하는 경우 메타 픽셀만 선택하세요(결정 1).

2. (선택 사항) 기존 픽셀 재사용

픽셀은 GA4 속성처럼 엄격한 보고 벽이 아닙니다. 하나의 픽셀은 전체 도메인 — 메인 앱 과 /waitlist 랜딩 페이지를 포괄할 수 있습니다. 두 번째 픽셀이 아닌, 이벤트 + 사용자 지정 매개변수(예: content_name: 'waitlist')로 퍼널을 구분하세요. 비즈니스에 이미 픽셀이 있다면 해당 ID를 재사용하세요.

3. 기본 코드 설치

모든 페이지의 <head>에 YOUR_PIXEL_ID를 바꿔서 붙여넣으세요. 자동으로 PageView를 실행합니다. (이벤트 매니저에서 정확한 스니펫을 복사하세요 — ID가 미리 채워져 있습니다 — 또는 다음 정식 형식을 사용하세요.)

<!-- Meta Pixel Code -->
<script>
!function(f,b,e,v,n,t,s)
{if(f.fbq)return;n=f.fbq=function(){n.callMethod?
n.callMethod.apply(n,arguments):n.queue.push(arguments)};
if(!f._fbq)f._fbq=n;n.push=n;n.loaded=!0;n.version='2.0';
n.queue=[];t=b.createElement(e);t.async=!0;
t.src=v;s=b.getElementsByTagName(e)[0];
s.parentNode.insertBefore(t,s)}(window,document,'script',
'https://connect.facebook.net/en_US/fbevents.js');
fbq('init', 'YOUR_PIXEL_ID');
fbq('track', 'PageView');
</script>
<noscript><img height="1" width="1" style="display:none"
  src="https://www.facebook.com/tr?id=YOUR_PIXEL_ID&ev=PageView&noscript=1"/></noscript>
<!-- End Meta Pixel Code -->

integrity/SRI 해시를 추가하지 마세요 — fbevents.js는 메타가 즉시 업데이트하는 버전 관리 로더이며 안정적인 해시를 게시하지 않습니다. SRI는 이를 손상시킵니다. 프레임워크별 설치(Next.js next/script, WordPress, Shopify, GTM)는 references/install-by-platform.md에 있습니다.

4. 액션 시 전환 이벤트 실행

메타의 최적화 및 보고가 인식할 수 있도록 표준 이벤트를 사용하세요 — Lead (대기자 명단/문의), CompleteRegistration (가입), Purchase (판매). 전체 목록과 각각을 사용하는 경우는 references/standard-events.md를 참조하세요. 액션이 실제로 성공한 후에만 실행하고, 잡힌 오류에 대해서는 절대 실행하지 마세요.

<script>
form.addEventListener('submit', async function (e) {
  e.preventDefault();
  try {
    await saveTheLead(/* ... */);          // 1. 먼저 저장 — 실제 성공
    if (window.fbq) fbq('track', 'Lead', { // 2. 그런 다음에만 카운트 (차단기 방어)
      content_name: 'waitlist',            // 세분화 가능, PII가 아닌 매개변수만
      value_bucket: 'high'
    });
    window.location.href = '/thank-you';
  } catch (err) {
    showError('문제가 발생했습니다. 다시 시도해 주세요.');  // 이벤트 없음, 가짜 성공 없음
  }
});
</script>

PII 규칙 — 브라우저 픽셀을 통해 개인 데이터를 전송하지 마세요

이메일, 전화번호, 이름 또는 주소를 이벤트 매개변수로 절대 전달하지 마세요. 카테고리/버킷(content_name, 값 범위, 페르소나)을 전송하세요 — 식별이 아닌 세분화에 충분한 정도입니다. (메타가 해시된 PII를 사용하는 유일한 곳은 CAPI의 고급 매칭으로, 이는 의도적이고 동의된 서버 측 선택이며(references/conversions-api.md 참조), 브라우저 이벤트에 뿌릴 것이 아닙니다.)

5. 지출 전에 반드시 확인하세요 — 게이트

라이브/미리보기 사이트에서 실제 전환을 수행한 후 다음을 확인하세요:

  • 메타 픽셀 헬퍼 Chrome 확장 프로그램을 설치하세요. 페이지를 로드하면 픽셀 + PageView가 표시됩니다. 양식을 제출하면 매개변수와 함께 Lead 이벤트가 표시됩니다.
  • 또는 이벤트 매니저 → 해당 데이터셋 → 테스트 이벤트에서 사이트 URL을 입력하고 이벤트가 실시간으로 도착하는지 확인하세요.
  • 성공 시에만 실행: 실패를 유발하고 이벤트가 실행되지 않는지 확인하세요.

전환이 올바르게 실행되는 것을 확인한 후에만 광고 예산을 시작해야 합니다. 잘못 연결된 전환은 메타가 잘못된 사람들을 대상으로 최적화하게 만들고 대시보드에서는 이를 알 수 없습니다. 전체 체크리스트: references/verify-checklist.md.

"저를 대신에 설정해 주실 수 있나요?"

계정/페이지/비즈니스-스위트/픽셀 생성은 사용자 자신의 메타 로그인이 필요합니다 — 대신 수행할 수 없습니다. 이는 짧은 UI 안내 과정입니다(이 스킬이 안내합니다). 데이터셋 ID를 얻는 것이 사용자의 유일한 작업입니다. 어시스턴트는 ID를 받으면 기본 코드 + 이벤트를 사이트에 작성할 수 있습니다. 이렇게 역할을 나누고 — 위의 두 가지 결정에 따라 사용자를 CAPI 마법사와 민감한 카테고리에서 멀어지게 하세요.

참고 파일

  • references/install-by-platform.md — Next.js, HTML, WordPress, Shopify, GTM용 기본 코드 설치.
  • references/standard-events.md — 일반적인 전환에 대한 메타 표준 이벤트 이름 및 매개변수.
  • references/conversions-api.md — CAPI가 무엇인지, 언제 가치가 있는지, 연결 전 PII/동의 보호 장치.
  • references/verify-checklist.md — 광고 지출 전 확인 게이트 (픽셀 헬퍼, 테스트 이벤트, 일반적인 실패).

Individual skills in this repo

This repo contains 3 individual skills — each has its own dedicated page.

관련 스킬