Singular SDK는 Cordova용 플러그인으로 사용할 수 있습니다. 아래 지침 는 Singular를 Cordova 앱에 연동하는 방법을 보여줍니다.

전제 조건

• 이 문서에서는 제대로 작동하는 Cordova 앱이 있다고 가정합니다.
• SDK를 초기화하려면 Singular SDK 키와 SDK 시크릿이 필요합니다. Singular 플랫폼의 "개발자 도구 > SDK 연동 > SDK 키"에서 얻을 수 있습니다.

Singular 플러그인 추가하기

코드바 프로젝트에 Singular 플러그인을 추가하려면 다음을 실행하세요:

cordova plugin add singular_cordova_sdk

Ionic

Ionic을 사용하는 경우

1. Singular SDK 플러그인을 설치합니다:

   $ ionic cordova plugin add singular_cordova_sdk

2. 메인 ts 파일에서 창 변수를 선언합니다:

   declare var cordova;

3. 이제 Cordova에서 바로 Singular 플러그인을 사용할 수 있습니다:

   import {Component} from '@angular/core';
     import {Platform} from '@ionic/angular';
     declare var cordova;
     ...
     
     export class HomePage {
     constructor(public platform: Platform) {
     this.platform.ready().then(() => {
     
         // 여기에 Singular SDK를 초기화하는 코드를 추가하세요.
   
     
     }); 
     }}

SDK 초기화하기(필수)

앱을 열 때마다 Singular SDK 초기화 코드를 호출해야 합니다. 이는 모든 Singular 어트리뷰션 기능의 전제 조건입니다. 또한 새 사용자 세션을 Singular로 전송합니다(세션은 사용자 리텐션을 계산하는 데사용됩니다).

Singular SDK를 초기화하려면 다음과 같이 하세요:

1. SingularConfig 객체를 생성합니다. 이 객체에는 Singular SDK 키와 시크릿이 포함됩니다.
2. 앱이 딥링크 및/또는 SKAdNetwork를 지원하도록 하려면 선택적 설정을 구성합니다(아래 딥링킹 지원 추가하기 및 SKAdNetwork 지원 추가하기 참조).
3. 메타 인스톨 리퍼러 어트리뷰션 지원

   '메타 인스톨 리퍼러' 어트리뷰션을 활성화하는 데 필요한 SDK 구성입니다:

   1. Singular 구성 개체에서 페이스북 앱 ID를 입력합니다.
      

      // META 설치 리퍼러를 활성화하려면
      
      singularConfig.withFacebookAppId("여기에 Facebook 앱 ID를 입력하세요.");

   앱의 Facebook 앱 ID는 어디에서 찾을 수있나요?
4. SingularConfig 객체를 사용하여 SDK를 초기화합니다.

코드 예시(선택적 설정은 주석 처리됨):

// 구성 개체 만들기

  var singularConfig = new
  cordova.plugins.SingularCordovaSdk.SingularConfig("<SDK KEY>", "<SDK SECRET>");
  
  /*
  // 선택 사항: 딥 링크 활성화(추가 설정 단계 필요, 가이드 참조)

  var linkHandler = function(data){
  var deeplink = data.deeplink;
  var passthrough = data.passthrough;
  var isDeferred = data.isDeferred;
  // 여기에 링크 처리 로직을 추가하세요.

  }
  singularConfig.withSingularLink(linkHandler);
  */
  /*
  
  // META 설치 리퍼러를 활성화하려면

  singularConfig.withFacebookAppId("여기에 Facebook 앱 ID를 입력하세요.");
  */
  
  /*
  // 선택 사항: SKAdNetwork 활성화(관리 모드에서 추가 옵션은 가이드 참조)

  singularConfig.withSkAdNetworkEnabled(true);
  */
  
  // Singular형 초기화

  cordova.plugins.SingularCordovaSdk.init(singularConfig);

사용자 ID를 Singular로 보내기(선택 사항)

Singular SDK 메서드를 사용하여 내부 사용자 ID를 Singular로 보낼 수 있습니다.

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

