Singular Website SDK: 네이티브 방식 통합

팔로우
Avatar
Jared Ornstead
Updated

 

단일 웹사이트 SDK는 기업용 기능입니다. 이 기능을 사용하는 데 관심이 있는 경우 고객 성공 관리자에게 문의하세요.

Singular 웹사이트 SDK를 사용하면 웹사이트 활동을 마케팅 터치포인트에 어트리뷰션하고 웹사이트 내에서 사용자 이벤트를 추적할 수 있습니다. 또한 싱귤러의 크로스 디바이스 어트리뷰션 솔루션의 핵심 구성 요소로, 사용자 여정을 분석하고 크로스 플랫폼 LTV 및 ROAS를 계산할 수있게 해줍니다.

자세한 내용은 크로스 디바이스 어트리뷰션 FAQ와 웹 어트리뷰션 FAQ를 참조하세요.

여기에 설명된 네이티브 자바스크립트 버전 외에도, 싱글 웹사이트 SDK는 구글 태그 관리자 템플릿으로도 사용할 수 있습니다.

브라우저 호환성:

Chrome: 15+ Edge: 15+ 인터넷 익스플로러 10+
Safari: 5.1+ Firefox: 6+ Opera: 15+

사이트에 SDK 스크립트 추가하기

다음 방법 중 하나를 사용하여 웹사이트 또는 웹 앱에서 SDK를 설정하세요.

Singular의 CDN에서 스크립트에 연결하기

이 방법에서는 싱귤러가 싱귤러의 CDN에서 SDK 자바스크립트 코드를 호스팅합니다.

추적하려는 각 페이지의 <head> 태그 안에 다음 코드를 추가합니다:

  <head>
      <!-- 최신 SDK 버전 사용 -->
      <script src="https://web-sdk-cdn.singular.net/singular-sdk/latest/singular-sdk.js">
      </script>
  </head>

참고: 위의 코드는 최신 버전의 SDK로 연결됩니다. 특정 버전의 SDK를 사용하려면 다음 코드를 대신 사용하세요:

  <head>
      <!-- 고정 SDK 버전 사용 -->
      <script src="https://web-sdk-cdn.singular.net/singular-sdk/1.4.2/singular-sdk.js">
      </script>
  </head>

NPM을 사용하여 설정

  1. 프로젝트의 루트 디렉터리에서 npm i singular-sdk를 실행하거나 "singular-sdk "를 추가합니다: "^1.4.1 "를 package.json 파일의 의존성 섹션에 추가한 다음 npm 설치를 실행합니다.
  2. SDK를 사용하려는 스크립트에 다음 코드를 추가합니다.
import {singularSdk, SingularConfig} from "singular-sdk";

SDK 초기화

SDK 초기화 코드는 페이지가 로드될 때마다 호출되어야 합니다. 이는 모든 싱글 어트리뷰션 기능의 전제 조건이며, 또한다음과 같은 기능을 수행합니다:

  • 사용자가 새 광고 데이터를 가지고 사이트에 들어올 때 또는 세션 시간 제한이 지났을 때 새 사용자 세션을 생성합니다.
  • 새로운 '페이지 방문' 이벤트를 싱귤러로 전송합니다.

페이지 방문 이벤트와 사용자 세션은 사용자 리텐션을 계산하고 리인게이지먼트 어트리뷰션을 활성화하는 데 사용됩니다.

1. 싱귤러 컨피그 객체 생성

SDK를 초기화하기 전에 SingularConfig 객체를 생성해야 합니다. 이 객체에는 다음이 포함됩니다:

  • SDK 키 및 SDK 시크릿: 이를 찾으려면 Singular 계정에 로그인하여 "개발자 도구 > SDK 통합 > SDK 키"로 이동하세요.
  • 제품 ID: 웹사이트의 이름입니다. 기본 웹 도메인의 역방향 DNS 표기법(예: "com.example")을 사용하는 것이 좋습니다. 이는 싱귤러 플랫폼 전체에서 귀하의 웹사이트를 식별하는 데 사용됩니다. 이 값은 싱귤러 플랫폼의 앱 페이지에 있는 앱 번들ID와도 일치해야 합니다.
  • 선택 사항으로 SDK 환경설정을 설정할 수 있습니다(자세한 내용은 계속 읽기).

기본 SingularConfig 객체를 만들려면 이 코드를 사용합니다:

  const config = new SingularConfig(sdkKey, sdkSecret, productId);

그러나 Singular에서 제공하는 다양한 기능을 활성화하기 위해 설정을 추가하고 싶을 수도 있습니다.

