Singular Website SDK (GTM Integration) |
|
---|---|
브라우저 호환성 |
|
소개
Singular Website SDK를 사용하면 웹 사이트의 활동을 마케팅 터치포인트에 어트리뷰트하고 웹 사이트 내의 사용자 이벤트를 추적할 수 있습니다. 또한 Singular의 크로스 디바이스 어트리뷰션 솔루션의 핵심 구성 요소로서 사용자 여정을 분석하고 플랫폼 간 LTV 및 ROAS를 계산할 수 있습니다. Singular Website SDK는 본 문서에서 설명하는 기본 JavaScript 버전 외에도 Google 태그 관리자 템플릿으로도 제공됩니다.
참조: Singular Website SDK를 Google 태그 관리자 없이 네이티브로 연동할 수도 있습니다
준비 사항
Singular Website SDK 연동을 시작하기 전에 아래 사항을 반드시 확인하세요.
- 웹사이트에 Google 태그 관리자(Google Tag Manager)가 설정되어야 합니다.
- 전환 이벤트와 모든 커스텀 이벤트를 포함하여 Singular로 보내려는 모든 이벤트에 대한 Google 태그 매니저 트리거를 설정해야 합니다. 트리거에 대해서는 Google의 트리거 정보 문서를 참조하세요.
- Singular로 보내려는 이벤트에 대한 Google 태그 매니저 변수를 설정해야 합니다. 예를 들어 트랜잭션 이벤트를 보내면서 트랜잭션 매출을 포함하고자 한다면, 트랜잭션 금액(sum)과 통화 단위(currency)를 추가해야 합니다. 자세한 내용은 Google의 변수 정보를 참조하세요.
Singular SDK 연동
SDK 초기화
Singular Web SDK를 웹사이트에서 사용하려면 Singular 초기화 태그를 추가해야 합니다. on window loaded와 같이 웹사이트가 로딩되자마자 (예: window loaded) 초기화를 발동하도록 권장합니다.
Singular 초기화 태그는 다음처럼 추가할 수 있습니다.
- Google 태그 관리자 계정에서 Tags > New 클릭
- In the Tag Configuration 창에서 Tag Configuration를 클릭한 후 Tag Type 메뉴에서 “Singular Web Tracking” 선택
- Track Type 아래에서 “Initialization” 선택
- 필요 파라미터 삽입
- API Key: 고객사의 Singular SDK API key, 예: “example_api_key1”.
- Secret: 고객사의 Singular SDK secret, 예: “ff3bfbce70b42a70fe920f42737d2123”.
- Product Id: 웹 사이트의 이름. DNS 표기를 역순으로 사용하기를 권장. 예: “com.example.site”. 이 이름은 Singular 전체 플랫폼에서 웹사이트를 식별하는 식별자로 활용됨.
- 선택 사항:
- Log Level: 콘솔에 표시할 SDK 디버그 로깅 설정, 기본값 none.
- Session Timeout: SDK가 새 세션을 생성하기 전 유저의 인액티비티 윈도우 기간. Singular는 유저 리텐션 계산 및 리인게이지먼트 어트리뷰션 활성화를 위해 유저 세션을 전송함. 기본값 30분
- 크로스 서브-도메인 트래킹
- Triggering 클릭 후 “Window Loaded” 트리거 추가
- Save 클릭
중요: 단일 페이지 애플리케이션(SPA, Single Page Applications)에서는 다른 페이지로 라우팅할 때마다 PageVisit trackType을 발동해야 합니다. 또한 초기화를 통해 page visit이 전달되므로 첫 페이지에서는 PageVisit을 따로 호출하지 않아야 합니다.
선택 사항: 유저 ID 설정
유저가 웹사이트에서 로그인없이 활동한 이벤트는 Singular가 생성한 유저 ID로 Singular에 전송됩니다. 유저가 가입하거나 로그인한다면 이메일 주소처럼 웹사이트에서 사용하는 실제 해당 유저 ID로 Singular에 이벤트를 전송할 수 있습니다.
이러한 유저 ID는 Singular의 유저 레벨 데이터 익스포트(Exporting Attribution Logs 참조)에서 확인할 수 있으며, 내부 BI 포스트백(Configuring Internal BI Postbacks 참조)을 설정한 경우에는 BI로도 전송할 수 있습니다.
다음 두 가지 방법을 통해 유저 ID를 Singular로 전송할 수 있습니다.
- 권장 사항: 웹사이트가 열릴 때 유저 ID를 알 수 있다면 Initialization track type에 “Custom user ID”를 설정하세요. 이를 통해 최초의 page visit 부터 유저 ID를 확인할 수 있습니다. 앞서 설명한 SDK 초기화 항목을 참조하세요.
- 아니면 실행 중 어느 지점에서라도 Login 메서드를 사용할 수 있습니다. 유저 ID 식별이 가능한 시점에 바로 이 메서드를 호출하는 것을 권장합니다.
유저 ID를 Singular로 보내려면 “Login” track type으로 Singular 태그를 추가합니다.
- Google 태그 관리자 계정에서 Tags > New 클릭
- Tag Configuration 창에서 Tag Configuration 클릭 후 Tag Type 메뉴에서 “Singular Web Tracking” 선택
- Track Type 아래에서 “Login” 선택
- Custom User Id 아래에 유저 ID를 포함한 Google 태그 관리자 변수 입력
- Triggering 클릭 후 triggering event 추가: user login 혹은 registration
- Save 클릭
유저 ID 설정을 해제하려면 “Logout” track type으로 태그를 추가하세요.
- Google 태그 관리자 계정에서 Tags > New 클릭
- Tag Configuration 창에서 Tag Configuration 클릭 후 Tag Type 메뉴에서 “Singular Web Tracking” 선택
- Track Type 아래에서 “Logout” 선택
- Triggering 클릭 후 triggering event 추가: user logout
- Save 클릭
주의:
- 유저 ID는 logout track type을 사용하거나 유저가 로컬 저장소를 삭제하기 전까지 유지됩니다.
- 웹사이트를 닫거나 새로고침하는 것으로는 유저 ID 설정이 해제되지 않습니다.
- Incognito처럼 프라이빗 모드로 브라우징하는 경우 브라우저가 닫히면 자동으로 로컬 저장소가 삭제되므로 유저 ID가 저장되지 않습니다.
선택 사항: 이벤트 및 매출 트래킹
이벤트 트래킹
캠페인 성과를 분석하고 KPI를 측정하기 위해 Singular를 통해 앱 내의 이벤트 데이터를 수집할 수 있습니다. 예를 들어 고객사는 유저 로그인, 회원 가입, 튜토리얼 완료 등과 같은 데이터를 수집하기를 원할 수 있습니다.
이 경우 event 메서드를 사용해서 Singular에 이벤트를 전송할 수 있습니다.
주의:
- 서드 파티 파트너 및 외부 분석 솔루션과의 호환성을 위해 이벤트 이름과 속성에는 영어를 사용하세요.
- 이벤트 이름은 32자 이하의 ASCII 캐릭터로 제한됩니다. ASCII 캐릭터가 아닌 문자열은 UTF-8로 변환되었을 때 32 byte 미만이어야 합니다.
- 속성과 값은 500자 이하의 ASCII 캐릭터로 제한됩니다.
커스텀 이벤트는 아래 단계를 통해 트래킹할 수 있습니다.
- Google 태그 관리자 계정에서 Tags > New 클릭
- Tag Configuration 창에서 Tag Configuration 클릭 후 Tag Type 메뉴에서 “Singular Web Tracking” 선택
- Track Type 아래에서 “Custom Event” 선택
- Event Name 아래에서 이벤트 이름을 입력하거나 이미 정의된 Google 태그 매니저 변수가 있는 경우 해당 변수 입력
- Triggering 클릭 후 triggering event 추가
- Save 선택
매출 트래킹
캠페인 성과 및 캠페인 ROI를 분석하기 위해 Singular를 통해 웹사이트에서 획득한 매출 데이터를 수집할 수 있습니다. 수집하는 경우 Singular의 리포트, 로그 익스포트, 포스트백을 통해 해당 데이터를 확인할 수 있습니다.
매출 이벤트 전송에는 revenue 메서드를 사용할 수 있습니다. 커스텀 이벤트 이름으로 매출 이벤트를 전달하면 Singular 리포트에서 여러 가지 매출 이벤트 유형을 분류해서 볼 수 있습니다.
주의: 매출을 여러 다른 통화 단위로 보내더라도 데이터 확인 시에는 Singular 계정에 설정한 고객사의 통화 단위로 자동으로 변환되어 표시됩니다.
매출 이벤트는 다음 단계를 통해 트래킹할 수 있습니다.
- Google 태그 관리자 계정에서 Tags > New 클릭
- Tag Configuration 창에서 Tag Configuration 클릭 후 Tag Type 메뉴에서 “Singular Web Tracking” 선택
- Track Type 아래에서 “Revenue Event” 선택
- Event Name 아래에서 이벤트 이름을 입력하거나 이미 정의된 Google 태그 매니저 변수가 있는 경우 해당 변수 입력.
- Currency 아래에서 3글자 ISO 4217 통화단위 코드 입력 (예: “USD”, “EUR”, “KRW")
- Revenue 아래에서 트랜잭션 금액을 포함하는 변수 입력(예:1.99와 같은 십진법(decimal) 숫자)
- Triggering 클릭 후 triggering event 추가
- Save 클릭
선택 사항: 크로스-서브도메인 트래킹
기본적으로 Singular Website SDK는 Singular 디바이스 ID(SDID)를 생성하고 브라우저 스토리지에 저장합니다. 해당 스토리지는 서브도메인간 공유되지 않으므로 SDK는 각 서브도메인마다 새로운 ID를 생성하게 됩니다.
서브도메인 사이에 Singular 디바이스 ID를 저장하고자 한다면 다음 중 하나의 옵션을 사용하세요.
메서드 A: 쿠키를 사용한 자동 저장(Auto-Persist)
커스텀 퍼스트 파티 쿠키를 사용해서 Singular SDK가 Singular 디바이스 ID를 저장하도록 할 수 있습니다. 트래킹할 메인 도메인에 다음 메서드를 설정하세요.
메서드 B (고급 사항): GTM 변수 사용을 위해 Singular 디바이스 ID 읽기
Singular SDK가 디바이스 ID를 자동으로 저장하기를 원하지 않는다면 수동으로 각 도메인간 ID가 저장되도록 할 수 있습니다. 예를 들어 Singular에서 ID값(유효한 uuid4 형식)을 생성한 후, 탑레벨 도메인 쿠키나 서버 사이드 쿠키 등을 사용해서 다른 쪽으로 직접 ID 값을 넘기는 방식입니다.
주의: 커스텀 JavaScript 변수를 정의하고 Init 트랙 타입 태그를 호출한 이후 singularSdk.getSingularDeviceId()를 호출해서 Singular 디바이스 ID를 읽을 수 있습니다.
커스텀 유저 ID 디바이스 매핑
중요 사항: 이 기능은 고급 사양이므로 구현 전 Singular의 솔루션 엔지니어와 상의하세요.
Singular는 추가적인 웹 트래킹 데이터를 서버 투 서버 연동을 통해 받을 수 있습니다. 본 기능을 사용하려면 커스텀 유저 ID를 Singular의 웹 트래킹 식별자와 매핑해야 합니다.
주의: 이 메서드를 Singular SDK 초기화 직후 혹은 커스텀 유저 ID를 사용할 수 있는 가장 빠른 시점에 호출하세요.
커스텀 유저 ID를 Singular의 웹 트래킹 식별자로 매핑하려면 다음 단계를 따릅니다.
- Google Tag Manager 계정에서 Tags > New를 클릭합니다.
- Tag Configuration 윈도우에서 Tag Configuration를 클릭하고 Tag Type 메뉴에서 “Singular Web Tracking”를 선택합니다.
- Track Type 하단에서 “Set Device Custom User Id”를 선택합니다.
- Custom User Id 아래에 유저 ID를 넣은 Google Tag Manager 변수를 입력합니다.
- Triggering을 클릭하고 triggering 이벤트를 추가합니다.
- Click Save를 클릭합니다.