전역 속성 설정

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

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

속성 사양

제한 및 지속성

전역 속성의 제약 조건과 지속성 동작을 이해하세요.

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

초기화 시 전역 속성 설정

SingularConfig를 통한 구성

Singular.init() 를 호출하기 전에 withGlobalProperty 메서드를 사용하여 SDK 초기화 중 전역 속성을 설정하세요.

전역 속성은 앱 실행 간에 지속되므로 속성이 이미 다른 값으로 존재할 수 있습니다. 새 값이 기존 값을 덮어쓸지 여부를 제어하려면 overrideExisting 파라미터를 사용하세요.

// Set global properties during initialization
val config = SingularConfig("SDK_KEY", "SDK_SECRET")
    .withGlobalProperty("MyProperty", "MyValue", true)
    .withGlobalProperty("AnotherProperty", "AnotherValue", true)

Singular.init(applicationContext, config)

// Set global properties during initialization
SingularConfig config = new SingularConfig("SDK_KEY", "SDK_SECRET")
    .withGlobalProperty("MyProperty", "MyValue", true)
    .withGlobalProperty("AnotherProperty", "AnotherValue", true);

Singular.init(getApplicationContext(), config);

메서드 시그니처:

public SingularConfig withGlobalProperty(String key, String value, boolean overrideExisting)

파라미터:

• key: 속성 이름(최대 200자)
• value: 속성 값(최대 200자)
• overrideExisting: 동일한 키를 가진 기존 속성을 덮어쓸지 여부

초기화 후 속성 관리

전역 속성 설정

앱 런타임 중 언제든지 전역 속성을 추가하거나 업데이트하세요.

// Set a global property after initialization
val result = Singular.setGlobalProperty("MyProperty", "MyValue", true)
if (result) {
    Log.d("Singular", "Property set successfully")
} else {
    Log.e("Singular", "Failed to set property")
}

// Set a global property after initialization
boolean result = Singular.setGlobalProperty("MyProperty", "MyValue", true);
if (result) {
    Log.d("Singular", "Property set successfully");
} else {
    Log.e("Singular", "Failed to set property");
}

메서드 시그니처:

public static boolean setGlobalProperty(String key, String value, boolean overrideExisting)

반환값: true 이면 속성이 성공적으로 설정되었음을 의미하며, 그렇지 않으면 false 를 반환합니다

전역 속성 가져오기

현재 설정된 모든 전역 속성과 해당 값을 Map으로 검색합니다.

// Retrieve all global properties
val properties: Map<String, String> = Singular.getGlobalProperties()

// Iterate through properties
properties.forEach { (key, value) ->
    Log.d("Singular", "Property: $key = $value")
}

// Retrieve all global properties
Map<String, String> properties = Singular.getGlobalProperties();

// Iterate through properties
for (Map.Entry<String, String> entry : properties.entrySet()) {
    Log.d("Singular", "Property: " + entry.getKey() + " = " + entry.getValue());
}

메서드 시그니처:

public static Map<String, String> getGlobalProperties()

반환값: 모든 전역 속성 키-값 쌍을 포함하는 Map

전역 속성 해제

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

// Remove a specific global property
Singular.unsetGlobalProperty("MyProperty")

// Remove a specific global property
Singular.unsetGlobalProperty("MyProperty");

메서드 시그니처:

public static void unsetGlobalProperty(String key)

파라미터:

• key: 제거할 속성의 이름

모든 전역 속성 지우기

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

// Remove all global properties
Singular.clearGlobalProperties()

// Remove all global properties
Singular.clearGlobalProperties();

메서드 시그니처:

public static void clearGlobalProperties()

구현 예시

전체 사용 패턴

애플리케이션 라이프사이클 전반에 걸쳐 앱 레벨 및 유저별 속성을 트래킹하세요.

// Initialize SDK with app-level global properties
val config = SingularConfig("SDK_KEY", "SDK_SECRET")
    .withGlobalProperty("app_version", BuildConfig.VERSION_NAME, true)

Singular.init(applicationContext, config)

// Set third-party identifier on login
fun onUserLogin(thirdPartyUserId: String) {
    val success = Singular.setGlobalProperty("third_party_identifier", thirdPartyUserId, true)
    if (success) {
        Log.d("Singular", "Third-party identifier set")
    }
}

// Clear third-party identifier on logout
fun onUserLogout() {
    Singular.unsetGlobalProperty("third_party_identifier")
    Log.d("Singular", "Third-party identifier cleared")
}

// Initialize SDK with app-level global properties
SingularConfig config = new SingularConfig("SDK_KEY", "SDK_SECRET")
    .withGlobalProperty("app_version", BuildConfig.VERSION_NAME, true);

Singular.init(getApplicationContext(), config);

// Set third-party identifier on login
public void onUserLogin(String thirdPartyUserId) {
    boolean success = Singular.setGlobalProperty("third_party_identifier", thirdPartyUserId, true);
    if (success) {
        Log.d("Singular", "Third-party identifier set");
    }
}

// Clear third-party identifier on logout
public void onUserLogout() {
    Singular.unsetGlobalProperty("third_party_identifier");
    Log.d("Singular", "Third-party identifier cleared");
}