설정을 추가하려면 SingularConfig 객체의 '.with' 메서드를 사용합니다. 예를 들면 다음과 같습니다:

  // 사용자 ID를 Singular에 전달하도록 SDK를 구성합니다.
  const config = new SingularConfig(sdkKey, sdkSecret, productId)
      .withCustomUserId(userId);

SingularConfig 메서드 참조

다음은 사용 가능한 모든 '.with' 메서드입니다.

메서드 설명 자세히보기
.withCustomUserId(customId) 사용자 ID를 단수로 보내기 사용자 ID 설정
.withProductName(productName) 제품의 선택적 표시 이름  
.withLogLevel(logLevel) 로깅 수준 구성: 0 - 없음(기본값), 1 - 경고, 2 - 정보, 3 - 디버그.  
.withSessionTimeoutInMinutes(timeout) 세션 타임아웃을 분 단위로 설정합니다(기본값: 30분).

 
.withAutoPersistentSingularDeviceId (domain) 자동 교차 하위 도메인 추적 사용 쿠키를 사용한 자동지속

.withPersistentSingularDeviceId (singularDeviceId)

 수동 교차 하위 도메인 추적 사용 단일 디바이스 ID 수동 설정
.withInitFinishedCallback(callback) SDK 초기화가 완료되면 콜백을 호출합니다. 초기화가 완료되면 콜백 함수 호출하기

2. Singular 초기화하기

SingularConfig 객체를 생성한 후, 구성 객체를 전달하여 init 메서드를 사용하여 Singular를 초기화합니다.

init 메서드는 코드의 어느 지점에서나 호출할 수 있지만 이벤트가 보고되기 전에 호출되어야 합니다. 추적하려는 각 페이지가 로드되는 동안 init을 호출하는 것이 좋습니다.

init 메서드
설명 SingularConfig 객체에 설정된 구성 옵션으로 SDK를 초기화합니다.
시그니처 init(config)
사용 예시 
  function initSingular() {
      const config = new SingularConfig(sdkKey, 
        sdkSecret, productId);
      singularSdk.init(config);
  }

중요: 단일 페이지 애플리케이션(SPA)의 경우, 다른 페이지로 라우팅할 때마다 singularSdk.pageVisit()을 호출하세요. singularSdk.init이 이미 페이지 방문을 보고하므로 로드되는 첫 번째 페이지에서는 singularSdk. pageVisit( )을 호출하지 마세요.

초기화가 완료되면 콜백 함수 호출하기

초기화가 완료되면 콜백 함수가 호출되도록 설정하려면 SingularConfig 객체에서 . withInitFinishedCallback(callback) 을 사용하면 됩니다.

withInitFinishedCallback 메서드
설명 초기화 프로세스가 완료되면 호출될 콜백을 설정합니다.
시그니처 withInitFinishedCallback(callback)
사용 예시 
  function initSingular() {      
    const config = new SingularConfig(sdkKey, sdkSecret, productId)
      .withInitFinishedCallback(initParams=> {
        // 이 콜백은 init 메서드가 완료되면 호출됩니다.
  
        // 디바이스 ID(SDID)를 검색하는 방법.
        const singularDeviceId = initParams.singularDeviceId;
      });
  singularSdk.init(config);
  }

싱귤러에 사용자 ID 보내기(선택 사항)

싱귤러 SDK 방법을 사용하여 내부 사용자 ID를 싱귤러에 전송할 수 있습니다.

참고: 싱귤러의 크로스 디바이스 솔루션을 사용하는 경우, 모든 플랫폼에서 사용자 ID를 수집해야 합니다.

  • 사용자 ID는 모든 식별자가 될 수 있으며 PII(개인 식별 정보)를 노출해서는 안 됩니다. 예를 들어 사용자의 이메일 주소, 사용자 이름 또는 전화번호를 사용해서는 안 됩니다. 싱귤러는 퍼스트 파티 데이터에만 고유한 해시값을 사용할 것을 권장합니다.
  • 또한 Singular에 전달되는 사용자 ID 값은 모든 플랫폼(웹/모바일/PC/콘솔/오프라인)에서 캡처한 내부 사용자 ID와 동일해야 합니다.
  • Singular는 사용자 수준 내보내기, ETL 및 내부 BI 포스트백(구성된 경우)에 사용자 ID를 포함합니다. 사용자 ID는 퍼스트 파티 데이터이며, Singular는 이를 다른 당사자와 공유하지 않습니다.
  • 싱귤러 SDK 메서드로 설정한 사용자 ID 값은 logout() 메서드를 사용하여 설정 해제하거나 브라우저 로컬 저장소가 삭제될 때까지 유지됩니다. 웹사이트를 닫거나 새로고침해도 사용자 ID는 설정이 해제되지 않습니다.
  • 비공개/시크릿 모드에서는 브라우저를 닫으면 로컬 저장소가 자동으로 삭제되므로 SDK가 사용자 ID를 유지할 수 없습니다.

