개요 (Overview)

이 문서는 SNS별 공식·연계 광고 라이브러리(웹 픽셀, 모바일 SDK, 서버→서버 API, Ads/Marketing API 등) 을 전문가 관점에서 체계적으로 분류·정리한 옵시디언(Obsidian) 마크다운 문서입니다. 한국 사용자를 주 대상(audience)으로 하여, 영어 기반 용어는 병기(한국어 병행 표기)하였고, 실무 적용(구현 우선순위·체크리스트·샘플 코드·테스트 절차) 관점에서 업그레이드했습니다.

문서는 다음을 포함합니다:

• 광고 라이브러리의 유형 정의(실무 분류)

• 플랫폼별(대표 SNS) 상세 목록 및 구현 포인트

• 권장 아키텍처(웹/앱/서버 관점)과 우선순위

• 회사/서비스별(이커머스, 모바일게임) 맞춤 이벤트 네이밍 템플릿

• 서버·플랫폼 간 이벤트 샘플(JSON), deduplication(중복제거) 설계

• Meta Conversions API / GA4 Measurement Protocol / TikTok Events API 샘플 호출

• 테스트·QA 체크리스트 및 샌드박스/디버그 방법

• Mermaid 다이어그램(데이터·이벤트 흐름) 및 요약 표

• 참고 링크(공식 문서 full-URL)

목차 (Table of Contents)

1. 개요

2. 광고 라이브러리 유형(분류)

3. 플랫폼별 핵심 목록(요약 표)

4. 플랫폼별 세부 설명

5. 구현 우선순위 & 권장 아키텍처

6. 회사/서비스별 맞춤 템플릿 (이커머스, 모바일게임)

7. 이벤트 네이밍 표준(샘플) & 데이터 스키마

8. 서버→서버(Conversions) 샘플 요청 예제

   • Meta Conversions API (cURL 샘플)

   • GA4 Measurement Protocol (cURL 샘플)

   • TikTok Events API (cURL 샘플)

9. Deduplication(중복제거) 설계 및 예제

10. 프라이버시·동의(CMP) 연동 가이드

11. 테스트 전략, QA 체크리스트, 샌드박스 사용법

12. MMP/서드파티 통합(AppsFlyer/Adjust/Branch 등)

13. 보안·데이터 거버넌스·보관정책

14. Mermaid 다이어그램(데이터/이벤트 흐름)

15. 요약 도표(핵심 한눈 보기)

16. 인사이트·핵심 정리

17. 추천 방안 및 우선순위

18. 추가 고려사항

19. 문서의 한계점

20. 참고자료 & 링크

21. 태그

1. 광고 라이브러리 유형(분류) — 실무 관점

(기존 항목 유지, 필요 시 내부 링크로 상세 전환)

1. 클라이언트 태그 / 픽셀 (Web Pixel / Tag)

2. 모바일 SDK (In-app SDK)

3. 서버→서버 전송 API (Server-to-Server / Conversions API / Events API)

4. 광고관리·오토메이션 API (Ads Management / Marketing API)

5. 타겟·오디언스 연동 (Audience Match / CRM Upload)

6. 측정·애널리틱스 라이브러리 (Analytics / Measurement SDK)

7. 모네타이제이션 / 인앱 광고 SDK (Ad Network SDK / Mediation)

8. 크리에이티브 업로드/미디어 라이브러리

9. 프라이버시·동의 관리 연동 (CMP SDK)

10. 서드파티 통합 (MMP / CDP / Tag Manager)

2. 플랫폼별 핵심 목록(요약 표)

(요약 표는 기존 내용을 유지하되, 각 항목에 ‘샌드박스/디버그 엔드포인트’ 칼럼을 추가)

3. 플랫폼별 세부 설명 (업그레이드된 포인트)

각 플랫폼 섹션에 아래 항목을 추가했습니다:

• 샘플 이벤트 매핑 테이블

• 서버→서버 전송의 인증 방식 요약

• 테스트/디버그 엔드포인트 표기

• deduplication(중복제거) 권장 필드

(실제 세부 항목은 플랫폼별 하위 섹션을 참조)

4. 구현 우선순위 & 권장 아키텍처 (세부 강화)

아키텍처 설계 시 고려할 핵심 포인트:

• 계층적 이벤트 파이프라인: Client (Browser/App) → Tag Manager / SDK → Backend (Event Processor) → Platform APIs / MMP

