Cordova SDK - 글로벌 속성 설정

팔로우
Avatar
Jared Ornstead
Updated
문서

전역 속성 설정

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

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

속성 사양

제한 및 지속성

구현하기 전에 글로벌 프로퍼티의 제약 조건과 지속성 동작을 이해하세요.

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

초기화 시 글로벌 속성 설정

SDK 초기화 전 구성

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

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

JavaScript 
// Initialize SDK with global properties
var config = new cordova.plugins.SingularCordovaSdk.SingularConfig(
  'YOUR_SDK_KEY',
  'YOUR_SDK_SECRET'
);

// Set app-level global properties before initialization
config.withGlobalProperty('app_version', '1.2.3', true);
config.withGlobalProperty('user_type', 'free', true);

// Initialize SDK with global properties
cordova.plugins.SingularCordovaSdk.init(config);

메서드 서명: 

withGlobalProperty(key: string, value: string, overrideExisting: boolean): SingularConfig

매개변수:

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

초기화 후 프로퍼티 관리

글로벌 프로퍼티 설정

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

JavaScript 
// Set a global property after initialization
function updatePlayerLevel(level) {
  cordova.plugins.SingularCordovaSdk.setGlobalProperty(
    'player_level',
    level.toString(),
    true,
    function(success) {
      if (success) {
        console.log('Global property set successfully');
      } else {
        console.error('Failed to set property - may have reached 5 property limit');
      }
    }
  );
}

메서드 서명: 

setGlobalProperty(key: string, value: string, overrideExisting: boolean, success: Function): void

매개변수

  • key: 속성 이름(최대 200자)
  • value: 속성 값(최대 200자)
  • overrideExisting: 동일한 키로 기존 프로퍼티를 재정의할지 여부
  • 성공: 프로퍼티가 성공적으로 설정된 경우 true, 그렇지 않은 경우 false 을 수신하는 콜백 함수

중요:

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

전역 프로퍼티 가져오기

현재 설정된 모든 전역 프로퍼티와 해당 값을 객체로 가져옵니다.

JavaScript 
// Retrieve all global properties
function displayGlobalProperties() {
  cordova.plugins.SingularCordovaSdk.getGlobalProperties(function(properties) {
    // Iterate through properties
    for (var key in properties) {
      if (properties.hasOwnProperty(key)) {
        console.log('Property: ' + key + ' = ' + properties[key]);
      }
    }
  });
}

메서드 서명: 

getGlobalProperties(success: Function): void

파라미터:

  • 성공: 모든 전역 속성 키-값 쌍을 포함하는 객체를 수신하는 콜백 함수입니다.

글로벌 프로퍼티 설정 해제

더 이상 해당 기준을 추적할 필요가 없을 때 해당 키로 특정 전역 속성을 제거합니다.

JavaScript 
// Remove a specific global property
cordova.plugins.SingularCordovaSdk.unsetGlobalProperty('player_level');

메서드 서명: 

unsetGlobalProperty(key: string): void

매개변수:

  • key: 제거할 속성의 이름

모든 전역 속성 지우기

일반적으로 사용자가 로그아웃하거나 모든 추적 속성을 재설정해야 할 때 모든 전역 속성을 한 번에 제거합니다.

JavaScript 
// Remove all global properties
cordova.plugins.SingularCordovaSdk.clearGlobalProperties();

메서드 서명: 

clearGlobalProperties(): void

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

구현 예시

전체 사용 패턴

적절한 오류 처리 및 로그인/로그아웃 관리를 통해 애플리케이션 수명 주기 전반에 걸쳐 앱 수준 및 사용자별 속성을 추적하세요.

JavaScript 
document.addEventListener('deviceready', initializeApp, false);

function initializeApp() {
  // Set app-level global properties before initialization
  var config = new cordova.plugins.SingularCordovaSdk.SingularConfig(
    'YOUR_SDK_KEY',
    'YOUR_SDK_SECRET'
  );
  
  config.withGlobalProperty('app_version', '1.2.3', true);
  config.withGlobalProperty('platform', 'cordova', true);
  
  // Initialize SDK
  cordova.plugins.SingularCordovaSdk.init(config);
}

// Set user-specific properties on login
function handleUserLogin(userId, userTier) {
  // Set third-party identifier
  cordova.plugins.SingularCordovaSdk.setGlobalProperty(
    'third_party_id',
    userId,
    true,
    function(success) {
      if (success) {
        // Set user tier property
        cordova.plugins.SingularCordovaSdk.setGlobalProperty('user_tier', userTier, true, function(tierSuccess) {
          if (tierSuccess) {
            console.log('User properties set successfully');
          }
        });
      } else {
        console.error('Failed to set user properties');
      }
    }
  );
}

// Update dynamic properties during gameplay
function handleLevelUp(newLevel) {
  cordova.plugins.SingularCordovaSdk.setGlobalProperty(
    'player_level',
    newLevel.toString(),
    true,
    function(success) {
      if (success) {
        // Track level up event
        cordova.plugins.SingularCordovaSdk.eventWithArgs('level_up', {
          new_level: newLevel
        });
      }
    }
  );
}

// Clear user-specific properties on logout
function handleUserLogout() {
  // Remove user-specific properties
  cordova.plugins.SingularCordovaSdk.unsetGlobalProperty('third_party_id');
  cordova.plugins.SingularCordovaSdk.unsetGlobalProperty('user_tier');
  cordova.plugins.SingularCordovaSdk.unsetGlobalProperty('player_level');
  
  console.log('User properties cleared');
}

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

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