Setting Global Properties

Define custom properties that automatically attach to every session and event sent from your app, enabling detailed data segmentation in reports.

Global properties let you track any user, app mode, or contextual information you need. For example, in a gaming app, create a "Level" property initialized to "0" that updates as users progress. All sessions and events include this property, allowing you to analyze sessions, event counts, and revenue broken down by user level.

Property Specifications

Limits and Persistence

Understand the constraints and persistence behavior of global properties before implementation.

Maximum Properties: Define up to 5 global properties per app installation
Persistence: Properties persist between app launches with their most recent values until explicitly unset or the app is uninstalled
Character Limit: Property names and values can be up to 200 characters long. Longer values are automatically truncated to 200 characters
Data Availability: Global properties are accessible in user-level exports and postbacks. Contact your Singular customer success manager for updates on aggregate reporting support

Setting Global Properties at Initialization

Configure Before SDK Initialization

Set global properties before SDK initialization using withGlobalProperty() to ensure they're included in the initial session.

Since global properties persist between app launches, properties may already exist with different values. Use the overrideExisting parameter to control whether the new value should override existing values.

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

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

Method Signature:

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

Parameters:

key: Property name (max 200 characters)
value: Property value (max 200 characters)
overrideExisting: Whether to override an existing property with the same key

Managing Properties After Initialization

Set Global Property

Add or update a global property at any point during the app's runtime using setGlobalProperty().

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

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

Method Signature:

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

Returns: Promise<boolean> that resolves to true if the property was set successfully, false otherwise

Important:

If 5 properties already exist and you attempt to add a new one, the method returns false
The overrideExisting parameter determines whether to replace existing property values
Always check the return value to confirm the property was set successfully

Get Global Properties

Retrieve all currently set global properties and their values as an object.

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

// 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}`);
  });
}

Method Signature:

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

Returns: A Promise that resolves to an object containing all global property key-value pairs

Unset Global Property

Remove a specific global property by its key when you no longer need to track that dimension.

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

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

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

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

Method Signature:

static unsetGlobalProperty(key: string): void

Parameters:

key: The name of the property to remove

Clear All Global Properties

Remove all global properties at once, typically when a user logs out or you need to reset all tracking properties.

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

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

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

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

Method Signature:

static clearGlobalProperties(): void

Best Practice: Use clearGlobalProperties() when a user logs out or when you need to reset all custom tracking properties to their default state.

Implementation Example

Complete Usage Pattern

Track app-level and user-specific properties throughout the application lifecycle with proper error handling and login/logout management.

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

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

Best Practice: Sync third-party analytics identifiers (e.g., Mixpanel distinct_id, Amplitude user_id) to Singular global properties for unified cross-platform tracking. Set user-specific identifiers on login and clear them with unsetGlobalProperty() on logout. App-level properties like app_version persist across sessions.

Property Limit Management: With a maximum of 5 global properties, prioritize the most valuable tracking dimensions for your analytics. If you reach the limit, consider removing less critical properties before adding new ones. The example above shows how to handle the 5-property limit gracefully by checking return values.

React Native SDK - Setting Global Properties

Setting Global Properties

Property Specifications

Limits and Persistence

Setting Global Properties at Initialization

Configure Before SDK Initialization

Managing Properties After Initialization

Set Global Property

Get Global Properties

Unset Global Property

Clear All Global Properties

Implementation Example

Complete Usage Pattern