• 데이터 계약(Data Contract): 모든 이벤트는 공통 스키마(schema)로 표준화. (예: event_name, event_id, event_time, user_pseudo_id, value, currency, items)

• 동의(Consent) 우선 처리: CMP에서 거부된 사용자에 대하여는 플랫폼 전송을 차단.

• 보안: 서버→서버 통신은 TLS, API 키 보관은 비밀관리시스템(Vault) 사용.

5. 회사/서비스별 맞춤 템플릿

5.1 이커머스(온라인 쇼핑몰) 이벤트 템플릿 — (E‑commerce)

공통 이벤트 목록 (Common events)

• page_view (페이지뷰)

• view_item / view_product (상품조회)

• add_to_cart (장바구니담기)

• begin_checkout (체크아웃시작)

• add_payment_info (결제정보입력)

• purchase (구매완료)

• refund (환불)

이벤트 스키마(샘플)

{
  "event_name": "purchase",
  "event_id": "order_20250818_0001",
  "event_time": 1734441600,
  "user_pseudo_id": "anon-uuid-12345",
  "value": 95000,
  "currency": "KRW",
  "items": [
    {"item_id": "sku-0001","item_name":"Red Sneakers","quantity":1,"price":95000}
  ],
  "user_data": {"email_hash":"sha256:...","phone_hash":"sha256:..."}
}

• event_id는 deduplication(중복제거)을 위해 필수로 생성하십시오 (예: 주문번호 기반).

5.2 모바일게임 (Free-to-Play) 이벤트 템플릿 — (Mobile Game)

공통 이벤트 목록

• session_start, level_start, level_complete, in_app_purchase, ad_impression, ad_click

이벤트 스키마(샘플)

{
  "event_name": "in_app_purchase",
  "event_id": "iap_txn_20250818_54321",
  "event_time": 1734441600,
  "user_pseudo_id": "deviceid-xyz-987",
  "value": 4.99,
  "currency": "USD",
  "items": [{"item_id":"gem_pack_1","quantity":1,"price":4.99}],
  "platform_receipt": "base64_receipt_string"
}

• 인앱 결제의 경우 플랫폼(receipt) 검증 로직을 서버에 구현하고, 검증이 완료된 이벤트만 전송하십시오.

6. 이벤트 네이밍 표준(샘플) & 데이터 스키마

권장 네이밍 규칙

• 소문자_언더바 표기 (snake_case)

• 도메인 공통 이벤트: page_view, view_item, add_to_cart, purchase, lead 등

• 커스텀 이벤트는 도메인_행동 형식: promo_click, wishlist_add

표준 스키마 필수 필드

• event_name (string)

• event_id (string, unique)

• event_time (unix timestamp)

• user_pseudo_id (string, 익명ID)

• value (number, optional)

• currency (string, ISO)

• items (array)

• user_data (object, 선택적: hashed identifiers)

7. 서버→서버(Conversions) 샘플 요청 예제

주의: 아래 샘플에서는 실제 토큰·ID를 YOUR_ACCESS_TOKEN 등으로 표기했습니다. 실제 환경에서는 안전한 비밀관리시스템(Vault)으로 API 키를 관리하십시오.

7.1 Meta Conversions API (cURL 샘플)

curl -X POST "https://graph.facebook.com/v16.0/<PIXEL_ID>/events" \
 -H "Content-Type: application/json" \
 -d '{
  "data": [
    {
      "event_name": "Purchase",
      "event_time": 1734441600,
      "event_id": "order_20250818_0001",
      "user_data": {
        "em": "<sha256_email>",
        "ph": "<sha256_phone>",
        "client_ip_address": "203.0.113.0",
        "client_user_agent": "Mozilla/5.0"
      },
      "custom_data": {"currency":"KRW","value":95000}
    }
  ],
  "access_token": "YOUR_ACCESS_TOKEN"
}'

• Meta는 event_id 및 event_time을 통해 deduplication을 권장합니다. 자세한 내용은 공식 문서를 확인하세요.

참고: https://developers.facebook.com/docs/marketing-api/conversions-api/

7.2 Google Analytics 4 Measurement Protocol (cURL 샘플)

