Attributes

In addition of overriding the language/region or setting a custom user ID, you can assign tags and attributes to your users, allowing you to improve your Push targeting.

Custom attributes

IMPORTANT
- User IDs (email address, username, etc) must be managed using our custom user ID 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

1.18 java.util.URI. Must not be longer than 2048 characters and must follow the format scheme://[authority][path][?query][#fragment].

Methods

The custom attribute API is simple, and has only three methods:

// 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.User.editor()
    .setAttribute("age", 26) // Set an attribute
    .removeAttribute("age") // Remove it
    .clearAttributes() // Removes all attributes
    .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.

Changes made to an editor happen transactionally and won't be persisted until you call save. Note that this MUST be called when Batch is started.

On Android, it means that any Batch.User.editor() call must happen between Batch.onStart() and Batch.onStop() or Batch.onServiceCreate() and Batch.onServiceDestroy(). Alternatively, if you use the automatic integration and don't have Batch.onStart() and related methods, simply call this after super.onStart(). Calling it anywhere else will fail, and an error will be printed to your logcat.

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

Managing tag collections

You can attach multiple tags to different collections. Collections names can't be longer than 30 characters (e.g. favorite_categories).

Tags have some limitations:

  • They are strings.
  • They will automatically be lowercased
  • Their size can't be greater than 64 characters and they can't be empty.

Collection names have the same limitations as attribute names.

Here are the available methods:

Batch.User.editor()
    .addTag("actions", "has_bought") // Add a tag to the "actions" collection
    .removeTag("actions", "has_bought") // Remove it
    .clearTagCollection("actions") // Removes all tags from that collection
    //.clearTags() // Removes all tag collections and tags
    .save(); // Don't forget to save the changes!

Reading attributes and tag collections

Since Batch 1.14, two class methods of Batch.User are available to asynchronously fetch saved attributes and tag collections.

Reading attributes

Batch.User.fetchAttributes(context, new BatchAttributesFetchListener() {
    @Override
    public void onSuccess(Map<String, BatchUserAttribute> attributes)
    {
        // Attributes are retrieved in the form of a map
        // Values are encapsulated in an instance of BatchUserAttribute
        BatchUserAttribute attribute = attributes.get("age");

        // BatchUserAttribute holds a reference to the value of the attribute
        Object 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); // 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
    public void onError()
    {
        // Callback method called on error 
    }
});

Reading tag collections

Batch.User.fetchTagCollections(contact, new BatchTagCollectionsFetchListener() {
    @Override
    public void onSuccess(Map<String, Set<String>> tagCollections)
    {
        // Tags are also retrieved in the form of a map
        // Keys are names of collections, values are sets of tags
        Set<String> tagCollection = tagCollections.get("actions");
        Log.i("attr", tagCollection); // Prints "["has_bought"]"
    }

    @Override
    public void 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.