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 custom 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, or their native Swift equivalent:

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

NSNumber

• Anything bigger than a long long or a double will be rejected.
  
• Unsigned values will be rejected.
  
• Booleans are supported, but should be initialized with [NSNumber numberWithBool:<your value>] or @YES/@NO.

NSDate
Since timezones are not supported, this will typically represent UTC dates.

Using any unsupported type as a value (NSNull, NSObject, NSArray, NSDictionary for example) will NOT work. Be careful, as it may cause [editor save] to fail.

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

NSArray<NSString>
Must not be longer than 25 items, only values of type NSString and must respect the string attribute limitations.

Setting an attribute

The custom attribute API works using an editor. You need to get an instance of the editor, enqueue your changes and then call save.
Changes will NOT be sent until you call this method, please make sure you call it!

There is one setAttribute/set(attribute:forKey:) method per attribute type. Use Xcode's autocompletion or see BatchProfileEditor.h for all available variants. If you're using Swift, the appropriate method will automatically be used according to the value's type.

Those methods throw an error if key/value failed validation according to the rules expressed higher up in this documentation. Note that no error does not mean the value has already been sent to the server.

// Get an editor instance.
// You need to save this in a local variable until you call save
// Editor instances don't share changes, and calling save on an empty editor will do nothing
let editor = BatchProfile.editor()

// Set an attribute. try? allows a potential error to be silently ignored
// This example is a valid key/attribute pair, and will not throw an error.
try? editor.set(attribute: 26, forKey:"age")

// Set an array attribute
try? editor.set(attribute: ["add_to_cart", "has_bought"], forKey: "actions")

// Add a string to an array attribute 
try? editor.addToStringArray(item: "has_bought", forKey: "actions")


// Set an attribute with error handling.
do {
    // Invalid attribute name, $ is a forbidden character
    try editor.set(attribute: "patricia", forKey: "fir$t_name")
} catch {
    // Handle the error here.
    // Error is of type BatchProfileError if you want to specifically
    // handle it.
}

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

// Alternatively you can use `editWithBlock` and make all your changes in a closure.
BatchProfile.editor { editor in
    try? editor.set(attribute: "patricia", forKey: "firt_name")
     // No need to save here since Batch will automatically save your change after executing the block.
}

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

Removing attributes

Use removeAttributeForKey to remove an attribute of any type.

// Get an editor instance.
// You need to save this in a local variable until you call save
// Editor instances don't share changes, and calling save on an empty editor will do nothing
let editor = BatchProfile.editor()

// Remove an attribute
editor.removeAttribute(forKey: "age") 

// Remove a string from an array
try? editor.removeFromStringArray(item: "has_bought", forKey: "actions")

// Don't forget to save the changes
editor.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

BatchUser.fetchAttributes { attributes in
    // Attributes are retrieved in the form of a dictionary
    // Values are encapsulated in an instance of BatchUserAttribute
    let attribute: BatchUserAttribute = attributes["age"]
            
    // BatchUserAttribute holds a reference to the value of the attribute
    let rawValue: Any = attribute.value // Raw value is not typed
    print(rawValue) // Prints "NSNumber(26)"
            
    // The type of the value is specified via a BatchUserAttributeType enumeration
    print(attribute.type) // Prints "BatchUserAttributeTypeLongLong"
            
    // To obtain a typed result you can use one of the four helper methods
    attribute.numberValue() // Will return "26" here
    attribute.dateValue()   // Will return nil here
    attribute.stringValue() // Will return nil here
    attribute.urlValue()    // Will return nil here
}

Reading tag collections

BatchUser.fetchTags { tagCollections in
    // Tags are also retrieved in the form of a dictionary
    // Keys are names of collections, values are sets of tags
    let tagCollection: Set<String> = tagCollections["actions"]
    print(tagCollection) // Prints "["has_bought"]"
}

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

Clearing the installation data will delete all tags and attributes set on an installation and their local cache returned by fetchAttributes and fetchTagCollections. It can be done as following:

BatchUser.clearInstallationData();

Note: This will NOT affect the profile related data.