Setting and removing Attributes

Setting and removing Attributes varies per Attribute type. Setting Attributes on Named Users is recommended.

There is no setup required for Default and NPS survey Attributes. You can go straight to Targeting your audience using Attributes. For Predefined and Custom Attributes, you must set them on your audience after adding them to your project.

Important

You must add Custom and Predefined Attributes to your project before setting them on users. Otherwise, setting those Attributes will result in an error. See Adding Attributes to your project.

JSON Attributes can only be set using the API.

Channels versus Named Users

You can set Attributes on Channels and Named Users, however their inheritance of Attributes varies:

Channels inherit from Named Users — All the Channels associated with a Named User will also bear the Named Users’s Attributes. When you remove a Channel from a Named User, Airship removes Attributes set on the Named User from that Channel.
Using the example favorite_actor Attribute contains the value chris, if you store the favorite_actor Attribute at the Named User level, you can target all contacts who are fans of Chrises over any of their Channels. You can keep your audience up to date on Chris-related news, no matter which Channels they use to communicate with you.

Attributes at the Named User level can be used to target any Channel associated with a Named User:

Named Users do not inherit from Channels — Any Attribute set for a Channel will not also be set for an associated Named User.
If you store the favorite_actor Attribute at the Channel level, you can only target fans of Chrises on the specific Channels bearing the favorite_actor Attribute, limiting the scope of Chris-related communications.

Attributes at the Channel level are limited to that Channel:

In general, we recommend that you store Attributes at the Named User level so you can take advantage of your Attributes across any of your users’ Channels. This helps you build and maintain a cohesive relationship with your audience. Setting Attributes at the Channel level limits the scope of the Attribute to that Channel and can also limit your flexibility when targeting audiences.

Named users also inherit a few Default Attributes from the last Channel that was associated with them, helping keep your Named Users up to date with scheduling and locale information.

These Attributes appear in the user_attributes object:

Default Attribute	Description	Example
ua_local_tz	The user's time zone	America/Los_Angeles
ua_country	The user's ISO 3166 two-character country code	US
ua_language	The user's ISO 639-1 two-character language code	en

Setting and removing Text, Number, and Date Attributes

You can set and remove Text, Number, and Date Attributes using:

CSV file upload in the dashboard
CSV file transfer using SFTP
App and Web SDKs
Channels and Named Users APIs

Use these formats when setting each Attribute type:

Type	Format
Text	String. When setting Text Attributes using a CSV, you do not need to wrap the value in quotes.
Number	Number, float value, or string
Date	ISO 8601 date-time formatted string: `YYYY-MM-DDTHH:MM:SS`. Set an offset by appending the date-time with `+HH:MM`. For example, `2020-07-20T12:35:42+08:00`.

CSV file

First, create a list of users and their Attributes in a CSV file. Prepare your file using the guidelines in Attributes CSV Format in the CSV Formatting Reference. 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.

Next, transfer the file using SFTP or upload it in the dashboard. Follow the steps in SFTP upload for CSV files, or follow these steps for dashboard upload:

Go to Audience, then Attributes, then Upload Attribute Data.
Select Choose file and select your file.
Select Upload.

To see your upload and SFTP transfer status, select Upload History. See Viewing upload history in Managing Attributes.

Retention and deletion

Airship automatically deletes a list and all its versions after 90 days of inactivity. Timestamps used to calculate the 90-day period:

Creation date
New version uploaded

The creation date is the initial day one of the 90-day period. Each instance of uploading a new version resets the timestamp to day one.

The retention period for an Attributes list is the same whether uploaded in the Airship dashboard or using SFTP.

After deletion, the list is removed from the upload history and is no longer visible in the Airship dashboard or through API calls. Deletion does not affect the project state. For example, if you use an Attribute list that adds Attribute A to a Channel, Attribute A will still exist on the Channel after list deletion.

SDK

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

iOS — UAContact UAChannel
Android — Channel Contact
Web — Attributes

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

