필수 조건

원활한 연동 과정을 위해 Singular React Native SDK를 설치하기 전에 다음 필수 단계를 완료하십시오.

설치

SDK 패키지 설치

npm을 사용하여 프로젝트에 Singular React Native SDK를 추가하십시오. 이 SDK는 iOS 및 Android용 네이티브 Singular SDK에 대한 JavaScript 바인딩을 제공합니다.

NPM을 통한 설치

1. 터미널 열기: 프로젝트의 루트 디렉터리로 이동합니다.
2. 패키지 설치: 다음 명령어를 실행하여 프로젝트에 SDK를 추가하세요:
   bash

   npm install singular-react-native --save

네이티브 모듈 연결

SDK를 연결하는 방법은 React Native 버전과 Expo 사용 여부에 따라 다릅니다.

• React Native 0.60 이상: SDK가 자동으로 연결됩니다. 별도의 단계가 필요하지 않습니다.
• React Native 0.59 이하: 네이티브 브릿지 코드를 수동으로 연결하세요:
  bash

  react-native link singular-react-native

• Expo 프로젝트: SDK를 설치한 후, 플러그인 구성에 추가하세요:
  app.json

  {
    "expo": {
      "plugins": ["singular-react-native"]
    }
  }

  그런 다음 Expo의 네이티브 코드 사용자 지정 가이드를 사용하여 앱을 다시 빌드하세요.

플랫폼 구성

iOS 설정

CocoaPods 종속성을 활성화하고 SDK가 제대로 작동하도록 iOS 전용 설정을 완료하세요.

CocoaPods 종속성 설치

프로젝트의 루트 디렉터리에서 다음 명령어를 실행하여 필요한 iOS 종속성을 설치하십시오:

cd ios && pod install

Android 구성

Singular Maven 저장소, 필요한 권한 및 종속성을 추가하도록 Android 빌드 파일을 구성하십시오.

Maven 저장소 추가

SDK 종속성 해결을 활성화하려면 프로젝트의 build.gradle 파일에 Singular Maven 저장소를 추가하세요.

allprojects {
  repositories {
    maven { url 'https://maven.singular.net/' }
  }
}

필요한 권한 추가

핵심 SDK 기능을 활성화하려면 AndroidManifest.xml 파일의 <manifest> 태그 아래에 다음 권한을 추가하세요.

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="BIND_GET_INSTALL_REFERRER_SERVICE" />
<uses-permission android:name="com.android.vending.CHECK_LICENSE" />
<uses-permission android:name="com.google.android.gms.permission.AD_ID" />

삼성 갤럭시 스토어 지원

삼성 갤럭시 스토어에서 설치 리퍼러 추적을 활성화하려면 AndroidManifest.xml 에 다음을 추가하십시오:

<queries>
   <package android:name="com.sec.android.app.samsungapps" />
</queries>

전달 의존성

Gradle 구성에서 Singular SDK에 대한 전이적 종속성을 비활성화한 경우, 다음 필수 종속성을 수동으로 추가하십시오:

dependencies {
    // Required for install referrer tracking
    implementation("com.android.installreferrer:installreferrer:2.2")

    // Required for App Set ID
    implementation("com.google.android.gms:play-services-appset:16.0.0")
}

ProGuard 구성

릴리스 APK를 빌드할 때 ProGuard(또는 R8)가 SDK 클래스를 제거하거나 난독화할 수 있습니다. Singular 기능을 유지하려면 다음 keep 규칙을 추가하십시오.

1. ProGuard 파일 찾기: 프로젝트 내 android/app/proguard-rules.pro 로 이동합니다.
2. keep 규칙 추가: 다음 규칙을 파일 끝에 추가하세요:
   proguard-rules.pro

   # Preserve Singular SDK classes
   -keep class com.singular.sdk.** { *; }
   
   # Preserve Android Install Referrer library
   -keep public class com.android.installreferrer.** { *; }
   
   # Uncomment if using Singular revenue tracking with Google Play Billing Library
   #-keep public class com.android.billingclient.** { *; }

SDK 연동

SDK 클래스 임포트

메인 애플리케이션 파일(일반적으로 App.tsx 또는 App.js)의 상단에 Singular SDK 클래스를 임포트합니다.

// Direct TurboModule API initialization (React Native 0.76+)

// Import Native API and EventEmitter
import NativeSingular from 'singular-react-native/js/NativeSingular';
import { NativeEventEmitter } from 'react-native';

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

SDK 초기화

기본 초기화

