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 via SingularConfig

Set global properties during SDK initialization using the setGlobalProperty method before calling Singular.start() .

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.

func getConfig() -> SingularConfig? {
    // Create config with API credentials
    guard let config = SingularConfig(apiKey: "SDK_KEY", andSecret: "SDK_SECRET") else {
        return nil
    }
    
    // Set global properties during initialization
    config.setGlobalProperty("MyProperty", withValue: "MyValue", overrideExisting: true)
    config.setGlobalProperty("AnotherProperty", withValue: "AnotherValue", overrideExisting: true)
    
    return config
}

// Initialize SDK with config
if let config = getConfig() {
    Singular.start(config)
}

- (SingularConfig *)getConfig {
    // Create config with API credentials
    SingularConfig *config = [[SingularConfig alloc] initWithApiKey:@"SDK_KEY" 
        andSecret:@"SDK_SECRET"];
    
    // Set global properties during initialization
    [config setGlobalProperty:@"MyProperty" withValue:@"MyValue" overrideExisting:YES];
    [config setGlobalProperty:@"AnotherProperty" withValue:@"AnotherValue" overrideExisting:YES];
    
    return config;
}

// Initialize SDK with config
SingularConfig *config = [self getConfig];
[Singular start:config];

Method Signature:

- (void)setGlobalProperty:(NSString *)key withValue:(NSString *)value overrideExisting:(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
let result = Singular.setGlobalProperty("MyProperty", 
    andValue: "MyValue", 
    overrideExisting: true)

if result {
    print("Property set successfully")
} else {
    print("Failed to set property")
}

// Set a global property after initialization
BOOL result = [Singular setGlobalProperty:@"MyProperty" 
    andValue:@"MyValue" 
    overrideExisting:YES];

if (result) {
    NSLog(@"Property set successfully");
} else {
    NSLog(@"Failed to set property");
}

Method Signature:

+ (BOOL)setGlobalProperty:(NSString *)key andValue:(NSString *)value overrideExisting:(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
let properties = Singular.getGlobalProperties()

// Iterate through properties
if let properties = properties as? [String: String] {
    for (key, value) in properties {
        print("Property: \(key) = \(value)")
    }
}

// Retrieve all global properties
NSDictionary *properties = [Singular getGlobalProperties];

// Iterate through properties
for (NSString *key in properties) {
    NSString *value = properties[key];
    NSLog(@"Property: %@ = %@", key, value);
}

Method Signature:

+ (NSDictionary *)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
Singular.unsetGlobalProperty("MyProperty")

// Remove a specific global property
[Singular unsetGlobalProperty:@"MyProperty"];

Method Signature:

+ (void)unsetGlobalProperty:(NSString *)key;

Parameters:

• key: The name of the property to remove

Clear All Global Properties

Remove all global properties at once.

// Remove all global properties
Singular.clearGlobalProperties()

// Remove all global properties
[Singular clearGlobalProperties];

Method Signature:

+ (void)clearGlobalProperties;

Implementation Example

Complete Usage Pattern

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

// Initialize SDK with app-level global properties
func getConfig() -> SingularConfig? {
    guard let config = SingularConfig(apiKey: "SDK_KEY", andSecret: "SDK_SECRET") else {
        return nil
    }
    
    // Set app version as a global property
    if let appVersion = Bundle.main.infoDictionary?["CFBundleShortVersionString"] as? String {
        config.setGlobalProperty("app_version", withValue: appVersion, overrideExisting: true)
    }
    
    return config
}

// Set third-party identifier on login
func onUserLogin(thirdPartyUserId: String) {
    let success = Singular.setGlobalProperty("third_party_identifier", 
        andValue: thirdPartyUserId, 
        overrideExisting: true)
    
    if success {
        print("Third-party identifier set")
    }
}

// Clear third-party identifier on logout
func onUserLogout() {
    Singular.unsetGlobalProperty("third_party_identifier")
    print("Third-party identifier cleared")
}

// Initialize SDK with app-level global properties
- (SingularConfig *)getConfig {
    SingularConfig *config = [[SingularConfig alloc] initWithApiKey:@"SDK_KEY" 
        andSecret:@"SDK_SECRET"];
    
    // Set app version as a global property
    NSString *appVersion = [[NSBundle mainBundle] infoDictionary][@"CFBundleShortVersionString"];
    if (appVersion) {
        [config setGlobalProperty:@"app_version" withValue:appVersion overrideExisting:YES];
    }
    
    return config;
}

// Set third-party identifier on login
- (void)onUserLogin:(NSString *)thirdPartyUserId {
    BOOL success = [Singular setGlobalProperty:@"third_party_identifier" 
        andValue:thirdPartyUserId 
        overrideExisting:YES];
    
    if (success) {
        NSLog(@"Third-party identifier set");
    }
}

// Clear third-party identifier on logout
- (void)onUserLogout {
    [Singular unsetGlobalProperty:@"third_party_identifier"];
    NSLog(@"Third-party identifier cleared");
}