문서

전역 속성 설정

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

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

속성 사양

제한 및 지속성

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

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

초기화 시 글로벌 속성 설정

SDK 초기화 전 구성

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

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

// TurboModule direct API (React Native 0.76+ New Architecture)
import React, { useEffect } from 'react';
import NativeSingular from 'singular-react-native/jsNativeSingular';

export default function App() {
  useEffect(() => {
    initializeSDK();
  }, []);

  async function initializeSDK() {
    // Initialize SDK with global properties in config
    const config: SingularConfig = {
      apikey: 'YOUR_SDK_KEY',
      secret: 'YOUR_SDK_SECRET',
      globalProperties: {
        app_version: {
          Key: 'app_version',
          Value: '1.2.3',
          OverrideExisting: true
        },
        user_type: {
          Key: 'user_type',
          Value: 'free',
          OverrideExisting: true
        }
      }
    };

    NativeSingular.init(config);
  }

  return (
    // Your app components
    null
  );
}

import React, { useEffect } from 'react';
import { Singular, SingularConfig } from 'singular-react-native';

export default function App() {
  useEffect(() => {
    initializeSDK();
  }, []);

  async function initializeSDK() {
    // Create configuration with global properties
    const config = new SingularConfig(
      'YOUR_SDK_KEY',
      'YOUR_SDK_SECRET'
    )
      // Set app-level global properties before initialization
      .withGlobalProperty('app_version', '1.2.3', true)
      .withGlobalProperty('user_type', 'free', true);

    // Initialize SDK with global properties
    Singular.init(config);
  }

  return (
    // Your app components
  );
}

메서드 서명:

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

매개변수:

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

초기화 후 프로퍼티 관리

글로벌 프로퍼티 설정

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

// TurboModule direct API (React Native 0.76+ New Architecture)
import NativeSingular from 'singular-react-native/jsNativeSingular';

// Set a global property after initialization
async function updatePlayerLevel(level) {
  const success = await NativeSingular.setGlobalProperty(
    'player_level',
    level.toString(),
    true
  );

  if (success) {
    console.log('Global property set successfully');
  } else {
    console.error('Failed to set property - may have reached 5 property limit');
  }
}

import { Singular } from 'singular-react-native';

// Set a global property after initialization
async function updatePlayerLevel(level) {
  const success = await Singular.setGlobalProperty(
    'player_level',
    level.toString(),
    true
  );

  if (success) {
    console.log('Global property set successfully');
  } else {
    console.error('Failed to set property - may have reached 5 property limit');
  }
}

메서드 서명:

static setGlobalProperty(key: string, value: string, overrideExisting: boolean): Promise<boolean>

반환: Promise<boolean> 프로퍼티가 성공적으로 설정된 경우 true, 그렇지 않은 경우 false 로 확인됩니다.

중요:

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

전역 프로퍼티 가져오기

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

// TurboModule direct API (React Native 0.76+ New Architecture)
import NativeSingular from 'singular-react-native/jsNativeSingular';

// Retrieve all global properties
async function displayGlobalProperties() {
  const properties = await NativeSingular.getGlobalProperties();

  // Iterate through properties
  Object.entries(properties).forEach(([key, value]) => {
    console.log(`Property: ${key} = ${value}`);
  });
}

import { Singular } from 'singular-react-native';

// Retrieve all global properties
async function displayGlobalProperties() {
  const properties = await Singular.getGlobalProperties();

  // Iterate through properties
  Object.entries(properties).forEach(([key, value]) => {
    console.log(`Property: ${key} = ${value}`);
  });
}

메서드 서명:

static getGlobalProperties(): Promise<Record<string, any>>

반환합니다: 모든 전역 프로퍼티 키-값 쌍을 포함하는 객체로 확인되는 프로미스입니다.

글로벌 프로퍼티 설정 해제

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

// TurboModule direct API (React Native 0.76+ New Architecture)
import NativeSingular from 'singular-react-native/jsNativeSingular';

// Remove a specific global property
NativeSingular.unsetGlobalProperty('player_level');

import { Singular } from 'singular-react-native';

// Remove a specific global property
Singular.unsetGlobalProperty('player_level');

메서드 서명:

static unsetGlobalProperty(key: string): void

매개변수:

