Attributes

In addition of setting a custom user ID, an email address or overriding the language/region, you can assign attributes to your users, allowing you to improve your orchestrations targeting.

IMPORTANT
- User IDs must be managed using our custom user ID implementation.
- Email address must be managed using our email subscription implementation.
- Region/language data must be managed using our custom region/language implementation.
- Never use an existing tagging plan. Read our guide on custom data before tagging your app.
- Newly tracked attributes and tags are hidden by default. You will need to manually display them from the dashboard settings > "Custom data" tab.

Managing attributes

Before we get started on how to implement attributes, here are some rules you should know.

Naming

Attribute names are strings. They should be made of letters, numbers or underscores ([a-z0-9_]) and can't be longer than 30 characters (e.g. has_premium).

Values

Values must be any of the following types:

• String, must not be longer than 64 characters and can be empty. For better results, you should make them upper/lowercase and trim the whitespaces.
• Int/long/double
• Boolean
• Date, java.util.Date. Since timezones are not supported, this will typically represent UTC dates.
• URL, java.net.URI. Must not be longer than 2048 characters and must follow the format scheme://[authority][path][?query][#fragment].
• List<String>, not longer than 25 items, only values of type String and must respect the string attribute limitations.

Methods

The custom attribute API is quite simple :

// This method returns a NEW editor instance every call. Make sure you chain calls or store the editor
// in a local variable before calling save. Calling save() on an empty editor will do nothing.
Batch.Profile.editor().apply {
   setAttribute("age", 26) // Set an attribute
   removeAttribute("age") // Remove an attribute
   addToArray("actions", listOf("added_to_cart", "has_bought")) // Add list of strings to an array attribute. You can also add just a string.
   removeFromArray("actions", "has_bought") // Remove a string from a list attribute
   save() // Don't forget to save the changes!
}

Note that this MUST be called when Batch is started.

Please test your implementation using our debug tool and profile view before releasing your app on the store.

Reading attributes and tag collections

Since Batch SDK v2, updating the user's data also update the profile's data to be accessible from your project scope. This mean the following APIs only read local data related to your installation and NOT to your profile.

You may also have noticed that APIs to set Tags or Tag Collections have been removed and replaced by array attributes. These methods are backward-compatible and array attributes are converted into tag collections to not break your implementation.

Reading attributes

Batch.User.fetchAttributes(context, object: BatchAttributesFetchListener {
  override fun onSuccess(attributes: Map<String, BatchUserAttribute>) {
    // Attributes are retrieved in the form of a map
    // Values are encapsulated in an instance of BatchUserAttribute
    val attribute = attributes["age"]

    // BatchUserAttribute holds a reference to the value of the attribute
    val rawValue = attribute?.value  // Raw value is not typed

    // The type of the value is specified via a BatchUserAttribute.Type enumeration
    Log.i("attr", attribute?.type.toString()) // Prints "BatchUserAttribute.Type.LONGLONG"

    // To obtain a typed result you can use one of the five helper methods
    attribute?.getNumberValue() // Will return "26" here
    attribute?.getDateValue() // Will return null
    attribute?.getBooleanValue() // Will return null
    attribute?.getStringValue() // Will return null
    attribute?.getUriValue() // Will return null
  }
  override fun onError() {
    // Callback method called on error
  }
})

Reading tag collections

Batch.User.fetchTagCollections(context, object : BatchTagCollectionsFetchListener {
  override fun onSuccess(tagCollections: Map<String, Set<String>>) {
    // Tags are also retrieved in the form of a map
    // Keys are names of collections, values are sets of tags
    val tagCollection = tagCollections["actions"]!!
    Log.i("attr", tagCollection.toString()) // Prints "["has_bought"]"
  }

  override fun onError() {
    // Callback method called on error
  }
})

Note: Since tags are limited in size and are case-sensitive, reading them back might produce different results than what had been saved.

Clearing installation data

Installation data can be cleared as following:

Batch.User.clearInstallationData();

Note: This method will clear the installation data on the App scope and will NOT affect the profile related data.