Unity SDK - 구성 레퍼런스

Unity용 Singular SDK가 제공하는 모든 구성 옵션과 각각의 타입, 기본값, 지원 플랫폼, 설정 방법입니다.

코드에서 구성 설정하기

인스펙터에서 Initialize On Awake를 해제하고 필요한 필드를 설정한 다음 SDK를 직접 초기화하세요. 정적 멤버는 이 방법으로만 설정할 수 있습니다.

using UnityEngine;
using Singular;

public class SingularBootstrap : MonoBehaviour
{
    void Awake()
    {
        // Clear Initialize On Awake in the Inspector first, so the SDK
        // does not start before these values are set.
        SingularSDK singular = GetComponent<SingularSDK>();

        singular.SingularAPIKey    = "YOUR_SDK_KEY";
        singular.SingularAPISecret = "YOUR_SDK_SECRET";
        singular.sessionTimeoutSec = 120;

        // Static members are not shown in the Inspector and are set here only.
        SingularSDK.endSessionOnGoingToBackground = true;

        SingularSDK.InitializeSingularSDK();
    }
}

전체 구성 예제

종합 SDK 구성

대부분의 연동에서 사용하는 주요 옵션을 담은 대표적인 구성입니다.

using UnityEngine;
using Singular;

public class SingularBootstrap : MonoBehaviour
{
    void Awake()
    {
        SingularSDK singular = GetComponent<SingularSDK>();

        // Required
        singular.SingularAPIKey    = "YOUR_SDK_KEY";
        singular.SingularAPISecret = "YOUR_SDK_SECRET";

        // Logging — off for a production build
        singular.enableLogging = false;

        // Sessions and link resolution
        singular.sessionTimeoutSec       = 120;
        singular.shortlinkResolveTimeout = 15;
        singular.ddlTimeoutSec           = 120;   // Android

        // Links
        singular.brandedDomains = new string[] { "go.yourcompany.com" };
        singular.pushNotificationsLinkPaths = new string[] { "sng_link" };

        // iOS
        singular.waitForTrackingAuthorizationWithTimeoutInterval = 300;
        singular.SKANEnabled = true;

        // Android
        singular.facebookAppId = "1234567890";

        SingularSDK.InitializeSingularSDK();
    }
}

autoIAPComplete

SingularSDK.autoIAPComplete 속성

StoreKit 트랜잭션을 자동으로 완료하던 레거시 설정입니다.

서명

public bool autoIAPComplete

기본값: false

플랫폼: iOS 전용

설정 방법: Unity 인스펙터 또는 코드

사용 예시

singular.autoIAPComplete = false;

brandedDomains

SingularSDK.brandedDomains 속성

SDK가 Singular Links로 처리해야 하는 커스텀 링크 도메인입니다. 트래킹 링크에 사용하는 모든 브랜디드 도메인을 추가하세요. 설정하지 않으면 Manage Links 페이지에 등록된 sng.link 도메인만 인식됩니다.

서명

public string[] brandedDomains

기본값: null

플랫폼: iOS 및 Android

설정 방법: Unity 인스펙터 또는 코드

사용 예시

singular.brandedDomains = new string[] {
    "yourcompany.com",
    "go.yourcompany.com"
};

clipboardAttribution

SingularSDK.clipboardAttribution 속성

앱 실행 시 SDK가 붙여넣기 보드를 읽어 Singular Link의 어트리뷰션 데이터를 복구할 수 있게 합니다.

서명

public bool clipboardAttribution

기본값: false

플랫폼: iOS 전용

설정 방법: Unity 인스펙터 또는 코드

사용 예시

singular.clipboardAttribution = true;

collectOAID

SingularSDK.collectOAID 속성

Google Play services가 없는 Android 기기(주로 중국 본토)에서 사용하는 광고 식별자인 OAID를 수집합니다. 빌드에 OAID 라이브러리가 포함되어 있어야 합니다.

서명

public bool collectOAID

기본값: false

플랫폼: Android 전용