Setting Attributes for mobile apps

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

Airship.channel.editAttributes { editor in
    editor.set(string: "cauldron", attribute: "last_product_purchased")
    editor.set(number: 4.99, attribute: "average_rating")
    editor.remove("purchase_pending")
}

[UAirship.channel editAttributes:^(UAAttributesEditor * editor) {
    [editor setString:@"cauldron" attribute:@"last_product_purchased"];
    [editor setNumber:@(4.99) attribute:@"average_rating"];
    [editor removeAttribute:@"purchase_pending"];
}];

Setting Attributes for Web

const editor = channel.editAttributes()
await editor
   .set("my_attribute", "some_value")
   .remove("other_attribute")
   .apply()

API

You can set Attribute values from external sources, such as a CRM or data warehouse, using the Channels and Named Users APIs:

Use set or remove for the action value. Use the Attribute ID as the key value.

Setting two Attributes on a Channel and removing another

POST /api/channels/attributes HTTP/1.1 Authorization: Basic <App Auth> style=color:#f92672>: 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" } ] }

Setting two Attributes on a Named User and removing another

POST /api/named_users/my_named_user/attributes HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: application/json

{
    "attributes": [
        {
            "action": "set",
            "key": "firstName",
            "value": "Gyuri",
            "timestamp": "2020-09-19 12:00:00"
        },
        {
            "action": "remove",
            "key": "birthDate",
            "timestamp": "2020-09-19 12:00:00"
        },
        {
            "action": "set",
            "key": "lastName",
            "value": "Pataki",
            "timestamp": "2020-09-19 12:00:00"
        }
    ]
}

Setting and removing JSON Attributes

JSON Attributes can only be set or removed using the Channels and Named Users APIs:

Use set or remove for the action value. Set the key value as <attribute_ID>#<instance_ID>. Instance IDs:

Can contain letters, numbers, and underscores only
Must begin with a letter
Must end with a letter or number
Are limited to 31 characters maximum
Are case-sensitive

For more information, see JSON Attributes in About Attributes.

In the examples below we are using the Attribute ID reservations and instance ID a001.

Setting a JSON Attribute on a Channel

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": "b31cf3ab-f33e-46ae-b874-782facda2bab"
    },
    "attributes": [
        {
            "action": "set",
            "key": "reservations#a001",
            "value": {
                "flights": [
                    {
                        "departs": {
                            "port": "PDX",
                            "time": "2023-12-01T05:09:00"
                        },
                        "arrives": {
                            "port": "LAX",
                            "time": "2023-12-01T07:09:00"
                        }
                    },
                    {
                        "departs": {
                            "port": "LAX",
                            "time": "2023-12-08T12:30:00"
                        },
                        "arrives": {
                            "port": "PDX",
                            "time": "2023-12-08T14:45:00"
                        }
                    }
                ]
            }
        }
    ]
}

Setting the four different types of Attributes on a Named User

POST /api/named_users/my_named_user/attributes HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: application/json

{
    "attributes": [
        {
            "action": "set",
            "key": "favorite_food",
            "value": "cake"
        },
        {
            "action": "set",
            "key": "age",
            "value": 35
        },
        {
            "action": "set",
            "key": "birthdate",
            "value": "1985-07-14T00:00:00"
        },
        {
            "action": "set",
            "key": "flights#id123",
            "value": {
                "recordID": 123,
                "flightsInfo": [
                    {
                        "departureTime": "2024-07-14T12:35:42+08:00",
                        "flightId": "LY205",
                        "destinationAirportCode": "PDX",
                        "originAirportCode": "LAX"
                    },
                    {
                        "departureTime": "2024-14-14T12:00:00+08:00",
                        "flightId": "LY315",
                        "destinationAirportCode": "LAX",
                        "originAirportCode": "PDX"
                    }
                ]
            }
        }
    ]
}

Feedback

Was this page helpful?