curl -X POST 'https://www.google-analytics.com/mp/collect?measurement_id=G-XXXXXX&api_secret=YOUR_API_SECRET' \
 -H 'Content-Type: application/json' \
 -d '{
  "client_id": "555",
  "events": [
    {
      "name": "purchase",
      "params": {
        "transaction_id": "order_20250818_0001",
        "value": 95000,
        "currency": "KRW"
      }
    }
  ]
}'

• GA4는 transaction_id를 사용해 중복 거래를 탐지할 수 있습니다. DebugView(디버그뷰)를 통해 실시간으로 이벤트를 확인하세요.

참고: https://developers.google.com/analytics/devguides/collection/protocol/ga4

7.3 TikTok Events API (cURL 샘플)

curl -X POST 'https://business-api.tiktok.com/open_api/v1.2/pixel/track/' \
 -H 'Content-Type: application/json' \
 -d '{
  "pixel_code": "YOUR_PIXEL_CODE",
  "event": {
    "event_name": "Purchase",
    "timestamp": 1734441600,
    "properties": {"currency":"KRW","value":95000},
    "context": {"ip":"203.0.113.0","user_agent":"Mozilla/5.0"}
  }
}'

참고: https://ads.tiktok.com/help/article/events-api

8. Deduplication(중복제거) 설계 및 예제

기본 원칙

• 클라이언트 픽셀과 서버 이벤트가 동일한 사용·동작을 보고할 수 있으므로 event_id와 event_time을 공통으로 포함시키고, 플랫폼 측 중복 제거 로직(대부분 플랫폼은 event_id 기반)을 활용합니다.

추천 필드

• event_id (unique, 주문ID 또는 UUID)

• event_time (unix timestamp)

• source (“browser” 또는 “server”)

중복제거 예시(Pseudocode)

# 서버에서 수신한 이벤트(서버 이벤트)와 클라이언트 이벤트를 병합·전송하기 전
def should_send_event(event):
    # 이벤트가 이미 플랫폼에 전송된 적이 있는지 캐시(또는 DB)를 확인
    key = f"sent_event:{event['event_id']}"
    if cache.exists(key):
        return False
    cache.set(key, True, ttl=3600)
    return True

• 플랫폼으로 전송 전 로컬 캐시 또는 DB에 event_id를 기록하여 중복 전송을 방지하십시오.

9. 프라이버시·동의(CMP) 연동 가이드

1. CMP(Consent Management Platform)를 페이지 최상단에 설치하여 사용자 동의 상태(광고, 기능, 통계 등)를 수집

2. 동의 허용 여부에 따라 태그(GTM) 또는 서버 전송을 활성/비활성화

3. 동의 철회 시 즉시 이벤트 전송 중단 및 개인식별자 제거

예시 로직(브라우저)

if (CMP.isConsentGiven('marketing')) {
  // Pixel load & fire
  loadMetaPixel();
}

10. 테스트 전략, QA 체크리스트, 샌드박스 사용법

10.1 테스트 단계

1. 로컬 개발환경에서 Tag Manager와 로컬 픽셀이 정상 로딩되는지 확인

2. 플랫폼의 디버그 툴(예: Meta Test Event Code, GA4 DebugView)로 이벤트가 도착하는지 확인

3. 서버→서버 호출은 staging 환경에서 샌드박스 토큰으로 검증

4. deduplication 및 동의 플래그가 올바르게 작동하는지 통합테스트

10.2 QA 체크리스트 (세부)

• 웹 픽셀 로딩 및 초기화 여부 확인

• 이벤트 네이밍/파라미터가 표준 스키마와 일치

• event_id 생성 규칙 검증(중복/형식)

• 서버-클라이언트 중복제거 작동 여부

• CMP 동의/비동의 시나리오 검증

• Ads API 권한/토큰 만료 처리 검증

• 로그·모니터링 알람(실패율 임계값) 설정

10.3 플랫폼별 디버그 엔드포인트

• Meta: Graph API Explorer 및 Test Event Code(픽셀 테스트코드) 사용

• GA4: DebugView(Measurement Protocol의 debug_mode 파라미터 사용 가능)

• TikTok: Ads Manager의 이벤트 테스트 도구

11. MMP / 서드파티 통합 (AppsFlyer / Adjust / Branch)

• 역할: 어트리뷰션(install attribution) 및 캠페인 성과 측정, 사기(Fraud) 감지

• 연동 포인트: SDK 설치(앱) + 서버-사이드 포스트백(postback) 설정