설정 방법: Unity 인스펙터 또는 코드

사용 예시

singular.collectOAID = true;

CustomSdid

SingularSDK.CustomSdid 속성

SDK가 생성하는 대신 직접 만든 Singular Device ID를 지정합니다. 초기화 전에 설정하고, 수락 여부를 확인하려면 SingularSDK.SetSingularSdidAccessorHandler()로 핸들러를 등록하세요.

서명

public static string CustomSdid

기본값: null

플랫폼: iOS 및 Android

설정 방법: 코드 전용 — 인스펙터에 표시되지 않음

사용 예시

SingularSDK.CustomSdid = "your-own-device-id";

ddlTimeoutSec

SingularSDK.ddlTimeoutSec 속성

신규 설치 후 SDK가 디퍼드 딥링크를 확인하여 Singular Link 핸들러를 호출할 수 있는 시간입니다. 0으로 두면 기본값 60초가 사용됩니다.

서명

public long ddlTimeoutSec

기본값: 0 (uses the 60 second default)

플랫폼: Android 전용

설정 방법: Unity 인스펙터 또는 코드

사용 예시

singular.ddlTimeoutSec = 120;

enableDeferredDeepLinks

SingularSDK.enableDeferredDeepLinks 속성

Android에서 디퍼드 딥링크 핸들러를 등록합니다. 디퍼드 링크를 의도적으로 무시하려는 경우가 아니라면 활성화 상태로 두세요.

서명

public static bool enableDeferredDeepLinks

기본값: true

플랫폼: Android 전용

설정 방법: 코드 전용 — 인스펙터에 표시되지 않음

사용 예시

SingularSDK.enableDeferredDeepLinks = false;

enableLogging

SingularSDK.enableLogging 속성

SDK 로그 출력을 활성화하여 연동 및 문제 해결에 도움을 줍니다. 기본적으로 활성화되어 있으므로(enableLogging가 true) 프로덕션 빌드를 출시하기 전에 체크박스를 해제하세요.

서명

public bool enableLogging

기본값: true

플랫폼: iOS 및 Android

설정 방법: Unity 인스펙터 또는 코드

사용 예시

singular.enableLogging = false;

enableODMWithTimeoutInterval

SingularSDK.enableODMWithTimeoutInterval 속성

Google의 On-Device Measurement(ODM)를 활성화하고, 첫 세션을 전송하기 전에 Google의 어트리뷰션 토큰을 기다릴 시간을 초 단위로 설정합니다. Google Ads iOS Integrated Conversion Measurement(ICM)에 필요합니다.

서명

public int enableODMWithTimeoutInterval

기본값: -1 (disabled)

플랫폼: iOS 전용

설정 방법: Unity 인스펙터 또는 코드

사용 예시

singular.enableODMWithTimeoutInterval = 10;

endSessionOnGoingToBackground

SingularSDK.endSessionOnGoingToBackground 속성

세션 타임아웃이 만료되기를 기다리지 않고 앱이 백그라운드로 전환되는 즉시 Singular 세션을 종료합니다. 대부분의 앱은 이 옵션을 끄고 sessionTimeoutSec에 맡기는 것이 좋습니다.

서명

public static bool endSessionOnGoingToBackground

기본값: false

플랫폼: iOS 및 Android

설정 방법: 코드 전용 — 인스펙터에 표시되지 않음

사용 예시

SingularSDK.endSessionOnGoingToBackground = true;

facebookAppId

SingularSDK.facebookAppId 속성

Android에서 Meta 인스톨 리퍼러 어트리뷰션에 필요한 Facebook App ID입니다.

서명

public string facebookAppId

기본값: null

플랫폼: Android 전용

설정 방법: Unity 인스펙터 또는 코드

사용 예시

singular.facebookAppId = "1234567890";

fcmDeviceToken

SingularSDK.fcmDeviceToken 속성

앱 삭제 트래킹에 사용하는 Firebase Cloud Messaging 토큰입니다. 초기화 전에는 이 값을 설정하고 초기화 후에는 네이티브 SDK를 호출하는 SingularSDK.RegisterTokenForUninstall()을 사용하는 것이 좋습니다.

