Flutter SDK - 글로벌 속성 설정

팔로우
Avatar
Jared Ornstead
Updated
문서

전역 속성 설정

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

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

속성 사양

제한 및 지속성

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

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

초기화 시 글로벌 속성 설정

SDK 초기화 전 구성

SDK 초기화 전에 globalProperties 구성 속성을 사용하여 전역 속성을 설정하여 초기 세션에 포함되도록 하세요.

글로벌 프로퍼티는 앱 실행 간에 유지되므로 프로퍼티가 이미 다른 값으로 존재할 수 있습니다. SingularGlobalProperty 생성자에서 overrideExisting파라미터를 사용하여 새 값이 기존 값을 재정의할지 여부를 제어하세요.

Dart 
import 'package:flutter/material.dart';
import 'package:singular_flutter_sdk/singular.dart';
import 'package:singular_flutter_sdk/singular_config.dart';
import 'package:singular_flutter_sdk/singular_global_property.dart';

void main() {
  runApp(MyApp());
}

class MyApp extends StatefulWidget {
  @override
  _MyAppState createState() => _MyAppState();
}

class _MyAppState extends State<MyApp> {
  @override
  void initState() {
    super.initState();
    initializeSDK();
  }

  void initializeSDK() {
    // Create configuration with global properties
    SingularConfig config = SingularConfig(
      'YOUR_SDK_KEY',
      'YOUR_SDK_SECRET'
    );

    // Set app-level global properties before initialization
    config.globalProperties = [
      SingularGlobalProperty('app_version', '1.2.3', true),
      SingularGlobalProperty('platform', 'flutter', true)
    ];

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

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Flutter Demo',
      home: MyHomePage(),
    );
  }
}

구성 속성: 

List<SingularGlobalProperty> globalProperties

Singular글로벌프로퍼티 생성자: 

SingularGlobalProperty(String key, String value, bool overrideExisting)

매개변수:

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

초기화 후 프로퍼티 관리

글로벌 프로퍼티 설정

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

Dart 
import 'package:singular_flutter_sdk/singular.dart';

// Set a global property after initialization
void updatePlayerLevel(int level) {
  Singular.setGlobalProperty(
    'player_level',
    level.toString(),
    true
  );

  print('Global property set: player_level = $level');
}

메서드 서명: 

static void setGlobalProperty(String key, String value, bool overrideExisting)

중요:

  • 이미 5개의 프로퍼티가 있는데 다른 키로 새 프로퍼티를 추가하려고 하면 SDK에서 추가하지 않습니다.
  • overrideExisting 매개 변수는 기존 속성 값을 대체할지 여부를 결정합니다.
  • 초기화 중 또는 런타임에 설정된 프로퍼티는 동일한 지속성 동작을 갖습니다.

예시: 사용자 작업 시 속성 업데이트

Dart 
import 'package:singular_flutter_sdk/singular.dart';

// Example: Track user subscription tier
void handleSubscriptionChange(String tier) {
  // Update global property
  Singular.setGlobalProperty('subscription_tier', tier, true);

  // Track the subscription event
  Singular.eventWithArgs('subscription_changed', {
    'new_tier': tier,
    'timestamp': DateTime.now().toIso8601String()
  });

  print('Subscription tier updated: $tier');
}

전역 속성 가져오기

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

Dart 
import 'package:singular_flutter_sdk/singular.dart';

// Retrieve all global properties
Future<void> displayGlobalProperties() async {
  Map<String, String> properties = await Singular.getGlobalProperties();

  // Iterate through properties
  properties.forEach((key, value) {
    print('Property: $key = $value');
  });

  // Check if specific property exists
  if (properties.containsKey('player_level')) {
    print('Current player level: ${properties['player_level']}');
  }
}

메서드 서명: 

static Future<Map<String, String>> getGlobalProperties()

반환합니다: 모든 전역 속성 키-값 쌍이 포함된 Map<String, String> 으로 해석되는 Future.

글로벌 프로퍼티 설정 해제

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

Dart 
import 'package:singular_flutter_sdk/singular.dart';

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

메서드 서명: 

static void unsetGlobalProperty(String key)

매개변수:

  • key: 제거할 속성의 이름

예시: 로그아웃 시 사용자 속성 지우기

Dart 
import 'package:singular_flutter_sdk/singular.dart';

// Clear user-specific properties on logout
void handleUserLogout() {
  // Remove user-specific properties
  Singular.unsetGlobalProperty('subscription_tier');
  Singular.unsetGlobalProperty('player_level');
  Singular.unsetGlobalProperty('user_segment');

  // Also clear custom user ID
  Singular.unsetCustomUserId();

  print('User properties cleared on logout');
}

모든 전역 속성 지우기

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

Dart 
import 'package:singular_flutter_sdk/singular.dart';

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

