Setting up your project for attributes

Before you can target using attributes, some setup work is required, and some steps must be performed by your mobile and web developers.

The general process for setting up your project for attributes:

  • Upgrade your SDKsRequired if you want to use default attributes or set attributes from the SDK.
  • Define custom attributes or add predefined attributes
  • Set attributes on channels or named users by uploading a CSV in the dashboard or using SFTP, or from our SDKs or Channels API

Upgrading your SDKs

You must upgrade to the listed minimum iOS and Android SDKs if you want to:

  • Use default attributes — Updating the SDK enables Airship to automatically set the default attributes for you. You can then use default attributes for targeting.
  • Set attributes from the SDK

iOS

 Important

If you are on an iOS SDK version prior to 12.1.0 and only want to upgrade for attributes, you can upgrade to 12.1.2, which includes patches since the initial attributes release.

We also support attributes in our latest major release, iOS SDK 13.0. Note, however, that our SDK 13.0 release splits the SDK into modules and requires additional development work. See the changelog and migration guide links in our iOS SDK 13.0 release note for details.

Android

 Important

Airship Android SDK 12 was a major release, decoupling Airship channel registration from push functionality and providing support for attributes. We do not recommend upgrading unless you plan to use attributes and are able to perform the other necessary steps to complete the upgrade.

See the Airship Android SDK Migration Guide for details.

Adding attributes to your project

 Important

You can add custom and predefined attributes to your Airship project at any time, but you set attributes on your audience by uploading a CSV, or from our SDKs or Channels API.

You can create up to 250 attributes per project.

  1. Go to Audience » Attributes » Attribute List and click Create Attribute.

  2. Search to see if Airship has predefined the attribute you want to create. Search does not return predefined attributes that have been archived or have already been added. See: List of predefined attributes.

  3. Complete the attribute fields. You can only edit the name for predefined attributes.

    • Attribute ID: Letters, numbers, and underscores only. 128 characters maximum.
    • Name: All characters accepted. 64 characters maximum.
    • Type: Date, Text, or Number.
       Important

      • The attribute ID is the key that Airship uses to reference the attribute in our SDKs and API; we recommend using lower-case characters with underscores for the ID, e.g., my_text_attribute.

      • Attribute IDs are case sensitive. If attributes exist in an external system, make sure they are always the same case in both systems.

      • Names and IDs must be unique. You cannot edit the ID or type after you create a custom attribute.

  4. Click Add.

Setting attributes on your audience

 Important

You must define custom attributes or add predefined attributes in the dashboard before associating them with channels and named users. Trying to use a custom or predefined attribute that you haven’t yet set up in the dashboard will result in an error.

Use the attribute ID as the value for the key when setting or removing attributes. Set attributes on channels or named users by uploading a CSV in the dashboard or using SFTP, or from our SDKs or Channels API.

Using a CSV file

Follow the steps in the SFTP tutorial, or follow the steps below for CSV upload in the Airship dashboard. When using email or SMS identifiers in your CSV file, Airship registers new channels for addresses or MSISDN/sender combinations that are new to your project. Additional fields indicate opt-in statuses, so that you can send messages to new channels generated from your CSV upload.

  1. Prepare your CSV file using the guidelines in Attributes CSV Format.
  2. Go to Audience » Attributes » Upload Attribute Data. You can click Download sample CSV file   to see a formatted file.
  3. Click Choose file and select your CSV.
  4. Click Upload. Your dashboard and SFTP uploads are listed in Audience » Attributes » Upload History.

From the SDK

To set or remove attributes on a channel or a contact, use the Channel or Contact classes in our SDKs:

The code examples below show how to set attributes using the provided methods. See the Mobile and Web SDK docs for more details.

Android: Java
UAirship.shared().getChannel().editAttributes()
            .setAttribute("average_rating", 4.99)
            .setAttribute("last_product_purchased", "A1234567")
            .removeAttribute("purchase_pending")
            .apply();

iOS: Swift
    let mutations = UAAttributeMutations()
    mutations.setNumber(4.99, forAttribute: "average_rating")
    mutations.setString("cauldron", forAttribute:"last_product_purchased")
    mutations.removeAttribute("purchase_pending")
    UAirship.channel()?.apply(mutations)

iOS: Objective-C
    UAAttributeMutations *mutations = [UAAttributeMutations mutations];
    [mutations setNumber:@4.99 forAttribute:@"average_rating"];
    [mutations setString:@"cauldron" forAttribute:@"last_product_purchased"];
    [mutations removeAttribute:@"pending_purchase"];
    [[UAirship channel] applyAttributeMutations:mutations];

Web
UA.then(function(sdk) {
   sdk.channel.attributes
     .set({last_product_purchased: "A1234567"})
     .then(result => console.log("Last product purchase attribute updated!"))
     .catch(err => console.error("An error occured while setting attributes: %s", err))
})

UA.then(function(sdk) {
 sdk.channel.attributes
   .remove("purchase_pending")
   .then(result => console.log("Purchase pending attribute has been removed!"))
   .catch(err => console.error("An error occured while removing 1 attribute: %s", err))
})

From the API

You can set attribute values from external sources, e.g., CRM or data warehouse, using the Channels API.

Use the Set or Remove Attributes endpoint to set an attribute on, or remove an attribute from, a channel or named user.

Set two attributes on a channel and remove another
POST /api/channels/attributes HTTP/1.1
Authorization: Basic <App Auth>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: application/json

{
    "audience": {
        "ios_channel": "b8f9b663-0a3b-cf45-587a-be880946e881"
    },
    "attributes": [
        {
            "action": "set",
            "key": "favorite_actor",
            "value": "chris_evans",
            "timestamp": "2019-09-19 12:00:00"
        },
        {
            "action": "remove",
            "key": "favorite_color",
            "timestamp": "2019-09-19 12:00:00"
        },
        {
            "action": "set",
            "key": "first_name",
            "value": "Roger",
            "timestamp": "2019-09-19 12:00:00"
        }
    ]
}