Singular Website SDK
다운로드	Singular Website SDK version 1.3.5
브라우저 호환성	Chrome: 15+ Safari: 5.1+ Edge: 15+ Firefox: 6+ Internet Explorer: 10+ Opera: 15+

소개

Singular Website SDK를 사용하면 웹 사이트의 활동을 마케팅 터치포인트에 어트리뷰트하고 웹 사이트 내의 사용자 이벤트를 추적할 수 있습니다. 또한 Singular의 크로스 디바이스 어트리뷰션 솔루션의 핵심 구성 요소로서 사용자 여정을 분석하고 플랫폼 간 LTV 및 ROAS를 계산할 수 있습니다. Singular Website SDK는 본 문서에서 설명하는 기본 JavaScript 버전 외에도 Google 태그 관리자 템플릿으로도 제공됩니다.

사이트에 SDK 스크립트 추가

다음 중 하나의 방법을 선택해서 고객사의 웹사이트나 웹앱에 SDK를 추가할 수 있습니다.

Singular CDN 상의 스크립트와 링크

이 방법으로 Singular가 CDN을 통해 호스트하는 JavaScript를 링크할 수 있습니다.

트래킹하려는 모든 페이지의 <head> 태그 내에 다음 코드를 추가하세요.

<head>
    <!-- Using the latest SDK version   -->
    <script src="https://web-sdk-cdn.singular.net/singular-sdk/latest/singular-sdk.js">
    </script>
</head>

주의: 위 코드는 가장 최신 SDK 버전으로 링크합니다. 특정 SDK 버전의 사용을 원하는 경우 다음 코드를 사용하세요:

<head>
    <!-- Using a fixed SDK version   -->
    <script src="https://web-sdk-cdn.singular.net/singular-sdk/1.3.5/singular-sdk.js">
    </script>
</head>

NPM으로 설정

프로젝트의 루트 디렉터리에서 `npm i singular-sdk`를 실행하거나, package.json 파일의 디펜던시에 `"singular-sdk": "^1.3.5"`를 추가한 후 `npm install`을 실행하세요.
SDK를 사용하려는 스크립트 내에 다음 코드를 추가합니다.

import {singularSdk, SingularConfig} from "singular-sdk";

SDK 초기화

SDK 초기화 코드는 페이지가 로딩될 때마다 호출돼야 합니다. 이는 모든 Singular 어트리뷰션 기능을 사용하기 위한 전제 조건으로 다음 활동을 수행합니다.

Singular에 새 페이지 방문(page visit)을 전송합니다.
유저가 새로운 광고 데이터를 통해 방문하거나 세션 타임아웃이 지난 이후에 방문한 경우 새로운 유저 세션을 생성합니다.

페이지 방문과 유저 세션은 유저 리텐션 계산 및 리인게이지먼트 어트리뷰션 활성화에 사용됩니다.

1. SingularConfig 오브젝트 생성

SDK를 초기화하기 전 SingularConfig를 먼저 생성해야 합니다. 이 오브젝트는 다음 내용을 포함합니다.

API Key, API Secret, Product Id
SDK 환경 설정을 선택적으로 지정 가능

기본적인 SingularConfig 오브젝트를 생성하려면 다음 코드를 사용하세요.

const config = new SingularConfig(apiKey, secretKey, productId);

기본 설정 외에도 Singular에서 제공하는 다양한 기능을 선택적으로 추가할 수 있습니다.

이 경우 SingularConfig 오브젝트의 ".with" 메서드를 사용할 수 있습니다. 다음 예시와 같은 형태입니다.

// Singular에 유저 ID를 전달하도록 SDK 설정
const config = new SingularConfig(apiKey, secretKey, productId)
    .withCustomUserId(userId);

SingularConfig 메서드 참조

".with" 메서드에서 설정 가능한 다양한 옵션을 아래 표에서 확인하세요.

메서드	정의	비고
.withCustomUserId(customId)	Singular에 유저 ID 전송	유저 ID 설정
.withProductName(productName)	프로덕트 디스플레이 네임 (선택 사항)
.withLogLevel(logLevel)	로그 레벨 설정: 0 - None(기본값); 1 - Warn; 2 - Info; 3 - Debug.
.withSessionTimeoutInMinutes (timeout)	세션 타임아웃을 분 단위로 설정 (기본값: 30분)
.withAutoPersistentSingularDeviceId (domain)	자동 크로스-서브도메인 트래킹 활성화	쿠키를 사용한 자동 저장(Auto-Persist)
.withPersistentSingularDeviceId (singularDeviceId)	수동 크로스-서브도메인 트래킹 활성화	Singular 디바이스 ID 수동 설정
.withInitFinishedCallback(callback)	SDK 초기화가 완료된 경우 콜백 호출	초기화가 완료되면 콜백 호출

2. Singular 초기화

SingularConfig 오브젝트를 생성한 후 init 메서드를 사용해서 Singular를 초기화하고 SingularConfig 오브젝트를 전달할 수 있습니다.

코드의 어느 지점에서라도 init 메서드를 호출할 수 있지만 반드시 이벤트를 전달하기 전에 호출해야 합니다. 트래킹할 각 페이지의 로딩 중에 호출하는 것을 권장합니다.

