Unity SDK 기본 연동

Singular Unity SDK
다운로드 Singular Unity SDK version 2.4.0
호환성

Unity 4.7.2+

샘플 앱 베스트 프랙티스에 기반한 전체 SDK 연동 방법 확인을 위해 샘플 앱을 참조해주세요.
연동 가이드

 

Android와 iOS 준비 사항 설정

Android 준비 사항

AndroidManifest.xml 파일 내에 다음 코드를 <application> 태그 아래 추가하여 인스톨 리퍼러를 사용할 수 있도록 합니다.

<receiver android:exported="true" android:name="com.singular.sdk.SingularInstallReceiver" android:permission="android.permission.INSTALL_PACKAGES">
    <intent-filter>      
        <action android:name="com.android.vending.INSTALL_REFERRER"></action>      
    </intent-filter>
</receiver>

또한 다음 권한을 추가합니다.

<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.INTERNET" />

Google Play Services (Mobile Ads)

Singular SDK는 Google Play Services APIs 7.5+에 포함된 Google Mobile Ads API를 사용합니다.

이미 앱 내에 Google Play Services를 포함했다면 Singular에서 필요로 하는 조건은 충족됩니다.

만약 해당 서비스를 포함하지 않았다면 다음 디펜던시를 앱의 build.gradle 파일에 추가해서 Google Mobile Ads를 개별적으로 연동할 수 있습니다.

compile 'com.google.android.gms:play-services-ads:11.6.0'

더 자세한 정보는 Google Play Services 설정에 대한 Google의 가이드에서 확인할 수 있습니다.

Android 설정 (Proguard 및 Eclipse) ▼

Proguard를 사용한다면, proguard-unity.txt 파일에 다음 코드를 추가하세요.

-keep class com.singular.sdk.** { *; }
-keep public class com.android.installreferrer.** { *; }
-keep public class com.singular.unitybridge.** { *; }

Eclipse로 앱을 빌드하는 경우, 다음 중 하나의 방법으로 Eclipse 프로젝트에 AAR을 연동하세요.

  • singular_sdk-9.x.x.aar의 압축 해제
  • classes.jarsingular_sdk-9.x.x.jar로 이름 변경(메인 main SDK)
  • 원하는 방법에 따라 Eclipse 프로젝트에 위 jar 및 libs/installreferrer-release.jar( Google Referrer API 라이브러리) 연동
  • AAR 내의 AndroidManifest.xml 파일의 BIND_GET_INSTALL_REFERRER_SERVICE 권한을 AndroidManifest.xml로 복사

iOS 준비 사항

다음 라이브러리/프레임워크를 Unity XCode 프로젝트에 링크합니다.

  • Security.framework
  • SystemConfiguration.framework
  • iAD.framework
  • Adsupport.framework
  • WebKit.framework
  • libsqlite3.0.tbd
  • libz.tbd
  • AdServices.framework (iOS 14.3 이상 디바이스만 해당합니다. optional로 선택하세요.)

SDK 패키지 다운로드 및 임포트

먼저 SDK unitypackage 파일을 다운로드하세요.

Assets > Import Package > Custom package 메뉴를 사용해서 앱에 unitypackage를 임포트합니다.

SDK 오브젝트 추가

Unity 플랫폼에서 다음 단계를 따르세요.

  • Main 씬에 오브젝트를 추가하고 SingularSDKObject로 이름 변경
  • SingularSDK 스크립트를 해당 오브젝트에 끌어다 넣습니다.
  • Inspection 창에서 Singular API Key와 API Secret을 복사하여 붙여 넣습니다.

기본 연동 설정

SDK 초기화

주의: Singular SDK를 연동할 때, GDPR, CCPA 및 COPPA 등 비즈니스를 수행하는 지역에서 제정된 다양한 개인 정보 보호법를 준수해야 함에 유의하세요. 더 자세한 내용은 SDK Opt-In and Opt-Out Practices 문서에서 확인할 수 있습니다.

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

기본적으로 SingularSDK.cs는 씬이 생성될 때 Awake 메서드를 통해 SDK를 자동 초기화합니다.

수동 초기화

앱 오픈 시점이 아닌 실행 이후 시점에 SDK를 수동으로 초기화하기를 원하는 경우 다음 단계를 따르세요.

  • SingularSDK 오브젝트의 inspection 창에서 Initialize on Awake 옵션을 비활성화합니다.
  • Singular.InitializeSingularSDK 정적 메서드를 사용해서 SDK를 초기화합니다.
