Setting Global Properties

The Singular SDK lets you define custom properties to be sent to the Singular servers along with every session and event sent from the app. These properties can represent any information you want about the user, the app mode/status, or anything else.

You can define up to 5 global properties. They persist between app runs (with the latest value you gave them) until you unset them or the user uninstalls the app.

Use Cases

Some use cases for global properties are:

• Pass an identifier from a third-party SDK and then use it in a postback from Singular to said third party for matching purposes.
• In a gaming app, you can define a property called "Level" and set it initially to "0". Any session and event sent from the app will be sent with "Level": "0". Once the user levels up, you reset the property to "1" and so on.

Setting Global Properties through the Config Object

To set global properties before initializing the SDK, use the setGlobalProperty method in the Config object.

Note that since global properties and their values persist between app runs, the property you are setting may already be set to a different value. Use the overrideExisting parameter to tell the SDK whether to override an existing property with the new value or not.

func getConfig() -> SingularConfig? {         
  // (Optional) Get 3rd-party identifiers to set in Global Properties:     

  // If 3rd-party SDKs are providing any identifiers to Singular, the

  // respective SDK must be initialized before Singular.     

  let thirdPartyKey = "anonymousID"     
  let thirdPartyID = "2ed20738-059d-42b5-ab80-5aa0c530e3e1"     
  
  // Singular Config Options     

  guard let config = SingularConfig(apiKey: Constants.APIKEY, 
    andSecret: Constants.SECRET) else {
      return nil
      }
  //...     
  // Using Singular Global Properties feature to capture third party identifiers

  config.setGlobalProperty(thirdPartyKey, withValue: thirdPartyID, overrideExisting: true)     
  //...
  return config 
}

- (SingularConfig *)getConfig {     
  // (Optional) Get 3rd-party identifiers to set in Global Properties:     

  // If 3rd-party SDKs are providing any identifiers to Singular, the

  // respective SDK must be initialized before Singular.     

  NSString* thirdPartyKey = @"anonymousID";
  NSString* thirdPartyID = @"2ed20738-059d-42b5-ab80-5aa0c530e3e1";     
  
  // Singular Config Options     

  SingularConfig* config = [[SingularConfig alloc] initWithApiKey:APIKEY 
    andSecret:SECRET];
  //...
  
  // Using Singular Global Properties feature to capture 3rd-party identifiers     

  [config setGlobalProperty:thirdPartyKey withValue:thirdPartyID overrideExisting:YES];
  //...
  return config;
}

Setting Global Properties After Initialization

Use the following methods to set, unset, and retrieve global properties at any time in the app's run.

var result = Singular.setGlobalProperty("propertyName",
  andValue: "propertyValue", overrideExisting: true)

BOOL result = [Singular setGlobalProperty:@"propertyName"
  andValue:@"propertyValue" overrideExisting:YES];

var globalProperties = Singular.getGlobalProperties()

NSDictionary* globalProperties = [Singular getGlobalProperties];

Singular.unsetGlobalProperty("propertyName")

[Singular unsetGlobalProperty:@"propertyName"];

Singular.clearGlobalProperties()

[Singular clearGlobalProperties];