Segmentation

Addressing Devices

To help target specific devices or users for a notification, we have Tags, Named Users, Tag Groups, and Attributes.

Tags

Tags are an easy way to group channels. Many tags can be applied to one or more devices. Then, a message sent to a tag will be sent out to all devices that are associated with that tag.

Modifying tags
// Set tags
UA.then(sdk => {

  sdk.getChannel().then(channel => {

    // List all tags
    channel.tags.list // Returns {device: [tag1, tag2, ...], custom-group: [tag]}

    // Check for a specific tag
    channel.tags.has(tag, group) // Returns bool

    // Add a tag
    channel.tags.add(tag, group) // Returns true if successful

    // Remove a tag
    channel.tags.remove([tag1, tag2, ...], group) // Returns True if successful

    // Set tags
    channel.tags.set(tags, group) // Returns true if successful
    // Resets all tags for the given tag group.

    // `group` is optional in all tag functions and defaults to `device` if not specified
  })

})

Named Users

Named Users allow you to associate multiple devices to a single user or profile that may be associated with more than one device, e.g., an end-user’s Chrome browser on their laptop and their iPhone. A device can have only one Named User, and a single Named User should not be associated with more than 50 devices. Named Users provide the ability to directly set tags on them (see Tag Groups).

 Note

Associating the channel with a Named User ID, will implicitly disassociate the channel from the previously associated Named User ID, if it existed.

By default, Named Users can only be associated server-side. A 403 Forbidden response is returned if Named User association is attempted when client-side association is disabled. In order to associate a Named User through the project, you must change the project’s Named User security setting to allow Named Users to be set from devices. To enable this option, go to Settings » APIs & Integrations » Named Users.

Setting the named user
UA.then(sdk => {

  sdk.getChannel().then(channel => {
    // Return the current Named User
    channel.namedUser.id  // Returns null or string

    // Set the Named User to a String
    channel.namedUser.set(name) // associates this channel with a named user

    // Remove the currently associated Named User
    channel.namedUser.remove() // Disassociates the channel from the named user
    // Returns true if successful
  })
})

Tag Groups

Tag groups are configurable namespaces for organizing tags for the channel and Named User. Please view the Tag Groups documentation for more details. Create and Push To a Tag Group guides you through creating and using tag groups.

By default, Tag Groups can only be modified from the server. A 403 Forbidden response is returned if Tag Groups modification is attempted when client-side Tag Groups is disabled. In order to modify Tag Groups through the application, you must change the application’s Tag Group security settings to allow these tags to be set from devices. Follow the steps in Manage Tag Groups to enable this option.

Channel Tag Group Examples
UA.then(sdk => {
  sdk.getChannel().then(channel => {

    // Add channel tag to a group
    channel.tags.add('tag-name', 'group-name')

    // Remove channel tag from a group
    channel.tags.remove('tag-name', 'group-name')

    // Set channel tags on a group
    channel.tags.set(['silver-member', 'gold-member'], 'loyalty')
    // Resets all channel tags for the given tag group.

    // List channel tags
    channel.tags.list

    // Check for a specific tag on a channel
    channel.namedUser.tags.has('bronze-member', 'loyalty')
  })
})
Named User Tag Group Examples
UA.then(sdk => {
  sdk.getChannel().then(channel => {

    // Add named user tag to a group
    channel.namedUser.tags.add('tag-name', 'group-name')

    // Remove named user tag from a group
    channel.namedUser.tags.remove('tag-name', 'group-name')

    // Set named user tags on a group
    channel.namedUser.tags.set(['silver-member', 'gold-member'], 'loyalty')
    // Resets all named user tags for the given tag group.

    // List named user tags
    channel.namedUser.tags.list

    // Check for a specific tag on a named user
    channel.namedUser.tags.has('bronze-member', 'loyalty')
  })
})

Attributes

Attributes are metadata that you can use to group and target your audience. Attributes differ from tags in that when evaluating users with attributes, Airship uses operators, e.g., equals, less than/greater than, contains, before/after, to determine whether or not to target a user. Supported attribute types are TEXT, NUMBER, and DATE.
Attributes Example
UA.then(sdk => {
  sdk.getChannel().then(channel => {
   channel.attributes.set({firstName: "John", lastName: "Doe"})
     .then(result => console.log("Firstname and lastname set!"))
     .catch(err => console.error("An error occured while setting attributes: %s", err))
  })
})