Attributes

Overview

Attributes are set of keys and values that correspond to user information that are set in the mobile push database. Attributes can be derived from user behavior, user actions, or information that users provide, such as information obtained from online forms. You can update the user records in the database based on the derived attributes.

You can use the updated attributes when you want to create segments that you want to target with messages, find the number of a specific type of user, personalize messages, or understand more about your users.

Types of attribute fields

The native classes of each platform are used to update fields of the corresponding type.

Fields with country types

When you set an attribute value on a column with a country type, you must use the country’s two-character, lowercase alpha code, as defined by ISO 3166. If the code does not match a value in the country list, you cannot query for it.

Fields with date and time types

• Date fields are set using a string of format yyyy-mm-dd (e.g. 2016-06-01).
• Time fields are set using a string of format HH:MM (e.g. 10:30) in 24-hour time format. Time fields have no timezone and are usually interpreted as local time.
• Timestamp fields are set using a native data time object; this will be automatically converted to the required format by the SDK. Timestamp fields will be stored in UTC.

Fields with multiple values

• The Attribute APIs can be used to set values on multi-selection columns (fields with the Selection (Multiple) type).
• The value sent to the column must be one or more values allowed by the field.
• Multiple values must be separated by a semi-colon (e.g One; Two). Otherwise, the value is not inserted into the column.

Update attributes

Attributes can be updated through the SDK and through the REST APIs. Since there is no way to determine how a field was updated, we recommend you update attributes corresponding to a particular field using one mechanism or the other, but not both.

When you update the attributes, the names and types must match custom fields in your mobile push database, and values must be appropriate to types. If you call the attribute API and do not use the name and type format that is specified in the mobile push database, the update operation (including values for valid fields) fails, and you might lose your attributes. For this reason, ensure that you verify names, types, and values in all attribute API calls.

Acoustic recommends that you send attribute updates from the device up as a group when it makes sense. For example, if a user makes several changes by clicking check-boxes on a preferences page, wait until the user completes all actions that affect attributes and buffer those changes. After the user navigates off the screen, you can send the attributes as a group. This strategy helps you improve battery life, reduce network usage, and make your users happier with your app. Too many attribute updates at one time can result in throttling on the server.

Update attributes through the SDK

When attributes are updated, there is no way to retrieve those attributes on the SDK, so you must store them locally as well as write them. Since attribute updates are queued in the SDK, passed to the service, and then updated asynchronously within the service, if you
update an attribute that does not exist in your database it results in a failed asynchronous operation. You will not see the failure if you attempt to update a non-existent attribute or an attribute that is a lookup key.
Acoustic strongly recommends that you use the “invalidateExistingUser”: true and “loglevel”: “verbose” options in your MceConfig.json when writing attribute support code for your app. Verbose logs expose attribute operations (including confirmation when attribute writes are passed to the service). Employing the invalidateExistingUser flag allows the app to be deleted and the subsequent install to be treated as a new device thus avoiding attribute caching within the service. Without this option, writing a value to a non-existent attribute results in a write failure that manifests in one of the two ways:

• The value simply never appears in your database because the attribute is not valid
• If other attributes were written or updated as part of the invalid operation, all writes will fail. This is due to writes being bundled as an atomic operation and a single invalid update causes the entire write operation to fail for all attributes.
  If you are not seeing an attribute update in your database during development, first ensure that the attribute exists (case matters) in your database. Next, ensure that the data type you are attempting to record is the correct data type for the attribute in your database. Next, check your verbose device log for the attribute value and see if it was passed to the service. Finally, you can simply delete the app and re-install to get a fresh development environment.
  These issues occur during development when field names are fluid. After the names and API to update the values becomes fixed, you can set “invalidateExistingUser” to false.

Attribute caching

Attribute caching occurs in multiple places. First, attributes are queued and cached within the SDK. The primary purpose of this caching is to suppress unneeded network operations. An attribute update that does not change the value of an existing attribute will not be written to the service. SDK attribute caching does not employ TTL (time-to-live). Therefore, if the SDK knows about the attribute and the value has not changed, the SDK will never write the value to the service because it assumes the service already has the proper value based on a past write. Queued requests that the SDK believes will cause a change are delivered to your mobile app messaging database, regardless of whether the application is killed and restarted.

Campaign also employs two attribute caches within the service itself. The first cache is a simple attribute store within the service layer that interacts with the SDK. This cache acts similarly to the cache that the SDK uses. It stores the latest values for attributes that are written via the SDK and it does not initiate write operations to your database if an SDK write contains the value that the server already has.

This legacy cache largely exists to serve the earliest versions of our SDKs, which do not contain attribute cache support within the SDK.
This cache will also merge individual requests into a single request. This can be a problem if one attribute sent up referred to an invalid field. Invalid attributes will be recorded in this tier and can cause subsequent updates to fail to be written to your database. To remedy this during development, use invalidateExistingUser: true and delete the app and reinstall. You can also delete the invalid attribute using attribute method calls on the SDK.

The second service cache operates with a 5-minute TTL. This cache holds writes and aggregates them on a contact basis. Because of this layer, successful attribute write operations may take up to 5 minutes to appear in your database.

📘

The MCE server caches attribute updates, and in Mobile App Messaging v3.7.1.0 (and later), the SDK caches attribute updates. Only attribute updates for defined columns are delivered. If you set an attribute before a column exists, Acoustic recommends that you set invalidateExistingUser to true in mceconfig.json to ensure your testing is in sync with your clients devices. For information about invalidateExistingUser, see Assign new MUIDs.