init 메서드
정의	SingularConfig 오브젝트에 설정된 구성으로 SDK 초기화
메서드	init(config)
사용예	`function initSingular() { const config = new SingularConfig(apiKey, secretKey, productId); singularSdk.init(config); }`

중요: 단일 페이지 애플리케이션(SPA, Single Page Applications)에서는 다른 페이지로 라우팅할 때마다 singularSdk.pageVisit()를 호출해야 합니다. 또한 singularSdk.init를 통해 page visit이 전달되므로 첫 페이지에서는 singularSdk.pageVisit()을 따로 호출하지 않아야 합니다.

초기화가 완료될 때 콜백 함수 호출

초기화가 완료된 시점에 콜백 함수 호출을 설정하려면 SingularConfig 객체의 .withInitFinishedCallback(callback) 메서드를 사용하세요.

withInitFinishedCallback 메서드

정의 초기화 프로세스가 완료되면 호출되도록 콜백 설정

메서드 withInitFinishedCallback(callback)

사용예

function initSingular() {      
  const config = new SingularConfig(apiKey, secretKey, productId)
    .withInitFinishedCallback(initParams=> {
      // 이 콜백은 init 메서드가 완료되면 호출됨

      // 아래 메서드를 활용하면 Singular 디바이스 ID(SDID)를 확인 가능
      const singularDeviceId = initParams.singularDeviceId;
    });
singularSdk.init(config);
}

선택 사항: 유저 ID 설정

Singular SDK를 사용하여 앱에서 Singular로 유저 ID를 전달할 수 있습니다. 유저 ID는 유저네임, 이메일 주소, 랜덤 생성 문자열 등 유저를 식별하는 어떤 값이라도 가능합니다.

Singular로 전달한 유저 ID는 유저레벨 데이터를 추출하거나 고객사가 내부 BI 포스트백을 설정한 경우 포스트백 내의 데이터 형태로 전달될 수 있습니다.

Singular에 유저 ID를 보내려면 다음 두 가지 방법 중 하나를 사용하세요.

권장 사항: 웹사이트가 열리는 시점에 유저 ID를 알 수 있다면 SDK를 초기화하기 전에 SingularConfig 오브젝트에 유저 ID를 설정하세요. 이를 통해 최초의 page visit 부터 유저 ID를 확인할 수 있습니다.

const config = new SingularConfig("apikey","secret",“productId”)
    .withCustomUserId("custom_user_id");
singularSdk.init(config);

또는 실행 중 언제든지 login 메서드를 호출할 수도 있습니다. 유저 ID를 확인 가능한 시점에 바로 호출하기를 권장합니다.

주의:

유저 ID는 logout 메서드를 호출하거나 유저가 로컬 저장소를 삭제하기 전까지 유지됩니다.
웹사이트를 닫거나 새로고침하는 것으로는 유저 ID 설정이 해제되지 않습니다.
Incognito처럼 프라이빗 모드로 브라우징하는 경우 브라우저가 닫히면 자동으로 로컬 저장소가 삭제되므로 유저 ID가 저장되지 않습니다.

login 메서드
정의	Singular에 유저 ID 전송
메서드	login(customUserId)
사용예	`singularSdk.login("custom_user_id");`
logout 메서드
정의	Singular로 전송된 유저 ID를 해제
메서드	logout()
사용예	`singularSdk.logout();`

선택 사항: 이벤트 및 매출 트래킹

이벤트 트래킹

캠페인 성과를 분석하고 KPI를 측정하기 위해 Singular를 통해 앱 내의 이벤트 데이터를 수집할 수 있습니다. 예를 들어 고객사는 유저 로그인, 회원 가입, 튜토리얼 완료 등과 같은 데이터를 수집하기를 원할 수 있습니다.

이 경우 event 메서드를 사용해서 Singular에 이벤트를 전송할 수 있습니다.

주의:

서드 파티 파트너 및 외부 분석 솔루션과의 호환성을 위해 이벤트 이름과 속성에는 영어를 사용하세요.
이벤트 이름은 32자 이하의 ASCII 캐릭터로 제한됩니다. ASCII 캐릭터가 아닌 문자열은 UTF-8로 변환되었을 때 32 byte 미만이어야 합니다.
속성과 값은 500자 이하의 ASCII 캐릭터로 제한됩니다.

event 메서드
정의	트래킹을 위해 추가 정보를 포함 혹은 비포함하여 이벤트를 Singular로 전송.
메서드	singularSdk.event(eventName, args) 주의: 'args'는 JavaScript의 맵 오브젝트입니다. 추가 아규먼트 없이 이벤트를 보내려면 이벤트 이름만을 포함하여 event 메서드를 호출하세요.
사용예	`// Registration_Completed 이벤트를 아규먼트 없이 전송 singularSdk.event("Registration_Completed"); // Registration_Completed 이벤트를 아규먼트를 포함하여 전송 // 아규먼트에 이메일과 전화번호를 추가 정보로 포함한 예제 singularSdk.event("Registration_Completed", {phone: '111-222-3333', email: 'example@mail.com'});`

