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.

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

using UnityEngine;
using Singular;

public class SingularInitializer : MonoBehaviour
{
    void Awake()
    {
        // Set global properties before SDK initialization
        SingularSDK.SetGlobalProperty("app_version", Application.version, true);
        SingularSDK.SetGlobalProperty("user_type", "free", true);

        // Manually initialize SDK to ensure properties are in first session
        SingularSDK.InitializeSingularSDK();
    }
}

Method Signature:

public static bool SetGlobalProperty(string key, string value, bool overrideExisting)

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.

// Set a global property after initialization
bool result = SingularSDK.SetGlobalProperty("player_level", "5", true);

if (result)
{
    Debug.Log("Property set successfully");
}
else
{
    Debug.LogError("Failed to set property - may have reached 5 property limit");
}

Method Signature:

public static bool SetGlobalProperty(string key, string value, bool overrideExisting)

Returns: true if the property was set successfully, false otherwise

Get Global Properties

Retrieve all currently set global properties and their values as a Dictionary.

// Retrieve all global properties
Dictionary<string, string> properties = SingularSDK.GetGlobalProperties();

// Iterate through properties
foreach (KeyValuePair<string, string> property in properties)
{
    Debug.Log($"Property: {property.Key} = {property.Value}");
}

Method Signature:

public static Dictionary<string, string> GetGlobalProperties()

Returns: A Dictionary containing all global property key-value pairs

Unset Global Property

Remove a specific global property by its key.

// Remove a specific global property
SingularSDK.UnsetGlobalProperty("player_level");

Method Signature:

public static void UnsetGlobalProperty(string key)

Parameters:

• key: The name of the property to remove

Clear All Global Properties

Remove all global properties at once.

// Remove all global properties
SingularSDK.ClearGlobalProperties();

Method Signature:

public static void ClearGlobalProperties()

Implementation Example

Complete Usage Pattern

Track app-level and user-specific properties throughout the application lifecycle.

using UnityEngine;
using Singular;

public class GlobalPropertiesManager : MonoBehaviour
{
    void Awake()
    {
        // Set app-level global properties before initialization
        SingularSDK.SetGlobalProperty("app_version", Application.version, true);
        
        // Initialize SDK
        SingularSDK.InitializeSingularSDK();
    }
    
    // Set third-party identifier on login
    public void OnUserLogin(string thirdPartyUserId)
    {
        bool success = SingularSDK.SetGlobalProperty("third_party_identifier", thirdPartyUserId, true);
        
        if (success)
        {
            Debug.Log("Third-party identifier set");
        }
    }
    
    // Clear third-party identifier on logout
    public void OnUserLogout()
    {
        SingularSDK.UnsetGlobalProperty("third_party_identifier");
        Debug.Log("Third-party identifier cleared");
    }
}