[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.0.9"`를 추가한 후 `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" 메서드를 사용할 수 있습니다. 다음 예시와 같은 형태입니다.

// Configure the SDK to pass the user ID to Singular
const config = new SingularConfig(apiKey, secretKey, productId)
    .withCustomUserId(userId);

SingularConfig 메서드 참조

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

메서드 정의 비고
.withCustomUserId(customId) Singular에 유저 ID  전송 Setting the User ID
.withProductName(productName) 프로덕트 디스플레이 네임 (선택 사항)  
.withLogLevel(logLevel) 로그 레벨 설정(기본값: Log.None) None = 0
Warn = 1
Info = 2
Debug = 3

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()을 따로 호출하지 않아야 합니다.

선택 사항: 유저 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');
도움이 되었습니까?
0명 중 0명이 도움이 되었다고 했습니다.