매출 트래킹

캠페인 성과 및 캠페인 ROI를 분석하기 위해 Singular를 통해 웹사이트에서 획득한 매출 데이터를 수집할 수 있습니다. 수집하는 경우 Singular의 리포트, 로그 익스포트, 포스트백을 통해 해당 데이터를 확인할 수 있습니다.

매출 이벤트 전송에는 revenue 메서드를 사용할 수 있습니다. 커스텀 이벤트 이름으로 매출 이벤트를 전달하면 Singular 리포트에서 여러 가지 매출 이벤트 유형을 분류해서 볼 수 있습니다.

주의: 매출을 여러 다른 통화 단위로 보내더라도 데이터 확인 시에는 Singular 계정에 설정한 고객사의 통화 단위로 자동으로 변환되어 표시됩니다.

revenue 메서드
정의	추가 정보를 포함하여 Singular에 매출 이벤트 전송
메서드	singularSdk.revenue(eventName, currency, amount, args) 주의: 통화(currency)는 세 글자로 이뤄진 ISO 4217 통화 코드를 사용합니다. 예: “USD”, “EUR”, “KRW 금액(amount)는 십진법(decimal)으로 전달합니다.
사용예	`// Singular에 "Item_Purchased"라는 이름으로 매출 이벤트 전송 singularSdk.revenue("Item_Purchased","USD", 5.50); // Singular에 추가 정보를 포함하여 "Item_Purchased"라는 // 이름으로 매출 이벤트 전송 singularSdk.revenue("Item_Purchased","USD", 5.50, {phone: '111-222-3333', email: 'example@mail.com');`

선택 사항: 크로스-서브도메인 트래킹

기본적으로 Singular Website SDK는 Singular 디바이스 ID(SDID)를 생성하고 브라우저 스토리지에 저장합니다. 해당 스토리지는 서브도메인간 공유되지 않으므로 SDK는 각 서브도메인마다 새로운 ID를 생성하게 됩니다.

서브도메인 사이에 Singular 디바이스 ID를 저장하고자 한다면 다음 중 하나의 옵션을 사용하세요.

메서드 A: 쿠키를 사용한 자동 저장(Auto-Persist)

커스텀 퍼스트 파티 쿠키를 사용해서 Singular SDK가 Singular 디바이스 ID를 저장하도록 할 수 있습니다. 트래킹할 메인 도메인에 다음 메서드를 설정하세요.

withAutoPersistentSingularDeviceId 메서드
정의	Singular 디바이스 ID를 자동 저장할 메인 도메인을 포함한 설정 옵션으로 SDK를 초기화
메서드	withAutoPersistentSingularDeviceId(domain)
사용예	`function initSingular() { const config = new SingularConfig(apiKey, secretKey, productId) .withAutoPersistentSingularDeviceId(“example.com”); singularSdk.init(config); }`

메서드 B (고급 사항): Singular 디바이스 ID 수동 설정

Singular SDK가 디바이스 ID를 자동으로 저장하기를 원하지 않는다면 수동으로 각 도메인간 ID가 저장되도록 할 수 있습니다. 예를 들어 Singular에서 ID값(유효한 uuid4 형식)을 생성한 후, 탑레벨 도메인 쿠키나 서버 사이드 쿠키 등을 사용해서 다른 쪽으로 직접 ID 값을 넘기는 방식입니다.

주의: 초기화 메서드를 호출하거나 InitFinishedCallback를 사용한 이후 시점에 singularSdk.getSingularDeviceId() 메서드를 사용해서 Singular 디바이스 ID를 읽을 수 있습니다.

withPersistentSingularDeviceId 메서드
정의	저장하고자 하는 Singular 디바이스 ID를 포함한 설정 옵션으로 SDK 초기화
메서드	withPersistentSingularDeviceId(singularDeviceId)
사용예	`function initSingular() { const config = new SingularConfig(apiKey, secretKey, productId) .withPersistentSingularDeviceId(singularDeviceId); singularSdk.init(config); }`

커스텀 유저 ID 디바이스 매핑

중요 사항: 이 기능은 고급 사양이므로 구현 전 Singular의 솔루션 엔지니어와 상의하세요.

Singular는 추가적인 웹 트래킹 데이터를 서버 투 서버 연동을 통해 받을 수 있습니다. 본 기능을 사용하려면 커스텀 유저 ID를 Singular의 웹 트래킹 식별자와 매핑해야 합니다.

주의: 이 메서드를 Singular SDK 초기화 직후 혹은 커스텀 유저 ID를 사용할 수 있는 가장 빠른 시점에 호출하세요.

setDeviceCustomUserId 메서드
정의	로그인과 동일하게 커스텀 유저 ID를 설정하고 Singular의 웹 트래킹 ID와 매핑
메서드	singularSdk.setDeviceCustomUserId(userId)
사용예	`// 커스텀 유저 ID를 설정하고 Singular의 웹 트래킹 ID와 매핑 singularSdk.setDeviceCustomUserId(customUserId);`

Singular Website SDK 네이티브 연동

소개