메서드 서명: 

static void clearGlobalProperties()

모범 사례: 사용자가 로그아웃하거나 모든 사용자 지정 추적 속성을 기본 상태로 재설정해야 하는 경우 clearGlobalProperties()을 사용합니다. 이 방법은 여러 사용자가 동일한 디바이스에서 로그인하는 다중 사용자 시나리오에서 특히 유용합니다.

구현 예시

전체 사용 패턴

로그인 및 로그아웃 흐름 동안 적절한 관리를 통해 애플리케이션 라이프사이클 전반에 걸쳐 앱 수준 및 사용자별 속성을 추적하세요.

Dart 
import 'package:flutter/material.dart';
import 'package:singular_flutter_sdk/singular.dart';
import 'package:singular_flutter_sdk/singular_config.dart';
import 'package:singular_flutter_sdk/singular_global_property.dart';

void main() {
  runApp(MyApp());
}

class MyApp extends StatefulWidget {
  @override
  _MyAppState createState() => _MyAppState();
}

class _MyAppState extends State<MyApp> {
  @override
  void initState() {
    super.initState();
    initializeSDK();
  }

  void initializeSDK() {
    // Set app-level global properties before initialization
    SingularConfig config = SingularConfig(
      'YOUR_SDK_KEY',
      'YOUR_SDK_SECRET'
    );

    config.globalProperties = [
      SingularGlobalProperty('app_version', '1.2.3', true),
      SingularGlobalProperty('platform', 'flutter', true)
    ];

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

  // Set user-specific properties on login
  void handleUserLogin(String userId, String userTier) {
    // Set custom user ID
    Singular.setCustomUserId(userId);

    // Set user tier property
    Singular.setGlobalProperty('user_tier', userTier, true);

    // Set initial player level
    Singular.setGlobalProperty('player_level', '1', true);

    print('User properties set successfully');
  }

  // Update dynamic properties during gameplay
  void handleLevelUp(int newLevel) {
    // Update player level property
    Singular.setGlobalProperty('player_level', newLevel.toString(), true);

    // Track level up event
    Singular.eventWithArgs('level_up', {
      'new_level': newLevel.toString(),
      'timestamp': DateTime.now().millisecondsSinceEpoch.toString()
    });

    print('Level updated to $newLevel');
  }

  // Update subscription status
  void handleSubscriptionPurchase(String tier) {
    // Update subscription tier
    Singular.setGlobalProperty('subscription_tier', tier, true);

    // Track subscription event
    Singular.customRevenue('subscription_purchase', 'USD', 9.99);

    print('Subscription tier updated: $tier');
  }

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

    // Clear custom user ID
    Singular.unsetCustomUserId();

    print('User properties cleared on logout');
  }

  // Alternative: Clear all properties at once
  void handleCompleteReset() {
    // Remove all global properties
    Singular.clearGlobalProperties();

    // Clear custom user ID
    Singular.unsetCustomUserId();

    print('All properties and user ID cleared');
  }

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Flutter Demo',
      home: MyHomePage(),
    );
  }
}

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

일반적인 사용 사례

게임 앱

플레이어의 진행 상황, 참여도, 구매화 티어를 추적하여 사용자를 세분화하고 캠페인을 최적화하세요.

  • player_level: 게임 내 현재 레벨 또는 스테이지
  • VIP_STATUS: 프리미엄 멤버십 티어(무료, 실버, 골드)
  • last_purchase_date: 가장 최근의 인앱 구매 날짜
  • 참여 점수: 계산된 참여 지표

이커머스 앱

고객 세그먼트, 충성도 상태, 쇼핑 선호도를 추적하여 마케팅 캠페인을 맞춤화하세요.

  • 로열티_티어: 고객 충성도 프로그램 수준
  • 선호 카테고리: 가장 많이 검색한 제품 카테고리
  • cart_status: 사용자가 장바구니에 상품을 보유하고 있는지 여부
  • lifetime_value_bucket: 분류된 총 비용액(낮음, 중간, 높음)

콘텐츠/미디어 앱

콘텐츠 추천 및 리텐션을 위해 콘텐츠 선호도, 구독 상태, 참여 패턴을 추적하세요.

  • 구독 유형: 무료, 프리미엄 또는 가족 요금제
  • content_preference: 주요 콘텐츠 카테고리 관심사
  • 다운로드_품질: 사용자가 선호하는 스트리밍 품질
  • watch_time_bucket: 분류된 일일 시청 시간

속성 제한 관리: 최대 5개의 글로벌 속성을 사용하여 분석에 가장 중요한 추적 기준에 우선순위를 지정하세요. 한도에 도달하면 새 속성을 추가하기 전에 덜 중요한 속성을 제거하는 것이 좋습니다. 인사이트를 극대화하려면 속성 전략을 신중하게 계획하세요.