When you make calls to the attribute APIs, the actions are added to a managed queue interface that persists requests. The queue automatically handles network and connection issues with built-in retry logic that uses exponential back-off, as needed. Queued requests are delivered to your mobile push database, regardless if the application is killed and restarted.

Update attributes using APIs

Mobile App Messaging provides two APIs for managing attributes: the update attributes API and the delete attributes API.
To add and change user attributes, use the update attributes API. With the update attributes API, you specify one or more fields to update and the field values that you want set in the database. The update API retains existing field values and replaces only specified keys with specified values.
When adding or updating attributes, you must specify the value and the value type. Fields of some types require special attention, such as fields for native classes, country types.

❗️

Warning!

If you set (or delete) the same attributes using both the SDK API and by updating the Acoustic Campaign database (either by using the REST API or by importing attributes), the attributes can get out of sync. The SDK always pushes attribute updates to the database, but the database does not push updated attributes to the device. For this reason, it is recommended that you update specific attributes either by using the SDK or the REST API/import mechanism. Do not use both methods. For example, you can set “First_Name” by using the SDK only or by using the REST API/import only, but you cannot set the “First_Name” attribute by using both the SDK and REST API / import.

Delete field values for a user

Occasionally, you might want to delete a field value from the mobile push database for a user. For example, you might want to delete specific attributes when the values are no longer relevant. The delete attributes API call removes values for specified keys for the current user in the Acoustic Campaign database. Specify one or more fields to remove the corresponding field values.

❗️

Warning!

If you delete the same attributes using both the SDK API and by updating the Acoustic Campaign database (either by using the REST API or by importing attributes), the attributes can get out of sync. The SDK always pushes attribute updates to the database, but the database does not push updated attributes to the device. For this reason, it is recommended that you update specific attributes either by using the SDK or the REST API/import mechanism. Do not use both methods. For example, you can delete “First_Name” by using the SDK only or by using the REST API/import only, but you cannot delete the “First_Name” attribute by using both the SDK and REST API / import.

Retrieve attributes for a user

Because of security concerns, apps cannot retrieve attributes after attributes are set. Thus, for attributes that the app must know, preserve attributes in the app and in the mobile push database. Don’t forget that attributes are at defined at the user level. If a user has more than one device, values might be updated more than once, depending on when the app runs on each device.

Examples to update attributes

// To set or update one or more attributes
NSDictionary * attributes = @{
    @"hobby": @"movies",
    @"age": @40,
    @"getsCatalogue": @YES,
    @"lastUpdate": [NSDate date]
};
[MCEAttributesQueueManager.sharedInstance updateUserAttributes: attributes];

// To delete one or more attributes
NSArray * attributeKeys = @[@"hobby", @"getsCatalogue"];
[MCEAttributesQueueManager.sharedInstance deleteUserAttributes: attributeKeys];

// To set or update one or more attributes
let attributes = [
    "hobby": "movies",
    "age": 40,
    "getsCatalogue": true,
    "lastUpdate": NSDate()    
]
MCEAttributesQueueManager.shared.updateUserAttributes(attributes)

// To delete one or more attributes
let attributeKeys = ["hobby", "getsCatalogue"]
MCEAttributesQueueManager.shared.deleteUserAttributes(attributes)

import co.acoustic.mobile.push.sdk.api.attribute.Attribute;
import co.acoustic.mobile.push.sdk.api.attribute.StringAttribute;
import co.acoustic.mobile.push.sdk.api.attribute.NumberAttribute;
import co.acoustic.mobile.push.sdk.api.attribute.BooleanAttribute;
// DateAttribute currently does not work
//import co.acoustic.mobile.push.sdk.api.attribute.DateAttribute;
import co.acoustic.mobile.push.sdk.api.attribute.AttributesOperation;

// To set or update one or more attributes
List < Attribute > attributes = new LinkedList < Attribute > ();
// attributes can also be ArrayList or any other List implementation
attributes.add(new StringAttribute("hobby", "movies"));
attributes.add(new NumberAttribute("age", 40));
attributes.add(new BooleanAttribute("getsCatalogue", false));
// DateAttribute currently does not work
// attributes.add(new DateAttribute("birthday", new Date()));

try {
    MceSdk.getQueuedAttributesClient().updateUserAttributes(
        getApplicationContext(),
        attributes);
} catch (JSONException jsone) {
    // if this happens it's an SDK defect
}


// To delete one or more attributes
List < String > attributeKeys = new ArrayList < String > ();
attributeKeys.add("hobby");
attributeKeys.add("getsCatalogue");
try {
    MceSdk.getQueuedAttributesClient().deleteUserAttributes(
        getApplicationContext(),
        attributeKeys);
} catch (JSONException jsone) {
    // if this happens it's an SDK defect
}

import {RNAcousticMobilePush} from 'NativeModules';

const attributes = {favioritePlayer: "Lionel Messi"};
RNAcousticMobilePush.updateUserAttributes(attributes);

// To set or update one or more attributes
var json = {};
json["hobby"] = "movies";
json["age"] = 40;
json["getsCatalogue" = true; json["lastUpdate"] = new Date();

MCEPlugin.queueUpdateUserAttributes(attributes);

// To delete one or more attributes
var attributeKeys = ["hobby", "getsCatalogue"]; MCEPlugin.queueDeleteUserAttributes(attributeKeys);

MCEPlugin.setAttributeQueueCallbacks(function() 
{
    console.log("attribute success");
}, 
function(error) 
{
    console.log("attribute failure")
});