사용자 ID를 설정하려면 setCustomUserId 메서드를 사용합니다. 설정을 해제하려면(예: 사용자가 계정에서 '로그아웃'하는 경우) unsetCustomUserId 으로 전화하세요.

앱이 열릴 때 사용자 ID를 이미 알고 있는 경우 Singular SDK를 초기화하기 전에 setCustomUserId 으로 전화하세요. 이렇게 하면 Singular가 첫 번째 세션부터 사용자 ID를 가질 수 있습니다. 그러나 일반적으로 사용자가 등록하거나 로그인을 수행할 때까지 사용자 ID를 사용할 수 없습니다. 이 경우 등록 절차가 완료된 후 setCustomUserId 으로 전화하세요.

SingularCordovaSdk.setCustomUserId('CustomUserId');

SingularCordovaSdk.unsetCustomUserId();

SingularCordovaSdk.setDeviceCustomUserId('CustomUserId');

이벤트 추적(비구매)

SDK 초기화를 통해 사용자 세션을 Singular로 전송하는 것 외에도 사용자 이벤트를 전송할 수 있습니다. 인앱 이벤트에 대한 데이터는 Singular가 사용자 확보 캠페인의 성과를 분석하고 KPI를 측정하는 데 도움이됩니다.

예를 들어, 게임 앱에서 사용자 로그인, 등록, 튜토리얼 완료 또는 레벨 업에 대한 데이터를 수집하고 싶을 수 있습니다.

Singular로 이벤트를 보내려면 eventWithArgs 메서드를 사용합니다. 이벤트에 이름을 지정하고 추적할 속성을 추가합니다.

// 예: 이벤트 속성이 있는 제품 보기라는 이벤트 보고

  cordova.plugins.SingularCordovaSdk.eventWithArgs(
    'ViewProduct', // 이벤트 이름

    {
      // 이벤트 속성

      productID:"123",
      productCategory:"Outerwear"
    }
  )

구매 추적

앱이 인앱 구매를 통해 얼마나 많은 구매을 창출했는지 Singular가 추적할 수 있도록 하려면, IAP 이벤트를 Singular에 보고하세요.

이벤트 어트리뷰트로 eventWithArgs 메서드를 사용하여 IAP 객체를 전달할 것을 권장합니다. Singular는 IAP 객체를 사용하여 구매의 유효성을 검사하고 사기성 구매를 감지하여 구매 지표가 왜곡되지 않도록 합니다( 인앱 구매 유효성 검사 FAQ 참조).

https://github.com/j3k0/cordova-plugin-purchase 라이브러리를사용하는 경우 다음 코드를 사용할 수 있습니다:

store.when('product123 verified', onProductVerified);
  product.verify();
  
  function onProductVerified(product){
    const iap = new cordova.plugins.SingularCordovaSdk.SingularIAP(product);
    cordova.plugins.SingularCordovaSdk.eventWithArgs('IAP_EVENT', iap)
  }

cordova.plugins.SingularCordovaSdk.customRevenue(
    customEventName, // 예 "purchase"

    currencyCode, // 예 "USD"

    purchaseAmount // 예 3.2

  );

하이브리드 이벤트 추적(고급)

Singular는 앱에 연동된 Singular SDK를 통해 모든 이벤트와 구매을 전송할 것을 권장합니다. 그러나 Singular는 다른 소스에서 이벤트와 구매을 수집할 수 있습니다.

Singular SDK에서 전송되지 않은 모든 이벤트는 Singular의 서버 간 이벤트 문서 요구사항을준수해야 하며, 이벤트의 정확한 어트리뷰션을 위해 일치하는 기기 식별자를 제공해야 합니다.

하이브리드 이벤트 추적 가이드

광고 구매 어트리뷰션 추적

딥링킹 지원 추가

딥링크는 사용자의 휴대폰에서 앱을 열어 앱의 기본 위젯이 아닌 특정 페이지나 사용자 경험으로 사용자를 직접 보내는 링크입니다.

딥링크는 일반적으로 휴대폰에 이미 앱이 설치되어 있지만 한동안 앱을 사용하지 않은 사용자를 대상으로 하는 리타게팅 캠페인에 사용됩니다.

Singular는 Singular 링크를 통한 딥링크를 지원합니다(Singular 링크 FAQ 참조).

