문서

개요

이 가이드에서는 추적 문제를 방지하고 데이터 정확성을 보장하는 데 도움이 되는 일반적인 구현 문제, 모범 사례 및 해결 방법을 다룹니다.

일반적인 구현 오류

오류 1: 중복 구현(네이티브 + GTM)

문제: 가장 일반적인 오류는 네이티브 자바Script SDK와 구글 태그 관리자 SDK를 동시에 구현하는 경우입니다. 이로 인해 모든 세션과 이벤트가 두 번 추적되어 모든 지표가 200% 부풀려집니다.

중요! Singular는 이벤트를 자동으로 중복 제거하지 않습니다. 두 가지 구현 방법을 모두 사용하면 모든 데이터가 두 번 계산됩니다.

이 문제를 식별하는 방법

웹사이트의 소스 코드에서 Singular SDK Script를 확인합니다.
Google 태그 관리자에서 Singular 태그를 확인합니다.
브라우저 개발자 도구에서 singular 으로 네트워크 요청을 필터링하고 페이지 로드 시 실행되는 요청 수를 계산합니다(2가 아닌 1이어야 함).

해결 방법

사용할 구현 방법을 결정합니다(네이티브 JS 권장).
다른 구현 방식을 완전히 제거합니다.
이벤트당 하나의 요청만 실행되는지 테스트합니다.
24-48시간 동안 데이터를 모니터링하여 지표가 정상으로 돌아오는지 확인합니다.

오류 2: 잘못된 제품 ID 형식

문제: 제품 ID에 잘못된 형식을 사용했습니다. 제품 ID는 모든 하위 도메인에서 웹 앱에 대해 일관성이 있어야 합니다.

일반적인 실수

웹사이트 URL 사용: www.mycompany.com ❌
대시 사용: my-company-store ❌
정방향 DNS 사용: mycompany.com.store ❌
공백 사용: my company store ❌

올바른 형식(역방향 DNS 표기법):

com.mycompany ✓

팁! 제품 ID는 모바일 앱 번들 식별자처럼 생각하세요. 소문자를 사용하고 도메인을 거꾸로 시작하며 점을 사용하여 구성 요소를 구분하세요.

이 문제를 식별하는 방법

개발자 도구에서 네트워크 요청을 확인 - 400 또는 403 오류를 찾습니다.
브라우저 개발자 도구에서 요청 페이로드의 i 매개변수를 확인합니다.
브라우저 콘솔에서 오류를 확인합니다.

해결 방법:

Singular 앱 페이지(BundleId)에서 올바른 값을 가져옵니다.
올바른 형식으로 구현을 업데이트합니다.
네트워크 요청에서 200개의 상태 코드 테스트 및 확인

오류 3: 이벤트가 여러 번 실행됨

문제: 페이지 재로드, 빠른 사용자 클릭 또는 중복 제거 로직 부족으로 인해 이벤트가 여러 번 실행됩니다. 이로 인해 이벤트 수와 전환 수가 부풀려집니다.

일반적인 원인:

사용자가 버튼을 빠르게 여러 번 클릭함
모든 페이지 렌더링에서 이벤트 코드가 실행됨(React, Vue, Angular 앱)
기본 동작을 방지하지 않는 양식 제출
페이지 새로 고침 또는 뒤로 버튼 탐색
Google 태그 관리자가 여러 번 실행을 트리거하는 경우

중요! 일부 분석 플랫폼과 달리 Singular는 이벤트를 자동으로 중복 제거하지 않습니다. 중복 추적을 방지하기 위한 안전 메커니즘을 구현하는 것은 사용자의 책임입니다.

솔루션 전략:

자세한 내용은 구현 가이드에서 전략을 검토하세요. 네이티브 JS, GTM

오류 4: SDK가 로드되지 않음

문제: Singular SDK Script가 로드되지 않아 추적이 불가능합니다.

일반적인 원인

광고 차단기에 의해 차단된 Script(주로 GTM에 영향을 미침)
콘텐츠 보안 정책(CSP) 제한
Script가 페이지의 잘못된 위치에 배치됨
구현 코드의 구문 오류
네트워크 연결 문제

진단 방법

브라우저 개발자 도구 콘솔 탭을 엽니다.
"singular" 또는 "sdk"를 언급하는 오류를 찾습니다.
콘솔에 typeof singularSdk 입력 - "정의되지 않음"이 아닌 "함수"가 반환되어야 합니다.
네트워크 탭에서 Script 로드 실패를 확인합니다.
광고 차단기를 비활성화하고 다시 테스트

해결 방법

해결 방법: 광고 차단기: 네이티브 자바Script 구현으로 전환(차단될 가능성이 낮음)
CSP 문제: 콘텐츠 보안 정책에 Singular 도메인을 추가하세요.
Script 배치: SDK Script가 <head> 태그에 있는지 확인
구문 오류: JavaScript 코드 유효성 검사

콘텐츠 보안 정책 구성

웹사이트에서 CSP 헤더를 사용하는 경우 다음 지시문을 추가하세요:

Content-Security-Policy: 
  script-src 'self' https://web-sdk-v1.singular.net;
  connect-src 'self' https://sdk-api-v1.singular.net;

모범 사례

제품 ID 관리

웹사이트 또는 웹 앱당 하나의 제품 ID 사용
모든 페이지와 하위 도메인에서 제품 ID를 일관되게 유지하세요.
팀의 지식창고에 제품 ID를 문서화하세요.
개발, 스테이징 및 프로덕션 환경에 별도의 제품 ID를 사용하세요.

이벤트 이름 지정 규칙

