Unity SDK - 글로벌 프로퍼티 설정

팔로우
Avatar
Jared Ornstead
Updated
문서

전역 속성 설정

앱에서 전송되는 모든 세션과 이벤트에 자동으로 첨부되는 사용자 지정 속성을 정의하여 보고서에서 세부적인 데이터 세분화를 가능하게 합니다.

전역 속성을 사용하면 필요한 모든 사용자, 앱 모드 또는 컨텍스트 정보를 추적할 수 있습니다. 예를 들어, 게임 앱에서 사용자가 게임을 진행함에 따라 업데이트되는 '0'으로 초기화된 '레벨' 속성을 만듭니다. 모든 세션과 이벤트에 이 속성이 포함되므로 사용자 수준별로 세션, 이벤트 수, 구매을 분석할 수 있습니다.

속성 사양

제한 및 지속성

글로벌 프로퍼티의 제약 조건과 지속성 동작을 이해합니다.

  • 최대 속성: 앱 설치당 최대 5개의 글로벌 속성을 정의할 수 있습니다.
  • 지속성: 명시적으로 설정이 해제되거나 앱이 제거될 때까지 앱 실행 간에 속성이 가장 최근 값으로 유지됩니다.
  • 글자 수 제한: 속성 이름과 값은 최대 200자까지 입력할 수 있습니다. 더 긴 값은 자동으로 200자로 잘립니다.
  • 데이터 가용성: 글로벌 속성은 사용자 수준 내보내기 및 포스트백에서 액세스할 수 있습니다. 집계 보고 지원에 대한 업데이트는 Singular 고객 성공 매니저에게 문의하세요.

초기화 시 글로벌 속성 설정

SDK 초기화 전 구성

SDK 초기화 전에 SetGlobalProperty() 을 사용하여 글로벌 속성을 설정하여 초기 세션에 포함되도록 하세요.

글로벌 프로퍼티는 앱 실행 간에 유지되므로 프로퍼티가 이미 다른 값으로 존재할 수 있습니다. overrideExisting 매개변수를 사용하여 새 값이 기존 값을 재정의할지 여부를 제어합니다.

중요: 글로벌 프로퍼티를 첫 번째 세션에 포함하려면 SingularSDKObject Inspector에서 Initialize On Awake 플래그를 비활성화하고 프로퍼티를 설정한 후 SDK를 수동으로 초기화하세요.

C# 
using UnityEngine;
using Singular;

public class SingularInitializer : MonoBehaviour
{
    void Awake()
    {
        // Set global properties before SDK initialization
        SingularSDK.SetGlobalProperty("app_version", Application.version, true);
        SingularSDK.SetGlobalProperty("user_type", "free", true);

        // Manually initialize SDK to ensure properties are in first session
        SingularSDK.InitializeSingularSDK();
    }
}

메서드 서명: 

public static bool SetGlobalProperty(string key, string value, bool overrideExisting)

파라미터:

  • key: 속성 이름(최대 200자)
  • value: 속성 값(최대 200자)
  • overrideExisting: 동일한 키로 기존 프로퍼티를 재정의할지 여부입니다.

초기화 후 프로퍼티 관리

글로벌 프로퍼티 설정

앱 런타임 중 언제든지 글로벌 프로퍼티를 추가하거나 업데이트할 수 있습니다.

C# 
// Set a global property after initialization
bool result = SingularSDK.SetGlobalProperty("player_level", "5", true);

if (result)
{
    Debug.Log("Property set successfully");
}
else
{
    Debug.LogError("Failed to set property - may have reached 5 property limit");
}

메서드 서명: 

public static bool SetGlobalProperty(string key, string value, bool overrideExisting)

반환: 프로퍼티가 성공적으로 설정된 경우 true, 그렇지 않은 경우 false

중요:

  • 5개의 프로퍼티가 이미 존재하고 새 프로퍼티를 추가하려고 하면 메서드는 false을 반환합니다.
  • overrideExisting 매개 변수는 기존 속성 값을 대체할지 여부를 결정합니다.
  • 반환 값을 확인하여 프로퍼티가 성공적으로 설정되었는지 확인합니다.

전역 프로퍼티 가져오기

현재 설정된 모든 글로벌 프로퍼티와 해당 값을 딕셔너리로 가져옵니다.

C# 
// Retrieve all global properties
Dictionary<string, string> properties = SingularSDK.GetGlobalProperties();

// Iterate through properties
foreach (KeyValuePair<string, string> property in properties)
{
    Debug.Log($"Property: {property.Key} = {property.Value}");
}

메서드 서명: 

public static Dictionary<string, string> GetGlobalProperties()

반환합니다: 모든 글로벌 프로퍼티 키-값 쌍이 포함된 딕셔너리입니다.

글로벌 프로퍼티 설정 해제

특정 전역 속성을 해당 키로 제거합니다.

C# 
// Remove a specific global property
SingularSDK.UnsetGlobalProperty("player_level");

메서드 서명: 

public static void UnsetGlobalProperty(string key)

파라미터:

  • key: 제거할 프로퍼티의 이름

모든 전역 속성 지우기

모든 전역 속성을 한 번에 제거합니다.

C# 
// Remove all global properties
SingularSDK.ClearGlobalProperties();

메서드 서명: 

public static void ClearGlobalProperties()

모범 사례: 사용자가 로그아웃하거나 모든 사용자 지정 추적 속성을 기본 상태로 재설정해야 할 때 ClearGlobalProperties()을 사용합니다.

구현 예시

전체 사용 패턴

애플리케이션 라이프사이클 전반에 걸쳐 앱 수준 및 사용자별 속성을 추적합니다.

C# 
using UnityEngine;
using Singular;

public class GlobalPropertiesManager : MonoBehaviour
{
    void Awake()
    {
        // Set app-level global properties before initialization
        SingularSDK.SetGlobalProperty("app_version", Application.version, true);
        
        // Initialize SDK
        SingularSDK.InitializeSingularSDK();
    }
    
    // Set third-party identifier on login
    public void OnUserLogin(string thirdPartyUserId)
    {
        bool success = SingularSDK.SetGlobalProperty("third_party_identifier", thirdPartyUserId, true);
        
        if (success)
        {
            Debug.Log("Third-party identifier set");
        }
    }
    
    // Clear third-party identifier on logout
    public void OnUserLogout()
    {
        SingularSDK.UnsetGlobalProperty("third_party_identifier");
        Debug.Log("Third-party identifier cleared");
    }
}

모범 사례: 연동 크로스 플랫폼 추적을 위해 타사 애널리틱스 식별자(예: Mixpanel distinct_id, Amplitude user_id)를 Singular 글로벌 프로퍼티에 동기화합니다. 로그인 시에는 사용자별 식별자를 설정하고 로그아웃 시에는 UnsetGlobalProperty() 으로 지웁니다. app_version 같은 앱 수준 속성은 여러 세션에 걸쳐 유지됩니다.

속성 제한 관리: 글로벌 속성은 최대 5개로, 분석에 가장 가치 있는 추적 기준에 우선순위를 지정하세요. 한도에 도달하면 새 속성을 추가하기 전에 덜 중요한 속성을 제거하는 것이 좋습니다. 위의 예는 5개 속성 제한을 우아하게 처리하는 방법을 보여줍니다.