앱에서 Singular 링크를 사용하려면 다음과 같이 하세요:

1. Singular 링크 전제 조건의 지침을 따릅니다.

2. Android의 경우 이 코드를 기본 활동에 추가합니다:

   import singular_cordova_sdk.SingularCordovaSdk;
     
     @Override
     public void onNewIntent(Intent intent) {
       SingularCordovaSdk.handleNewIntent(intent);
     }

   iOS의 경우, 이 코드를 앱 델리게이트에 추가합니다:

   #import "SingularCordovaSdk.h"
     
       - (BOOL)application:(UIApplication*)application
       didFinishLaunchingWithOptions:(NSDictionary*)launchOptions
       {
          self.viewController = [[MainViewController alloc] init];
          [SingularCordovaSdk setLaunchOptions: launchOptions];
          return [super
       application:application didFinishLaunchingWithOptions:launchOptions];
       }
     
       - (BOOL)application:(UIApplication *)application
       continueUserActivity:(NSUserActivity *)userActivity
       restorationHandler:(void (^)(NSArray<id> * _Nullable))restorationHandler{
        [SingularCordovaSdk startSessionWithUserActivity:userActivity];
        return
       YES;
       }

3. 코드에서 Singular SDK를 초기화하기 전에, Singular 구성 개체에 .withSingularLink를 추가하고 링크 핸들러 함수를 지정하세요:

   var singularConfig = new
       cordova.plugins.SingularCordovaSdk.SingularConfig("<SDK KEY>", "<SDK SECRET>");
     
     var linkHandler = function(data){
       var deeplink = data.deeplink;
       var passthrough = data.passthrough;
       var isDeferred = data.isDeferred;
       // 여기에 링크 처리 로직을 추가하세요.
   
     }
     
     singularConfig.withSingularLink(linkHandler);
     
     cordova.plugins.SingularCordovaSdk.init(singularConfig);

SKAdNetwork 지원 추가하기

Singular 플러그인은 SKAdNetwork 프레임워크를 지원합니다. 아래 구성 옵션을 사용하여 앱에 대한 SKAdNetwork 추적을 활성화할 수 있습니다.

관리 모드 (권장)

관리 모드에서는 Singular 플랫폼에서 설정할 수 있는 전환 모델에 따라, Singular가 자동으로 SKAdNetwork 전환 값을 관리합니다.

자세한 내용은 Singular의 전환 가치 관리 이해및 SKAdNetwork 모델 구성 FAQ를 참조하세요. Singular와 함께 SKAdNetwork를 사용하는 단계별 가이드는 SKAdNetwork 시작하기 방법을 참조하세요.

관리 모드에서 SKAdNetwork를 활성화하려면 다음 코드를 사용합니다:

var singularConfig = new
    cordova.plugins.SingularCordovaSdk.SingularConfig("<SDK KEY>", "<SDK SECRET>");
  
  // SKAdNetwork 활성화(기본적으로 관리 모드)

  singularConfig.withSkAdNetworkEnabled(true);
  
  cordova.plugins.SingularCordovaSdk.init(singularConfig);

수동 모드

이미 자체 전략과 도구로 SKAdNetwork 전환 가치를 관리하고 있는 경우, 수동 모드에서 SKAdNetwork를 사용할 수 있습니다.

수동 모드에서 SKAdNetwork를 활성화하려면 다음 코드를 사용합니다:

var singularConfig = new
    cordova.plugins.SingularCordovaSdk.SingularConfig("<SDK KEY>", "<SDK SECRET>");
  
  // SKAdNetwork 활성화

  singularConfig.withSkAdNetworkEnabled(true);
  
  // SKAdNetwork 수동 모드 선택

  singularConfig.withManualSkanConversionManagement();
  
  // 선택사항: 전환 가치의 변경사항을 추적하는 핸들러 정의

  var conversionHandler = function(updatedConversionValue){
    // updateConversionValue로 작업 수행

  }
  
  singularConfig.withConversionValueUpdatedHandler(conversionHandler);
  
  // Singular SDK 초기화

  cordova.plugins.SingularCordovaSdk.init(singularConfig);