사용자 ID를 설정하려면 login() 방법을 사용합니다. 설정을 해제하려면(예: 사용자가 계정에서 '로그아웃'하는 경우) logout() 메서드를 호출하세요.

참고: 여러 사용자가 하나의 디바이스를 사용하는 경우 로그인 및 로그아웃할 때마다 사용자 ID를 설정하고 설정 해제하는 로그아웃 플로우를 구현하는 것이 좋습니다.

웹사이트에서 Singular SDK를 초기화할 때 사용자 ID를 이미 알고 있는 경우 구성 개체에서 사용자 ID를 설정하세요. 이렇게 하면 Singular가 첫 번째 세션의 사용자 ID를 가질 수 있습니다. 그러나 일반적으로 사용자가 등록하거나 로그인을 수행할 때까지 사용자 ID를 사용할 수 없습니다. 이 경우 등록 흐름이 완료된 후 login() 을 호출하세요.

SingularSDK login() 메서드
설명 싱귤러에 사용자 ID를 전송합니다.
서명 login(customUserId)
사용 예시 
singularSdk.login("custom_user_id");
SingularSDK 로그아웃() 메서드
설명 싱귤러로 전송된 사용자 ID를 설정 해제합니다.
서명 로그아웃()
사용 예시 
singularSdk.logout();

선택 사항입니다: 사용자 지정 사용자 ID 장치 매핑

중요: 이 고급 엔터프라이즈 기능은 예외적인 경우에만 사용할 수 있습니다.이 기능을 구현하기 전에 싱귤러의 솔루션 엔지니어와 상담하세요.

싱귤러는 서버 간 연동을 통해 추가 모바일 이벤트 추적 데이터를 수신할 수 있습니다. 이 기능을 활용하려면 사용자 ID를 Singular의 모바일 디바이스 추적 식별자에 매핑해야 합니다.

참고: 이 메서드는 싱귤러 SDK를 초기화한 후 또는 사용자 ID를 확보한 후 가능한 한 빨리 호출하세요.

싱귤러 SDK 설정 디바이스 커스텀 유저 아이디 메서드
설명 사용자 지정 사용자 ID를 로그인과 동일하게 설정하고 이를 싱귤러의 추적 식별자에 매핑합니다.
서명 singularSdk.setDeviceCustomUserId(userId)
사용 예시 
singularSdk.setDeviceCustomUserId("customUserId");

선택 사항입니다: 이벤트 및 수익 추적

이벤트 추적(비수익)

싱귤러는 사이트 내 사용자 이벤트에 대한 데이터를 수집하여 캠페인의 성과를 분석하고 KPI를 측정할 수 있습니다. 예를 들어, 조직에서 사용자 로그인, 등록 또는 튜토리얼 완료에 대한 데이터를 수집하고자 할 수 있습니다.

이벤트 메서드를 사용하여 싱귤러에 이벤트를 보낼 수 있습니다.

참고:

  • 타사 파트너 및 분석 솔루션을 사용하려는 경우 타사 파트너 및 분석 솔루션과의 호환성을 보장하기 위해 이벤트 이름과 속성을 영어로 전달할 것을 적극 권장합니다.
  • 이벤트 이름은 32자로 제한됩니다. ASCII가 아닌 문자로 된 문자열은 UTF-8로 변환한 후 32바이트 미만이어야 합니다.
  • 속성 및 값은 500 ASCII 문자로 제한됩니다.
이벤트 메서드
설명 추가 정보를 포함하거나 포함하지 않고 사용자 이벤트를 Singular에 보고합니다.
시그니처

singularSdk.event(eventName, args)

참고: 'args'는 키-값 쌍을 가진 자바스크립트 객체입니다. 추가 인수를 전달하지 않으려면 이벤트 이름만 사용하여 이벤트 메서드를 호출하세요.
사용 예시 
  // 인수 없이 등록 완료 이벤트 보내기
  singularSdk.event("Registration_Completed");

  // 추가 속성과 함께 "등록 완료"라는 이벤트를 보냅니다.
  singularSdk.event("Registration_Completed",
  {key1: 'value1',
  key2: 'value2'});

수익 추적

