The Mobile App Messages SDK allows you to set field values in user records in the mobile push database. For example, you can update field values 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.
Attributes are sets of keys and values that correspond to user information. Attributes can be derived from user behavior, user actions, or information that users provide, such as information obtained from online forms.
Attribute 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.
|Note:||When column in Watson Campaign Automation database is set to
Development Best Practices
In general, IBM 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.
Attributes can be sent in two places: via the SDK and via REST API. There is no way to determine which way caused a field to be updated. We recommend you update particular attributes using one mechanism or the other, but not both.
There is no way to retrieve attributes on the SDK, so you must store them locally as well as write them.
Attempting to update an attribute that does not exist in your database results in a failed asynchronous operation. Since attribute updates are queued in the SDK, passed to the service, and then updated asynchronously within the service, you will not see the failure if you attempt to update a non-existent attribute or an attribute that is a lookup key.
IBM 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 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.
WCA 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.
Note: 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 with the SDK API.
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.
|Note:||The MCE server caches attribute updates, and in Mobile App Messaging v220.127.116.11 (and later), the SDK caches attribute updates. Only attribute updates for defined columns are delivered. If you set an attribute before a column exists, IBM recommends that you set
Note: 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.
Mobile App Messaging provides two APIs for managing attributes: the update attributes API and the delete attributes API.
Adding and changing user attributes
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 Watson Campaign Automation 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, IBM recommends 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.
Fields for native classes
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.
Deleting 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 Watson Campaign Automation 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 Watson Campaign Automation 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, IBM recommends 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.
Retrieving 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.
Note that additional platform-specific information on the SDK methods can be found at the following URLs.