전환 값을 업데이트하려면 다음 코드를 사용합니다:

cordova.plugins.SingularCordovaSdk.skanUpdateConversionValue(
    newConversionValue,
    function(isSuccess){
      // isSuccess == 업데이트가 성공한 경우 true

    }
  )

현재 전환 값을 검색하려면 다음 코드를 사용합니다:

cordova.plugins.SingularCordovaSdk.skanGetConversionValue(
    function(conversionValue){
      // ConversionValue로 작업 수행

    }
  )

기타 옵션

추적 제거

Singular가 앱 제거를 추적하도록 하려면, 다음 코드를 사용하여 APNS/FCM 토큰을 Singular로 전송하세요:

안드로이드

cordova.plugins.SingularCordovaSdk.setUninstallToken(fcmToken)

iOS:

cordova.plugins.SingularCordovaSdk.setUninstallToken(apnsToken)

짧은 리퍼러 링크 생성

짧은 링크를 사용하면 매개변수로 가득 찬 긴 Singular 링크를 공유하기에 편리한 더 짧고 안전한 링크로 변환할수 있습니다.

일반적으로 앱 사용자가 친구와 공유하여 앱을 사용하도록 초대할 수 있도록 짧은 링크를 동적으로 생성하는 것이 좋습니다.

짧은 링크를 만들려면 다음이 필요합니다:

• 앱 다운로드로 연결되는 Singular 링크 ( Singular 링크 FAQ 참조).
• 링크에 동적으로 추가하려는 모든 매개변수 (옵션 목록은 링크 매개변수 추적참조).
• 링크를 공유한 사용자의 새 앱 설치를 추적할 수 있도록 하려는 경우 추천 사용자의 이름과 ID.

짧은 링크를 만들려면 다음 코드를 사용합니다:

cordova.plugins.SingularCordovaSdk.createReferrerShortLink(
      longLinkURL, 
      referrerName,
      referrerID,
      {
          // 짧은 링크에 추가할 추적 링크 매개변수(예: "channel":"sms"

          param1: value1,
          param2: value2,
          ...
      },
      {
          onSuccess: function (shortLinkURL) {
          // shortLinkURL로 작업하기

          },
          onError: function (error) {
          // 오류 처리

          }
      }
  )

데이터 개인정보 보호법 준수

Singular는 개인정보 보호 기능을 제공하여 GDPR 및 CCPA(캘리포니아 소비자 개인정보 보호법)와 같은 소비자 개인정보 보호법을 준수하는 파트너와 협력할 수 있도록 지원합니다. 이러한 파트너는 최종 사용자가 개인 정보 공유에 동의했는지 여부를 알림을 받기를 원합니다.

사용자에게 정보 공유에 대한 동의를 요청하는 방법을 구현한 경우, limitDataSharing 메서드를 사용하여 사용자의 선택 사항을 Singular에 알려주세요:

사용자가 정보 공유에 동의(옵트인)했음을 표시하려면 SingularCordovaSdk.limitDataSharing(false )를 사용하세요.

사용자가 동의하지 않은 경우 SingularCordovaSdk.limitDataSharing(true)를 사용합니다.

Singular는"사용자 개인정보 포스트백"에서 제한데이터공유를 사용할 뿐만 아니라 관련 규정을 준수하기 위해 이 정보를 필요로 하는 파트너에게 전달합니다. 자세한 내용은"사용자 개인정보 및 데이터 공유 제한"을 참조하세요.

// 사용자가 데이터 공유에 동의했습니다.

cordova.plugins.SingularCordovaSdk.limitDataSharing(false);

GDPR 준수를 위한 추가 방법

Singular SDK는 GDPR 정책을 준수하고 추적에 대한 사용자 동의 또는 비동의를 Singular에 알리는 데 도움이 되는 몇 가지 방법을 제공합니다.

cordova.plugins.SingularCordovaSdk.trackingOptIn();

cordova.plugins.SingularCordovaSdk.stopAllTracking();

cordova.plugins.SingularCordovaSdk.resumeAllTracking();

cordova.plugins.SingularCordovaSdk.isAllTrackingStopped();