싱귤러는 웹사이트를 통해 얻은 수익에 대한 데이터를 수집하여 캠페인의 성과와 ROI를 분석하는 데 도움을 줄 수 있습니다. 싱귤러는 보고서, 로그 내보내기 및 포스트백에서 데이터를 사용할 수 있도록 합니다.

수익 방식을 사용하여 이벤트를 보고합니다. 수익 방식을 사용하면 사용자 지정 이벤트 이름을 전달할 수 있으므로 Singular 보고서에서 다양한 유형의 수익 이벤트에 따라 분류된 수익을 볼 수 있습니다.

참고: 다른 통화로 보고된 모든 수익은 단수 계정에 설정된 대로 조직의 기본 통화로 자동 변환됩니다.

수익 방법
설명 선택적 추가 정보와 함께 수익 이벤트를 Singular로 전송합니다.
서명

singularSdk.revenue(eventName, 통화, 금액, args)

참고:

  • 통화는 "USD", "EUR", "INR"과 같은 세 글자로 된 ISO 4217 통화 코드로 전달하세요.
  • 금액 값은 십진수 값으로 전달할 수 있습니다.
사용 예 
  // 싱귤러에 수익 이벤트 보내기 
  singularSdk.revenue("Item_Purchased","USD", 5.50);

  // 추가 인수를 사용하여 Singular에 수익 이벤트 보내기
  singularSdk.revenue("Item_Purchased","USD", 5.50,
  {key1: 'value1',
   key2: 'value2');

선택 사항입니다: 교차 하위 도메인 추적

기본적으로 싱글 웹사이트 SDK는 싱글 디바이스 ID를 생성하고 브라우저 저장소를 사용하여 이를 유지합니다. 이 저장소는 하위 도메인 간에 공유할 수 없으므로 SDK는 각 하위 도메인에 대해 새 ID를 생성하게 됩니다.

하위 도메인에서 단일 장치 ID를 유지하려는 경우 다음 옵션 중 하나를 사용할 수 있습니다:

방법 A: 쿠키를 사용하여 자동 지속

사용자 지정 퍼스트 파티 쿠키를 사용하여 싱귤러 SDK가 싱귤러 디바이스 ID를 유지하도록 할 수 있습니다. 다음 방법을 사용하여 추적하려는 기본 도메인을 설정합니다.

withAutoPersistent싱귤러디바이스아이디 방법
설명 단일 디바이스 ID 자동 지속을 위한 기본 도메인을 포함한 구성 옵션으로 SDK를 초기화합니다.
서명 withAutoPersistentSingularDeviceId(도메인)
사용 예시 
  function initSingular() {
    const config = new SingularConfig(sdkKey, sdkSecret, productId)
      .withAutoPersistentSingularDeviceId(“example.com”);
    singularSdk.init(config);
  }

방법 B(고급): 단일 장치 ID 수동으로 설정

싱귤러 SDK가 자동으로 디바이스 ID를 유지하지 않도록 하려면 최상위 도메인 쿠키 또는 서버 측 쿠키를 사용하는 등 여러 도메인에서 ID를 수동으로 유지할 수 있습니다. 이 값은 이전에 Singular에서 생성한 유효한 uuid4 형식의 ID여야 합니다.

참고: init 메서드를 호출한 후 singularSdk.getSingularDeviceId()를 사용하여 Singular 디바이스 ID를 읽거나 InitFinishedCallback을 사용할 수 있습니다.

withPersistentSingularDeviceId 메서드

설명

지속하려는 단일 디바이스 ID를 포함한 구성 옵션으로 SDK를 초기화합니다.
시그니처 withPersistentSingularDeviceId(singularDeviceId)
사용 예시 
  function initSingular() {
    const config = new SingularConfig(sdkKey, sdkSecret, productId)
      .withPersistentSingularDeviceId(singularDeviceId);
    singularSdk.init(config);
  }

선택 사항입니다: 매치 ID 가져오기

중요: 이 기능은 고급 기능입니다. 구현하기 전에 싱귤러의 솔루션 엔지니어와 상담하세요.

싱귤러는 사용자별 결정론적 고유 매치 ID를 기반으로 PC 및 콘솔 플랫폼에서 서버 간 설치를 어트리뷰션할 수 있습니다. 이 기능을 활용하려면 초기화 후 싱귤러의 웹 SDK에서 매치 ID를 검색하세요.

getMatchID 메서드
설명 이 웹 세션의 고유한 매치 ID를 가져옵니다.
시그니처 singularSdk.getMatchID()
사용 예시 
  // 다른 플랫폼의 첫 번째 세션에 포함할 사용자 일치 ID를 가져옵니다.
  singularSdk.getMatchID()