文件

设置全局属性

定义自定义属性，这些属性会自动附加到应用程序发送的每个会话和事件，从而在报告中实现详细的数据细分。

全局属性可让您跟踪任何用户、应用模式或您需要的上下文信息。例如，在一个游戏应用程序中，创建一个初始化为 "0 "的 "级别 "属性，该属性会随着用户的进度而更新。所有会话和事件都包含该属性，这样就可以按用户级别分析会话、事件计数和收入。

属性规格

限制和持久性

在实施前了解全局属性的限制和持久性行为。

最大属性数：每个应用程序安装最多可定义 5 个全局属性。
持久性：属性会在应用启动之间以其最新值持续存在，直到显式取消设置或应用卸载。
字符限制：属性名和值最长可达 200 个字符。较长的值将自动截断为 200 个字符。
数据可用性：全局属性可在用户级导出和回传中访问。请联系您的 Singular 客户成功经理，了解有关汇总报告支持的最新信息。

在初始化时设置全局属性

在 SDK 初始化前配置

在 SDK 初始化前使用globalProperties 配置属性设置全局属性，以确保它们包含在初始会话中。

由于全局属性会在应用程序启动之间持续存在，因此可能已经存在不同值的属性。在SingularGlobalProperty 构造函数中使用overrideExisting参数来控制新值是否覆盖现有值。

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

SingularGlobalProperty 构造函数：

SingularGlobalProperty(String key, String value, bool overrideExisting)

参数：

key：属性名称（最多 200 个字符）
value: 属性值（最多 200 个字符属性值（最多 200 个字符）
overrideExisting（覆盖现有属性是否覆盖具有相同键的现有属性

初始化后管理属性

设置全局属性

在应用程序运行期间的任何时刻，使用setGlobalProperty() 添加或更新全局属性。

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 参数决定是否替换现有属性值。
在初始化或运行时设置的属性具有相同的持久化行为。

示例更新用户操作上的属性

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');
}

获取全局属性

以地图形式读取当前设置的所有全局属性及其值。

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()

返回值： Future ，解析为包含所有全局属性键值对的Map<String, String> 。

取消设置全局属性

当不再需要跟踪某一维度时，通过键值移除该特定全局属性。

import 'package:singular_flutter_sdk/singular.dart';

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

方法签名：

static void unsetGlobalProperty(String key)

参数：

key：要移除的属性名称

示例清除注销时的用户属性

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');
}

清除所有全局属性

一次性删除所有全局属性，通常是在用户注销或需要重置所有跟踪属性时。

import 'package:singular_flutter_sdk/singular.dart';

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

方法签名：

static void clearGlobalProperties()

最佳实践：当用户注销或需要将所有自定义跟踪属性重置为默认状态时，请使用clearGlobalProperties()。这在多用户场景中尤其有用，因为不同用户可能在同一设备上登录。

实施示例

完整使用模式

在登录和注销流程中进行适当管理，在整个应用生命周期内跟踪应用级和特定用户的属性。

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：最近一次应用内购买的日期
engagement_score：计算的参与度指标

电子商务应用程序

跟踪客户细分、忠诚度状态和购物偏好，以个性化营销活动。

loyalty_tier：客户忠诚度计划级别
首选类别：浏览次数最多的产品类别
cart_status：用户购物车中是否有商品
life_value_bucket：分类总支出（低、中、高）

内容/媒体应用程序

跟踪内容偏好、订阅状态和参与模式，以进行内容推荐和保留。

订阅类型：免费、高级或家庭计划
内容偏好：主要感兴趣的内容类别
下载质量：用户首选的流媒体质量
watch_time_bucket：分类的每日观看时间

属性限制管理：全局属性最多 5 个，优先考虑对分析最有价值的跟踪维度。如果达到上限，请考虑在添加新属性前删除不太重要的属性。仔细规划属性策略，最大限度地提高洞察力。

Flutter SDK - 设置全局属性

设置全局属性

属性规格

限制和持久性

在初始化时设置全局属性

在 SDK 初始化前配置

初始化后管理属性

设置全局属性

示例更新用户操作上的属性

获取全局属性

取消设置全局属性

示例清除注销时的用户属性

清除所有全局属性

实施示例

完整使用模式

常见用例

游戏应用程序

电子商务应用程序

内容/媒体应用程序