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 준비 사항
-
build.gradle 파일 내의 Maven repositories에 다음 내용을 추가하세요.
maven { url 'https://maven.singular.net/' }
-
앱의 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" />
- 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를 초기화 |
사용 예시 |
|
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.unsetCustomUserId 메서드 |
|
정의 | Singular로 전송된 유저 ID를 해제 |
사용예 |
|
앱 추적 투명성 동의(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);
연동 가이드 |