• 주의: MMP를 통한 데이터는 플랫폼별로 추가적인 파라미터/매핑이 필요하므로, 데이터 계약(schema)을 사전에 조정

12. 보안·데이터 거버넌스·보관정책

• API 키/시크릿은 Vault 등 비밀관리시스템에 보관

• 서버 로그에는 개인식별자(PII) 저장 금지(또는 해시화)

• 보관기간(예시): 원시 이벤트 로그 180일, 집계 리포트 3년(회사 정책 및 법규 준수)

• 접근권한: 역할 기반 접근 제어(RBAC)를 적용

13. Mermaid 다이어그램(데이터/이벤트 흐름)

13.1 하이브리드 추적 흐름 (flowchart)

%%{init: { 'theme': 'default', 'flowchart': { 'nodeSpacing': 20, 'rankSpacing': 20 }}}%%
flowchart LR
  Browser[Browser / Web Page]
--> Pixel[Tag Manager / Pixel]
  App[Mobile App]
--> SDK[In-app SDK / Analytics]
  Pixel --> Backend[Event Collector / Backend]
  SDK --> Backend
  Backend -->|Server->Platform API| Platform[Ads Platform (Meta/Google/TikTok)]
  Pixel -->|Client->Platform| Platform
  Platform -->|Reporting| BI[BI / Dashboard]

13.2 시퀀스 다이어그램 (sequenceDiagram)

sequenceDiagram
  participant U as User
  participant B as Browser
  participant S as Server
  participant P as Platform
  U->>B: Click "Purchase"
  B->>B: Pixel fires (event_id=order_1)
  B->>S: POST /events (send client event)
  S->>P: POST Conversions API (event_id=order_1)
  P-->>S: 200 OK
  P-->>B: Attribution reporting

14. 요약 도표(핵심 한눈 보기)

15. 인사이트·핵심 정리

• 하이브리드 트래킹이 현재 최선의 실무 패턴임

• 이벤트 표준화(스키마)가 데이터 품질·어트리뷰션 정확도의 핵심

• 프라이버시·동의 설계는 초기 설계단계에서 반드시 포함

• 한국 시장에서는 Kakao·Naver 연동이 도달성에 큰 영향

16. 추천 방안 및 우선순위

1. GTM + 핵심 픽셀(3종 이내) 우선 배포

2. 이벤트 표준 스키마 확정(팀 합의) 후 앱·웹에 동시 적용

3. 서버→서버(Conversions API) 우선 도입(Meta/TikTok)

4. Ads API로 운영 자동화(스케일 시)

17. 추가 고려사항

• 법무·보안팀과의 연계 검증

• 데이터 레이크·BI와의 연결(이벤트 스키마 매핑)

• 비용(광고비 외 기술 운영 비용) 산정

18. 문서의 한계점

• 플랫폼별 구체적 SDK 버전·인증 흐름(예: OAuth 토큰 갱신, App Secret 인증 등)은 수시 변경되므로, 배포전 각 플랫폼의 최신 개발문서를 반드시 확인해야 합니다.

• 중국권 플랫폼의 상세 구현(중문 문서 기반)은 별도 로컬 담당자의 검증 권장.

19. 참고자료 & 링크 (References, full-URL)

• Meta Conversions API — https://developers.facebook.com/docs/marketing-api/conversions-api/

• Meta Test Events — https://developers.facebook.com/docs/marketing-api/conversions-api/using-test-events

• Google Analytics 4 Measurement Protocol — https://developers.google.com/analytics/devguides/collection/protocol/ga4

• GA4 DebugView — https://support.google.com/analytics/answer/7201382

• Google Ads API — https://developers.google.com/google-ads/api

• TikTok Events API — https://ads.tiktok.com/help/article/events-api

• TikTok Business API — https://business-api.tiktok.com/portal/docs

• Kakao Moment / Pixel — https://developers.kakao.com/docs/latest/en/kakaomoment/pixel-and-sdk

• Naver Search Ad API Docs — https://naver.github.io/searchad-apidoc/

• AppsFlyer Developer Documentation — https://support.appsflyer.com/hc/en-us

• Adjust Documentation — https://help.adjust.com/

20. 태그

#광고라이브러리 #AdLibraries #SNS #마케팅API #MarketingAPI #트래킹 #Tracking #웹픽셀 #앱SDK #데이터거버넌스