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.

Custom attributes

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

Setting an attribute

The profile attribute API works using an editor. You need to get an instance of the editor, enqueue your changes by either holding a reference to the editor, or by using it as a builder, and then call save.

Attributes are a key-value system, with attribute keys being strings. Attribute keys (names) should be made of letters, numbers or underscores ([a-z0-9_]) and can't be longer than 30 characters (e.g. has_premium). Any attribute with an invalid key or value will be ignored.

The following attribute setters are available, depending on the type of the value you want to set:

• setBooleanAttribute

• setIntegerAttribute

• setDoubleAttribute

• setDateTimeAttribute

  • Dates must be UTC.

• setStringAttribute

  • Strings must not be longer than 64 characters and can be empty. For better results, you should make them upper/lowercase and trim the whitespaces.

• setUrlAttribute

  • Even though this uses Dart's Uri classes, the value must not be longer than 2048 characters and must follow the format scheme://[authority][path][?query][#fragment].

• setStringListAttribute

  • The list must not be longer than 25 items, only values of type String and must respect the string attribute limitations.

• addToArray

  • The list must not be longer than 25 items, only values of type String and must respect the string attribute limitations.

// Get a new editor instance.
// Editor instances don't share changes, and calling save on an empty editor will do nothing:
// either store the instance or use it like a builder by chaining calls.
BatchProfile.instance.newEditor()
      .setIntegerAttribute("age", 26) // Set a new integer attribute
      .setStringAttribute("name", "patricia") // Set a new string attribute
      .setStringListAttribute('actions', ['added_to_cart', 'has_bought']) // Set a new string list (Array) attribute.
      .addToArray("actions", ["added_to_cart", "has_bought"]) // Add item(s) to an existing string list (Array) attribute.
      .save(); // Don't forget to save the changes

Please test your implementation using our debug tool or profile view before releasing your app on the store. Make sure you're unwrapping your optionals!

Removing one or multiple attributes

Use removeAttribute or removeFromArray to remove an attribute or remove items from an existing attribute.

BatchUser.instance.newEditor()
  .removeAttribute("age") // Remove an attribute
  .removeFromArray("actions", "has_bought") // Remove an item from an existing attribute of type Array
  .save()

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 a map
// Values are encapsulated in an instance of BatchUserAttribute
Map<String, BatchUserAttribute> attributes = await BatchUser.instance.attributes;

BatchUserAttribute age = attributes["age"]!;
// BatchUserAttribute holds a reference to the value of the attribute
dynamic rawValue = age.value; // Raw value is not typed

// The type of the value is specified using the BatchUserAttributeType enumeration
print(age.type.toString()); // Prints "BatchUserAttributeType.integer"

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

Reading tag collections

// Tags are also retrieved in the form of a map
// Keys are names of collections, values are lists of tags
Map<String, List<String>> tagCollections = await BatchUser.instance.tagCollections;

Clearing installation data

Installation data can be cleared as following:

import { BatchUser } from '@batch.com/react-native-plugin';

BatchUser.clearInstallationData();

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