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 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.
Number
Boolean
Date, Since timezones are not supported, this will typically represent UTC dates.
URL, Must not be longer than 2048 characters and must follow the format scheme://[authority][path][?query][#fragment].
Array<String>, not longer than 25 items, only values of type String and must respect the string attribute limitations.

Methods

The profile attribute API is pretty straightforward:

batch.profile.getEditor()
    .setAttribute("age", 26) // Set a Number attribute
    .setAttribute("birdthday", new Date(Date.UTC(1979, 3, 30))) // Set a Date attribute
    .setAttribute("url", new URL("https://batch.com")) // Set an URL Attribute
    .removeAttribute("age") // Remove an attribute
    .setAttribute('actions', ['added_to_cart', 'has_bought']) // Set an array attribute
    .addToArray("actions", ["added_to_cart", "has_bought"]) // Add list of strings to an array attribute. You can also add just a string.
    .removeFromArray("actions", ["added_to_cart", "has_bought"]) // Remove a list of strings to an array attribute. You can also remove just a string.
    .save(); // Don't forget to save the changes!

You might be tempted to write helpers or loops that open and save many transactions in a row, with each transaction only doing one operation.
Doing so prevents Batch from optimizing disk usage and network roundtrips, which impact your user's data plan and battery life.
Please try to batch as many operations as you can in a single transaction.

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

// Attributes are retrieved in the form of an object
// Values are encapsulated in an instance of BatchUserAttribute
// Attributes is of type { [key: string]: BatchUserAttribute }
let attributes = await batch.user.getAttributes();

// age if of type BatchUserAttribute
const age = attributes["age"];
// BatchUserAttribute holds a reference to the value of the attribute
const rawValue = age.getValue(); // Raw value is not typed

// The type of the value is specified using the BatchUserAttributeType enumeration
console.log(age.getType() === batch.user.BatchUserAttributeType.INTEGER); // Prints true

// To obtain a typed result you can use one of the three helper methods, which returns undefined if there is a type mismatch
age.getNumblerValue(); // Will return "26" here
age.getBooleanValue();   // Will return undefined here
age.getDateValue(); // Will return undefined here
age.getStringValue(); // Will return undefined here

Reading tag collections

// Tags are also retrieved in the form of an object
// Keys are names of collections, values are lists of tags
// TagCollections if of type  [key: string]: string[] }
let tagCollections = await batch.user.getTagCollections();

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.

Documentation > Cordova > Custom data