key: 제거할 속성의 이름

모든 전역 속성 지우기

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

// TurboModule direct API (React Native 0.76+ New Architecture)
import NativeSingular from 'singular-react-native/jsNativeSingular';

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

import { Singular } from 'singular-react-native';

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

메서드 서명:

static clearGlobalProperties(): void

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

구현 예시

전체 사용 패턴

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

// TurboModule direct API (React Native 0.76+ New Architecture)
import React, { useEffect } from 'react';
import NativeSingular from 'singular-react-native/jsNativeSingular';

export default function App() {
  useEffect(() => {
    initializeSDK();
  }, []);

  async function initializeSDK() {
    // Set app-level global properties before initialization
    const config: SingularConfig = {
      apikey: 'YOUR_SDK_KEY',
      secret: 'YOUR_SDK_SECRET',
      globalProperties: {
        app_version: {
          Key: 'app_version',
          Value: '1.2.3',
          OverrideExisting: true
        },
        platform: {
          Key: 'platform',
          Value: 'react-native',
          OverrideExisting: true
        }
      }
    };

    // Initialize SDK
    NativeSingular.init(config);
  }

  // Set user-specific properties on login
  async function handleUserLogin(userId, userTier) {
    // Set third-party identifier
    const success = await NativeSingular.setGlobalProperty(
      'third_party_id',
      userId,
      true
    );

    if (success) {
      // Set user tier property
      await NativeSingular.setGlobalProperty('user_tier', userTier, true);
      console.log('User properties set successfully');
    } else {
      console.error('Failed to set user properties');
    }
  }

  // Update dynamic properties during gameplay
  async function handleLevelUp(newLevel) {
    await NativeSingular.setGlobalProperty('player_level', newLevel.toString(), true);

    // Track level up event
    NativeSingular.eventWithArgs('level_up', {
      new_level: newLevel
    });
  }

  // Clear user-specific properties on logout
  function handleUserLogout() {
    // Remove user-specific properties
    NativeSingular.unsetGlobalProperty('third_party_id');
    NativeSingular.unsetGlobalProperty('user_tier');
    NativeSingular.unsetGlobalProperty('player_level');

    console.log('User properties cleared');
  }

  return (
    // Your app components
    null
  );
}

import React, { useEffect } from 'react';
import { Singular, SingularConfig } from 'singular-react-native';

export default function App() {
  useEffect(() => {
    initializeSDK();
  }, []);

  async function initializeSDK() {
    // Set app-level global properties before initialization
    const config = new SingularConfig(
      'YOUR_SDK_KEY',
      'YOUR_SDK_SECRET'
    )
      .withGlobalProperty('app_version', '1.2.3', true)
      .withGlobalProperty('platform', 'react-native', true);

    // Initialize SDK
    Singular.init(config);
  }

  // Set user-specific properties on login
  async function handleUserLogin(userId, userTier) {
    // Set third-party identifier
    const success = await Singular.setGlobalProperty(
      'third_party_id',
      userId,
      true
    );

    if (success) {
      // Set user tier property
      await Singular.setGlobalProperty('user_tier', userTier, true);
      console.log('User properties set successfully');
    } else {
      console.error('Failed to set user properties');
    }
  }

  // Update dynamic properties during gameplay
  async function handleLevelUp(newLevel) {
    await Singular.setGlobalProperty('player_level', newLevel.toString(), true);

    // Track level up event
    Singular.eventWithArgs('level_up', {
      new_level: newLevel
    });
  }

  // Clear user-specific properties on logout
  function handleUserLogout() {
    // Remove user-specific properties
    Singular.unsetGlobalProperty('third_party_id');
    Singular.unsetGlobalProperty('user_tier');
    Singular.unsetGlobalProperty('player_level');

    console.log('User properties cleared');
  }

  return (
    // Your app components
  );
}

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

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

React Native SDK - 전역 속성 설정하기

전역 속성 설정

속성 사양

제한 및 지속성

초기화 시 글로벌 속성 설정

SDK 초기화 전 구성

초기화 후 프로퍼티 관리

글로벌 프로퍼티 설정

전역 프로퍼티 가져오기

글로벌 프로퍼티 설정 해제

모든 전역 속성 지우기

구현 예시

전체 사용 패턴