서명

public static string fcmDeviceToken

기본값: null

플랫폼: Android 전용

설정 방법: 코드 전용 — 인스펙터에 표시되지 않음

사용 예시

SingularSDK.RegisterTokenForUninstall(token);

Initialized

SingularSDK.Initialized 속성

읽기 전용입니다. SDK 초기화 완료 여부를 나타냅니다. 이 값이 true가 되기 전까지 대부분의 SDK 메서드는 아무 작업도 하지 않고 반환됩니다.

서명

public static bool { get; } Initialized

기본값: false

플랫폼: iOS 및 Android

설정 방법: 코드 전용 — 인스펙터에 표시되지 않음

사용 예시

if (SingularSDK.Initialized) {
    SingularSDK.Event("level_complete");
}

InitializeOnAwake

SingularSDK.InitializeOnAwake 속성

게임 오브젝트의 Awake()에서 SDK를 자동으로 초기화합니다. 코드에서 먼저 구성을 설정해야 한다면 해제한 뒤 SingularSDK.InitializeSingularSDK()를 직접 호출하세요.

서명

public bool InitializeOnAwake

기본값: true

플랫폼: iOS 및 Android

설정 방법: Unity 인스펙터 또는 코드

사용 예시

singular.InitializeOnAwake = false;

limitAdvertisingIdentifiers

SingularSDK.limitAdvertisingIdentifiers 속성

SDK가 기기 광고 식별자를 수집하지 않도록 합니다. 일부 사용자로부터 광고 ID를 수집하면 안 되는 혼합 대상 앱에 사용하세요.

서명

public bool limitAdvertisingIdentifiers

기본값: false

플랫폼: iOS 및 Android

설정 방법: Unity 인스펙터 또는 코드

사용 예시

singular.limitAdvertisingIdentifiers = true;

logLevel

SingularSDK.logLevel 속성

SDK 로그 출력의 상세 수준을 설정합니다. 값은 Android android.util.Log 상수이며 숫자가 작을수록 더 상세합니다. 2 Verbose, 3 Debug, 4 Info, 5 Warn, 6 Error, 7 Assert. 기본값은 3(Debug)입니다. 2~7 범위를 벗어난 값은 거부되어 SDK가 Debug로 폴백하므로 0과 1은 로그를 줄이지 않습니다. 로그를 끄려면 Enable Logging 체크를 해제하세요.

서명

public int logLevel

기본값: 3 (Debug)

플랫폼: iOS 및 Android

설정 방법: Unity 인스펙터 또는 코드

사용 예시

singular.logLevel = 3; // Debug

manualSKANConversionManagement

SingularSDK.manualSKANConversionManagement 속성

SKAdNetwork 전환 값 관리를 앱으로 넘깁니다. 활성화하면 Singular이 관리를 중단하므로 직접 SingularSDK.SkanUpdateConversionValue()를 호출해야 합니다.

서명

public bool manualSKANConversionManagement

기본값: false

플랫폼: iOS 전용

설정 방법: Unity 인스펙터 또는 코드

사용 예시

singular.manualSKANConversionManagement = true;

openUri

SingularSDK.openUri 속성

앱이 실행될 때 사용된 URI로, 초기화 시 SDK에 전달되어 해당 실행을 어트리뷰션할 수 있게 합니다. SDK가 시작되기 전에 액티비티가 딥링크를 받는 경우 초기화 전에 설정하세요.

서명

public static string openUri

기본값: null

플랫폼: Android 전용

설정 방법: 코드 전용 — 인스펙터에 표시되지 않음

사용 예시

SingularSDK.openUri = "myapp://product/123";

pushNotificationsLinkPaths

SingularSDK.pushNotificationsLinkPaths 속성

푸시 알림 페이로드에서 Singular Link를 찾을 위치입니다. 각 항목은 페이로드를 따라가는 경로이며 단계는 /로 구분합니다. 앱이 수신하는 페이로드 형태마다 항목을 하나씩 추가하세요.