1. 인증 정보 가져오기: Singular계정에 로그인하고 Developer Tools > SDK Integration > SDKKeys 로 이동하여 SDK 키와 시크릿을 찾으십시오.
2. 구성 생성: 자격 증명을 사용하여 SingularConfig 객체 또는 TurboModule API용 일반 객체를 인스턴스화합니다.
3. 구성 추가: 선택적으로 구성 메서드를 연쇄 호출하거나 (레거시) config 객체에 속성을 직접 추가합니다 (TurboModule).
4. SDK 초기화: Singular.init() 또는 NativeSingular.init() 를 호출하여 SDK를 시작합니다.

초기화 예시

앱의 진입점(일반적으로 useEffect 훅 내부)에서 SDK를 초기화하여 앱 시작 시 한 번만 실행되도록 합니다.

// TurboModule direct API (React Native 0.76+ New Architecture)
import React, { useEffect } from 'react';
import NativeSingular from 'singular-react-native/js/NativeSingular';

export default function App() {
  useEffect(() => {
    const config: SingularConfig = {
      apikey: 'YOUR_SDK_KEY',
      secret: 'YOUR_SDK_SECRET',
      enableLogging: true,
      logLevel: 3,
    };

    NativeSingular.init(config);

  }, []);
  
  return (
    // Your app components
  );
}

import React, { useEffect } from 'react';
import Singular, { SingularConfig } from 'singular-react-native';

export default function App() {
  useEffect(() => {
    const config = new SingularConfig('YOUR_SDK_KEY', 'YOUR_SDK_SECRET')
      .withLoggingEnabled()
      .withLogLevel(3);
    
    Singular.init(config);
  }, []);
  
  return (
    // Your app components
  );
}
      

고급 구성 예시

init() 를 호출하기 전에 구성 메서드를 연쇄하여 초기화 시 여러 SDK 기능을 구성합니다.

// TurboModule direct API (React Native 0.76+ New Architecture)
import React, { useEffect } from 'react';
import NativeSingular from 'singular-react-native/js/NativeSingular';
import { NativeEventEmitter } from 'react-native';

export default function App() {
  useEffect(() => {
    const config: SingularConfig = {
      apikey: 'YOUR_SDK_KEY',
      secret: 'YOUR_SDK_SECRET',
      customUserId: 'user_123456',
      limitDataSharing: false,
      waitForTrackingAuthorizationWithTimeoutInterval: 300
    };

    NativeSingular.init(config);

    // Register event listener
    const emitter = new NativeEventEmitter(NativeSingular);
    emitter.addListener('SingularLinkHandler', (params) => {
      console.log('Singular: Deep link:', params.deeplink);
      console.log('Singular: Passthrough:', params.passthrough);
      console.log('Singular: Is deferred:', params.isDeferred);
      console.log('Singular: urlParameters:', params.urlParameters);
    });

  }, []);
  
  return (
    // Your app components
  );
}

import React, { useEffect } from 'react';
import { Singular, SingularConfig } from 'singular-react-native';

export default function App() {
  useEffect(() => {
    const config = new SingularConfig(
      'YOUR_SDK_KEY',
      'YOUR_SDK_SECRET'
    )
      // User identification
      .withCustomUserId('user_123456')

      // Privacy settings
      .withLimitDataSharing(false)

      // Deep linking
      .withSingularLink((params: SingularLinkParams) => {
        console.log('Singular: Deep link:', params.deeplink);
        console.log('Singular: Passthrough:', params.passthrough);
        console.log('Singular: Is deferred:', params.isDeferred);
        console.log('Singular: urlParameters:', params.urlParameters);
      })

      // iOS-specific
      .withWaitForTrackingAuthorizationWithTimeoutInterval(300)

      // Debugging
      .withLoggingEnabled()
      .withLogLevel(3);

    Singular.init(config);
  }, []);

  return (
    // Your app components
  );
}

고급 구성

Google Ads iOS 연동 전환 측정 필수

앱에서 iOS 14.5 이상 사용자를 대상으로 하는 Google Ads 캠페인을 실행하는 경우, iOS 연동 전환 측정(ICM)을 지원하려면 추가적인 SDK 구성 단계가 필요합니다. 여기에는 다음이 포함됩니다:

• Google의 기기 내 측정(ODM) SDK 연동
• Singular iOS SDK v12.8.1 이상으로 업데이트(Unity의 경우 v5.5.0 이상, Flutter/Cordova의 경우 v1.8.0 이상, React Native의 경우 v3.9.0 이상)
• -ObjC 링크어 플래그 추가 및 SingularConfig 에서 enableOdmWithTimeoutInterval 활성화

참고: enableOdmWithTimeoutInterval를 활성화하면 SDK 초기화가 지연되고 딥 링크 콜백이 연기될 수 있습니다. 재작업을 방지하려면 초기 SDK 구현 단계에서 이 설정을 완료하십시오.

전체 iOS ICM 기술 요구 사항 참조