[NEW] Singular Website SDK 네이티브 연동

Singular Website SDK
다운로드 Singular Website SDK version 1.1.0
브라우저 호환성
  • 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.1.0/singular-sdk.js">
    </script>
</head>

NPM으로 설정

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

SDK 초기화

SDK 초기화 코드는 페이지가 로딩될 때마다 호출돼야 합니다. 이는 모든 Singular 어트리뷰션 기능을 사용하기 위한 전제 조건이며 유저가 새로운 광고 데이터를 가지거나 세션 타임아웃이 지나고 사이트에 진입할 때 Singular에 새 페이지 방문(page visit)을 전송합니다. 이러한 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  전송 Setting the User ID
.withProductName(productName) 프로덕트 디스플레이 네임 (선택 사항)  
.withLogLevel(logLevel) 로그 레벨 설정:None = 0 - None (기본값); 1 - Warn; 2 - info; 3 - Debug  
.withSessionTimeoutInMinutes (timeout) 분 단위로 세션 타임 아웃 설정 (기본값: 30분) Auto-Persist using Cookies
.withAutoPersistentSingularDeviceId (domain) 크로스-서브도메인 트래킹 자동 활성화 쿠키를 사용한 자동 저장
.withPersistentSingularDeviceId (singularDeviceId) 크로스-서브도메인 트래킹 수동 활성화 수동으로 Singular Device 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 웹사이트 SDK는 기본적으로 Singular 디바이스 ID(SDID)를 생성하고 브라우저 스토리지에 유지합니다. 이 스토리지는 서브도메인간 공유가 불가능하여 SDK는 각 서브도메인마다 새로운 ID를 생성하도록 동작합니다.

Singular 디바이스 ID를 서브도메인간 동일하게 유지하려면 다음 옵션 중 하나를 선택하여 사용할 수 있습니다.

메서드 A: 쿠키를 사용한 자동 유지

커스텀 자사(first-party) 쿠키를 통해 Singular SDK가 Singular 디바이스 ID를 유지하도록 할 수 있습니다. 본 메서드를 사용 시 도메인에는 트래킹하려는 메인 도메인을 설정하세요.

withAutoPersistentSingularDeviceId 메서드
정의 Initialize the SDK with configuration options including the main domain for auto persisting Singular Device Id.
메서드 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 형식입니다.

주의: init 메서드나 InitFinishedCallback을 사용한 다음 singularSdk.getSingularDeviceId()를 활용하여 Singular 디바이스 ID를 읽어올 수 있습니다.

withPersistentSingularDeviceId 메서드

정의

Initialize the SDK with configuration options including the Singular Device Id you want to persist.

메서드 withPersistentSingularDeviceId(singularDeviceId)
사용예
function initSingular() {
  const config = new SingularConfig(apiKey, secretKey, productId)
    .withPersistentSingularDeviceId(singularDeviceId);
  singularSdk.init(config);
}

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

중요 사항: 이 기능은 고급 기능입니다. 연동 전 반드시 Singular의 솔루션 엔지니어와 상의해 주세요.

Singular는 추가적인 웹 트래킹 데이터를 S2S(서버-투-서버) 연동을 통해 수신할 수 있습니다. 이 기능은 Singular의 웹 트래킹 식별자로써 커스텀 유저 ID를 매핑하여 활성화됩니다.

주의: SDK 초기화 이후 커스텀 유저 ID가 식별되는 가장 빠른 시점에 이 메서드를 호출하세요.

setDeviceCustomUserId 메서드
정의 login에서 사용하는 커스텀 유저 ID를 설정해서 Singular의 웹 트래킹 식별자로 매핑합니다.
메서드

singularSdk.setDeviceCustomUserId(userId)

사용예
// 커스텀 유저 ID를 설정하고 Singular의 웹 트래킹 식별자로 매핑합니다.
singularSdk.setDeviceCustomUserId(customUserId);

 

도움이 되었습니까?