서명

public string[] pushNotificationsLinkPaths

기본값: null

플랫폼: iOS 및 Android

설정 방법: Unity 인스펙터 또는 코드

사용 예시

singular.pushNotificationsLinkPaths = new string[] {
    "sng_link",
    "notification/deep_link",
    "rootObj/nestedObj/singularLink"
};

restartSessionOnReturningToForeground

SingularSDK.restartSessionOnReturningToForeground 속성

앱이 포그라운드로 돌아올 때마다 새 Singular 세션을 시작합니다. endSessionOnGoingToBackground와 함께 사용하세요. 대부분의 앱은 두 옵션을 모두 끄는 것이 좋습니다.

서명

public static bool restartSessionOnReturningToForeground

기본값: false

플랫폼: iOS 및 Android

설정 방법: 코드 전용 — 인스펙터에 표시되지 않음

사용 예시

SingularSDK.restartSessionOnReturningToForeground = true;

sessionTimeoutSec

SingularSDK.sessionTimeoutSec 속성

다음 실행이 새 세션으로 집계되기까지 앱이 백그라운드에 머물 수 있는 시간입니다. 0으로 두면 기본값 60초가 사용됩니다.

서명

public long sessionTimeoutSec

기본값: 0 (uses the 60 second default)

플랫폼: iOS 및 Android

설정 방법: Unity 인스펙터 또는 코드

사용 예시

singular.sessionTimeoutSec = 120;

shortlinkResolveTimeout

SingularSDK.shortlinkResolveTimeout 속성

SDK가 단축 링크 확인을 포기하기까지 기다리는 시간입니다. 0으로 두면 기본값 10초가 사용됩니다.

서명

public long shortlinkResolveTimeout

기본값: 0 (uses the 10 second default)

플랫폼: iOS 및 Android

설정 방법: Unity 인스펙터 또는 코드

사용 예시

singular.shortlinkResolveTimeout = 15;

SingularAPIKey

SingularSDK.SingularAPIKey 속성

SDK 키입니다. Singular에서 Developer Tools > SDK Integration > SDK Keys 아래에서 확인할 수 있습니다.

서명

public string SingularAPIKey

기본값: 필수

플랫폼: iOS 및 Android

설정 방법: Unity 인스펙터 또는 코드

사용 예시

singular.SingularAPIKey = "YOUR_SDK_KEY";

SingularAPISecret

SingularSDK.SingularAPISecret 속성

같은 페이지에서 SDK 키와 함께 발급되는 SDK 시크릿입니다.

서명

public string SingularAPISecret

기본값: 필수

플랫폼: iOS 및 Android

설정 방법: Unity 인스펙터 또는 코드

사용 예시

singular.SingularAPISecret = "YOUR_SDK_SECRET";

SKANEnabled

SingularSDK.SKANEnabled 속성

앱을 SKAdNetwork 어트리뷰션에 등록하고 Singular이 전환 값을 관리하도록 합니다. 앱의 다른 SDK가 SKAdNetwork를 관리하는 경우가 아니라면 켜 두세요.

서명

public bool SKANEnabled

기본값: true

플랫폼: iOS 전용

설정 방법: Unity 인스펙터 또는 코드

사용 예시

singular.SKANEnabled = false;

waitForTrackingAuthorizationWithTimeoutInterval

SingularSDK.waitForTrackingAuthorizationWithTimeoutInterval 속성

첫 세션을 전송하기 전에 사용자가 App Tracking Transparency 프롬프트에 응답하기를 기다릴 시간(초)입니다. 기다리면 동의를 받았을 때 첫 세션에 IDFA를 포함할 수 있습니다.

서명

public int waitForTrackingAuthorizationWithTimeoutInterval

기본값: 0 (do not wait)

플랫폼: iOS 전용

설정 방법: Unity 인스펙터 또는 코드

사용 예시

singular.waitForTrackingAuthorizationWithTimeoutInterval = 300;