文件

设置全局属性

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

全局属性可让您跟踪任何用户、应用模式或您需要的上下文信息。例如，在一个游戏应用程序中，创建一个初始化为 "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 个字符）
value：属性值（最多 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>>

返回值：解析为包含所有全局属性键值对的对象的 Promise

取消设置全局属性

当你不再需要跟踪某个特定的全局属性时，按其键值删除该属性。

// 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 初始化前配置

初始化后管理属性

设置全局属性

获取全局属性

取消设置全局属性

清除所有全局属性

实现示例

完整使用模式