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.

// Initialize SDK with global properties
var config = new cordova.plugins.SingularCordovaSdk.SingularConfig(
  'YOUR_SDK_KEY',
  'YOUR_SDK_SECRET'
);

// Set app-level global properties before initialization
config.withGlobalProperty('app_version', '1.2.3', true);
config.withGlobalProperty('user_type', 'free', true);

// Initialize SDK with global properties
cordova.plugins.SingularCordovaSdk.init(config);

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

// Set a global property after initialization
function updatePlayerLevel(level) {
  cordova.plugins.SingularCordovaSdk.setGlobalProperty(
    'player_level',
    level.toString(),
    true,
    function(success) {
      if (success) {
        console.log('Global property set successfully');
      } else {
        console.error('Failed to set property - may have reached 5 property limit');
      }
    }
  );
}

Method Signature:

setGlobalProperty(key: string, value: string, overrideExisting: boolean, success: Function): void

Parameters:

• key: Property name (max 200 characters)
• value: Property value (max 200 characters)
• overrideExisting: Whether to override an existing property with the same key
• success: Callback function that receives true if the property was set successfully, false otherwise

Get Global Properties

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

// Retrieve all global properties
function displayGlobalProperties() {
  cordova.plugins.SingularCordovaSdk.getGlobalProperties(function(properties) {
    // Iterate through properties
    for (var key in properties) {
      if (properties.hasOwnProperty(key)) {
        console.log('Property: ' + key + ' = ' + properties[key]);
      }
    }
  });
}

Method Signature:

getGlobalProperties(success: Function): void

Parameters:

• success: Callback function that receives 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.

// Remove a specific global property
cordova.plugins.SingularCordovaSdk.unsetGlobalProperty('player_level');

Method Signature:

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.

// Remove all global properties
cordova.plugins.SingularCordovaSdk.clearGlobalProperties();

Method Signature:

clearGlobalProperties(): void

Implementation Example

Complete Usage Pattern

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

document.addEventListener('deviceready', initializeApp, false);

function initializeApp() {
  // Set app-level global properties before initialization
  var config = new cordova.plugins.SingularCordovaSdk.SingularConfig(
    'YOUR_SDK_KEY',
    'YOUR_SDK_SECRET'
  );
  
  config.withGlobalProperty('app_version', '1.2.3', true);
  config.withGlobalProperty('platform', 'cordova', true);
  
  // Initialize SDK
  cordova.plugins.SingularCordovaSdk.init(config);
}

// Set user-specific properties on login
function handleUserLogin(userId, userTier) {
  // Set third-party identifier
  cordova.plugins.SingularCordovaSdk.setGlobalProperty(
    'third_party_id',
    userId,
    true,
    function(success) {
      if (success) {
        // Set user tier property
        cordova.plugins.SingularCordovaSdk.setGlobalProperty('user_tier', userTier, true, function(tierSuccess) {
          if (tierSuccess) {
            console.log('User properties set successfully');
          }
        });
      } else {
        console.error('Failed to set user properties');
      }
    }
  );
}

// Update dynamic properties during gameplay
function handleLevelUp(newLevel) {
  cordova.plugins.SingularCordovaSdk.setGlobalProperty(
    'player_level',
    newLevel.toString(),
    true,
    function(success) {
      if (success) {
        // Track level up event
        cordova.plugins.SingularCordovaSdk.eventWithArgs('level_up', {
          new_level: newLevel
        });
      }
    }
  );
}

// Clear user-specific properties on logout
function handleUserLogout() {
  // Remove user-specific properties
  cordova.plugins.SingularCordovaSdk.unsetGlobalProperty('third_party_id');
  cordova.plugins.SingularCordovaSdk.unsetGlobalProperty('user_tier');
  cordova.plugins.SingularCordovaSdk.unsetGlobalProperty('player_level');
  
  console.log('User properties cleared');
}