좋은 이름 지정 관행

명확하고 설명적인 이름을 사용하세요: Purchase, Signup_Completed, Video_Play
일관된 대문자 사용(Title_Case 권장)
공백 대신 밑줄 사용
이름은 32자 이내로 유지
특수 문자 및 이모티콘 사용하지 않기

잘못된 예

Purchase!!!🎉 (특수 문자 및 이모티콘)
user clicked the purchase button on the checkout page (너무 길거나 공백)
evt_123 (설명이 아닌)

팁! 일관성을 유지하기 위해 마케팅, 제품, 엔지니어링 팀에서 공유하는 이벤트 이름 지정 문서를 만드세요.

이벤트 매개변수 모범 사례

구매: 항상 문자열이 아닌 숫자로 전송: revenue: 49.99 revenue: "$49.99" 아닌
통화: 3글자 ISO 통화 코드를 사용합니다: USD, EUR, GBP
ID: 숫자이더라도 문자열로 전송합니다: product_id: "12345"
매개변수 이름: 일관성을 위해 snake_case 사용
값: 값: 문자열 값을 100자 미만으로 유지

테스트 전략

실행하기 전에 이 테스트 체크리스트를 따르세요:

표

테스트	확인 방법	예상 결과
SDK 로드	콘솔: `typeof singularSdk`	"함수" 반환
초기화/페이지 방문 추적	네트워크 탭: "__PAGE_VISIT__" 필터링	페이지 로드 시 요청 1건, 상태 200
이벤트 발생	이벤트 트리거, 네트워크 탭 확인, 페이로드에서 이벤트 이름("n" 매개변수)의 유효성 검사.	상태 200의 이벤트당 새 요청 1건
제품 ID가 올바름	요청 페이로드를 확인하고 페이로드에서 이벤트 이름("i" 매개변수)의 유효성을 검사합니다.	역방향 DNS 형식
중복 없음	동일한 이벤트를 3번 빠르게 트리거	단 한 번의 요청만 전송
구매 추적	구매 이벤트 페이로드 확인	구매이 숫자로 표시됨
여러 페이지	다른 페이지로 이동	모든 페이지에서 추적 작동
모바일 기기	iOS 및 Android 브라우저에서 테스트	모바일에서 추적 작동

성능 최적화

조기 로딩을 위해 <head> 태그에 SDK Script 배치
페이지당 추적되는 이벤트 수 최소화(의미 있는 액션, 마케팅 이벤트에 집중)
모든 키 입력에 대한 추적 방지(디바운싱 사용)

개인정보 보호 및 규정 준수

쿠키 공개

구성에서 교차 하위 도메인 추적을 활성화하면 Singular는 퍼스트 파티 쿠키를 설정합니다. 개인정보처리방침에 이를 공개해야 합니다.

권장 개인정보처리방침 언어:

당사는 쿠키를 사용하여 사용자 행동을 추적하고 웹사이트 경험을 개선합니다. 구체적으로 다음과 같은 쿠키를 사용합니다:

singular_device_id - 이 쿠키는 당사 웹사이트를 방문하는 사용자에게 고유 ID를 할당합니다. 이 ID는 개인정보를 수집하지 않고 방문 중 사용자 활동과 상호 작용을 추적하는 데 도움이 됩니다. 이를 통해 사용자를 구분하고 여러 세션에서 방문자 행동을 모니터링할 수 있습니다.

기간: 기간: 1년

유형: 퍼스트 파티 쿠키

제공자: Singular(https://www.singular.net/privacy-policy/)

GDPR 및 개인정보 보호 규정 준수

GDPR 준수를 위해:

기본적으로 persistentIdentifier: false 설정
사용자 동의 후에만 쿠키 활성화
사용자에게 추적 옵트아웃 기능 제공
쿠키 동의 배너에 Singular 포함

디버깅 도구 및 기법

브라우저 개발자 도구

디버깅을 위한 콘솔 명령어

// Check if SDK is loaded
typeof singularSdk
// Should return: "function"

// Test firing an event manually
window.singularSdk.event("test");

마이그레이션 체크리스트

다른 분석 플랫폼에서 이동하거나 구현을 업그레이드하는 경우:

현재 구현 감사
- 현재 추적 중인 모든 이벤트 문서화
- 추적 코드가 있는 모든 페이지 식별
- 모든 사용자 정의 매개변수 또는 사용자 ID를 기록합니다.
새로운 구현 계획
- 기존 이벤트 이름을 새로운 명명 규칙에 매핑하기
- 네이티브 JS와 GTM중 결정
- 테스트 계획 만들기
단계별 구현
- 테스트/준비 환경으로 시작
- 철저한 테스트(최소 1주일)
- 트래픽이 적은 기간 동안 프로덕션에 배포
- 1~2주 동안 기존 시스템과 병행 실행
데이터 검증
- 기존 시스템과 새 시스템 간의 메트릭 비교
- 중복 추적 확인
- 모든 이벤트가 올바르게 실행되는지 확인
- 2~4주 동안 모니터링
이전 시스템 폐기
- 이전 추적 코드 제거
- 문서 업데이트
- 새 시스템에 대한 팀 교육

도움 받기

이 가이드에서 다루지 않은 문제가 발생하는 경우:

Singular 고객 성공 매니저에게 문의하세요.
Singular 대시보드를 통해 지원 티켓을 제출하세요.
브라우저 콘솔 로그와 네트워크 요청 스크린샷을 포함하세요.
웹사이트 URL과 문제를 재현하기 위한 자세한 단계를 제공하세요.

웹 SDK - 문제 해결 및 모범 사례

개요