React Native SDK 기본 연동

Singular React Native SDK
다운로드 Singular React Native SDK 버전 3.1.15 (체인지 로그 참고)
호환성 React Native 0.46.4+
샘플 앱

샘플 앱은 Singular SDK가 완전히 연동된 앱입니다. 코드를 참고하여 베스트 프랙티스를 통해 여러 연동 파트들이 어떻게 결합되는지 확인하세요.  

연동 가이드

 

프로젝트에 SDK 추가

Singular React SDK를 프로젝트에 추가하려면 다음 단계를 따르세요.

  • 프로젝트의 루트 디렉터리에서 터미널을 엽니다.
  • 다음 명령어로 프로젝트에 SDK 패키지를 다운로드합니다.

    npm install singular-react-native --save
  • React Native 0.60 이상인 경우 Singular 패키지가 자동으로 프로젝트에 링크됩니다.
    React Native 0.59 이하인 경우 다음 명령어를 실행해서 Singular 패키지에서 프로젝트로 네이티브 브리지 코드를 링크하세요.
    react-native link singular-react-native

준비 사항 설정

iOS 준비 사항

프로젝트의 루트 디렉터리에서 다음 명령어를 실행하세요.

cd ios; pod install

Android 준비 사항

  1. build.gradle 파일 내의 Maven repositories에 다음 내용을 추가하세요.

    maven { url 'https://maven.singular.net/' }
  2. 앱의 AndroidManifest.xml 파일에 다음 권한을 추가하세요.

    <uses-permission android:name="android.permission.INTERNET" />
     <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
     <!--  This permission is needed for Singular to retrieve Google Play Referrer data  -->
     <uses-permission android:name="com.google.android.finsky.permission.BIND_GET_INSTALL_REFERRER_SERVICE" />
     <!--  This permission is needed for Singular to retrieve data from the google licensing API  -->
     <uses-permission android:name="com.android.vending.CHECK_LICENSE" />

    앱 빌드가 Android 12/API 레벨 31 이상을 타깃한다면, Google Advertising ID에 접근할 수 있도록 권한을 추가하세요.

    <uses-permission android:name="com.google.android.gms.permission.AD_ID" />
  3. Singular SDK에서 전의 의존성(transitive dependencies)을 비활성화했다면, 앱의 build.gradle에 다음을 추가하세요.
    implementation 'com.android.installreferrer:installreferrer:2.2'
    implementation 'com.google.android.gms:play-services-appset:16.0.0'

SDK 초기화

주의: Singular SDK를 구현할 때 GDPR, CCPA, COPPA뿐만 아니라 비즈니스를 하는 지역에 적용되는 여러 프라이버시 정책을 준수하세요. 상세 정보는, SDK Opt-In과 Opt-Out Practices를 참조하세요. 

SDK 초기화 코드는 앱이 열릴 때마다 호출돼야 합니다. 이는 Singular의 어트리뷰션 기능이 동작하기 위한 전제 조건이자, Singular에 새 세션을 보내서 유저 리텐션을 계산하는 기준으로 사용됩니다.

필요 클래스 임포트

App.js 파일 내에 다음 코드를 추가해서 Singular와 SingularConfig 클래스를 임포트합니다.

import {Singular, SingularConfig, Events, Attributes} from 'singular-react-native';

SDK 설정 및 초기화

SingularConfig 오브젝트는 Singular SDK를 초기화하기 전에 생성해야 합니다. 이 오브젝트는  Singular SDK를 위한 고객사의 SDK key SDK secret을 포함합니다. (이는 Singular 계정으로 로그인하여 Developer Tools > SDK Keys 로 이동하면 가져올 수 있습니다)

선택 사항으로, 여러 SDK 기능들을 활성화하도록 설정을 추가할 수 있습니다.

다음으로 아래 예제처럼 init 메서드를 사용해서 SingularConfig를 넘기면서 SDK를 초기화합니다.

const config = new SingularConfig('<SDK KEY>', '<SDK SECRET>');

// Optional settings
config.withCustomUserId("johndoe@email.com"); // Set user ID
config.withSingularLinks(callBackFunction); // Enable deep linking

Singular.init(config);
Singular.init 메서드
정의 Singular SDK를 초기화
사용 예시
Singular.init(config);

SingularConfig Options

".with" Method 정의
withCustomUserId(user_id) Singular에 유저 ID 전송 (더 알아보기)
withSingularLinks(callBackFunction) 딥링크 활성화 (더 알아보기)
withSessionTimeoutInSec(seconds) 세션 타임아웃 수정 (더 알아보기)

선택 사항: 유저 ID 설정

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

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

유저 ID는 두 가지 방법 중 하나를 택하여 Singular로 전송할 수 있습니다.

  • 권장 사항: 앱이 실행되는 시점에 유저 ID를 파악할 수 있는 경우 SDK 초기화 전에 SingularConfig에 유저 ID를 설정하세요. 이 경우 최초의 세션부터 유저 ID를 Singular에 보낼 수 있습니다.

    const config = new SingularConfig("<SDK KEY>", "<SDK SECRET>")
        .withCustomUserId("custom_user_id");
    Singular.init(config);
  • 또는 실행 중 언제든지 setCustomUserId 메서드를 호출할 수 있습니다.

일반적으로 유저가 서비스에 로그인하는 시점에 setCustomUserId를 호출하고 유저 로그아웃 시점에 unsetCustomUserId를 사용하는 경우가 많습니다.

주의: 유저 ID는 unsetCustomUserId 호출을 통해 설정을 해제하거나 앱이 삭제되기 전까지 유지됩니다. 앱을 닫거나 재시작하는 것으로는 유저 ID 설정이 해제되지 않습니다.

Singular.setCustomUserId 메서드
정의 Singular에 유저 ID 전송
사용예
Singular.setCustomUserId("custom_user_id");
Singular.unsetCustomUserId 메서드
정의 Singular로 전송된 유저 ID를 해제
사용예
Singular.unsetCustomUserId();

앱 추적 투명성 동의(ATT Consent) 처리

iOS 14.5부로, 유저 기기의 IDFA를 추적하기 전 유저로부터 IDFA 접근에 대한 동의를 구해야합니다. (ATTrackingManager를 사용)

유저에게 동의를 구하기 전에 Singular SDK를 초기화하려면, 유저 동의에 대기하도록 특정 시간 간격을 지정하여 SDK가 IDFA없이 이벤트 발생시키지 않도록 지연시키세요.  

이 설정을 적용하려면, 다음 예시와 같이 waitForTrackingAuthorizationWithTimeoutInterval 옵션을 사용하여 Singular SDK를 초기화하세요. 

const config = new SingularConfig('<SDK KEY>', '<SDK SECRET>');

// Enable SKAdNetwork
config.withSkAdNetworkEnabled(true);

// Wait 5m for tracking authorization before sending any events
config.withWaitForTrackingAuthorizationWithTimeoutInterval(300);

Singular.init(config);