SingularSDK.InitializeSingularSDK 메서드
정의 Awake에서 Singular SDK가 초기화되지 않은 경우 초기화합니다.
메서드
public void InitializeSingularSDK()
사용예
// API Key and API Secret are set on the 
// game object associated with SingularSDK SingularSDK.InitializeSingularSDK();

스레드 안전성 주의: 다른 유니티 메서드 호출시와 마찬가지로 Singular Unity SDK는 동일한 스레드에서 불려야 합니다.

선택 사항: 세션 타임아웃 변경

기본적으로 앱이 포그라운드로 돌아오기 전 백그라운드에서 60초 이상 실행됐다면 Singular SDK는 새 세션을 등록합니다. SingularSDKObject의 Session Timeout Sec 프로퍼티를 수정하면 이 기본 타임아웃 값을 변경할 수 있습니다.

선택 사항: 유저 ID 설정

Singular SDK를 통해 앱에서 Singular로 유저 ID를 전달할 수 있습니다. 유저 ID는 유저 네임, 이메일 주소, 무작위 생성 문자열 등 어떤 식별자라도 가능합니다. Singular는 유저 ID를 유저 레벨 데이터 익스포트 혹은 (설정시) 내부 BI 포스트백에서 제공합니다.

Singular에 보낼 유저 ID를 설정하려면 SetCustomUserId 메서드를 호출하세요. ID를 설정 해제하는 경우 (예를 들어 유저가 로그아웃을 하는 경우) UnsetCustomUserId를 호출하세요.

주의:

  • 설정된 유저 ID는 UnsetCustomUserId 호출로 설정 해제하거나 앱이 삭제될 때까지 유지됩니다. 앱을 닫거나 재시작하는 것으로는 유저 ID가 설정 해제되지 않습니다.
  • 앱이 열리는 시점에 유저 ID를 식별할 수 있고 Singular의 최초 세션부터 Singular에 유저 ID를 보내고자 한다면 Singular SDK 초기화 시점 전에 유저 ID를 설정하세요.
SingularSDK.SetCustomUserId 메서드
정의 Singular에 유저 ID 전송
메서드
public void SetCustomUserId(string customUserId)
사용예
SingularSDK.SetCustomUserId("custom_user_id");
SingularSDK.UnsetCustomUserId 메서드
Description 마지막 CustomUserId 호출에서 Singular로 전송된 유저 ID를 해제
메서드
public void UnsetCustomUserId()
사용예
SingularSDK.UnsetCustomUserId();

[NEW] AppTrackingTransparency 동의 처리

주의: Apple은 발표를 통해 iOS 14.5부터 디바이스 IDFA에 접근하기 위해서는 앱 추적 투명성(App Tracking Transparency, ATT) 팝업창이 요구된다고 밝혔습니다. iOS 14.5의 공식 릴리즈 전에는 AppTrackingTransprency 팝업창을 구현하지 않기를 권장합니다.

iOS 14.5부터 앱이 디바이스의 IDFA 값을 포함한 유저 데이터 일부에 접근하기 전에 앱 추적 투명성(App Tracking Transparency) 프레임워크를 통해 유저 동의를 받아야 합니다.

Singular는 인스톨 어트리뷰션을 수행한 디바이스를 식별하기 위해 IDFA를 사용해 왔습니다. (물론 IDFA 없이도 어트리뷰션을 수행하는 방법도 있었습니다.) IDFA를 얻으려면 유저 동의를 구하는 것을 적극적으로 권장합니다.

또한 유저 세션을 Singular로 보내기 전에 SDK가 대기하도록 해야합니다. Singular SDK는 기본적으로 유저 세션을 초기화 시점에 전송하며, 세션이 신규 디바이스에서 발송되면 이는 즉시 Singular의 어트리뷰션 절차를 시작합니다. 이 프로세스는 Singular가 해당 시점에 사용할 수 있는 데이터에 의존하게 됩니다.

따라서 Singular SDK가 세션을 발송하기 전에 유저 동의를 구하고 IDFA를 확인할 수 있도록 해야 합니다.

유저 세션 전송을 지연하려면 SingularSDKObject 내의 waitForTrackingAuthorizationWithTimeoutInterval 옵션을 설정하세요. 이는 Singular SDK가 Singular 서버에 이벤트를 전송하기 전, AppTrackingTransparency 동의 사항을 유저가 수락하거나 거부하는 것을 최대 시간(초 단위) 동안 기다립니다. 해당 옵션의 기본값은 0(대기하지 않음)입니다.

도움이 되었습니까?