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.

Setting an attribute

The custom 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.
Changes will NOT be persisted until you call this method, please make sure you call it!

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 inalid 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].

// 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.
BatchUser.instance.newEditor()
      .setIntegerAttribute("age", 26)
      .setStringAttribute("name", "patricia")
      .save(); // Don't forget to save the changes

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

Removing one or multiple attributes

Use removeAttribute to remove one attribute and clearAttributes to remove them all.

BatchUser.instance.newEditor()
  .removeAttribute("age") // Remove an attribute
  .clearAttributes() // Remove all attributes
  .save()

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:

BatchUserDataEditor editor = BatchUser.instance.newEditor();

editor.addTag("actions", "has_bought") // Add a tag to the "actions" collection
editor.removeTag("actions", "has_bought") // Remove it

editor.clearTagCollection("actions") // Removes all tags from that collection
// editor.clearTags() // Removes all tag collections and tags

editor.save(); // Don't forget to save the changes

Reading attributes and tag collections

Attributes and tag collections previously set can be read back.

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;