Audience and Segmentation

Segments

Examples can be found in the segments documentation here.

class urbanairship.devices.segment.Segment
create(airship: BaseClient) → Response

Create a Segment object and return it.

classmethod from_id(airship: BaseClient, seg_id: str)

Retrieve a segment based on the provided ID.

update(airship: BaseClient) → Response

Updates the segment associated with data in the current object.

Segment Listing

Segment lists are fetched by instantiating an iterator object using SegmentList.

class urbanairship.devices.segment.SegmentList(airship: BaseClient, limit: int | None = None)

Retrieves a list of segments

Parameters:

limit – Number of segments to fetch

Tags

Examples can be found in the tags documentation here.

Channel Tags

class urbanairship.devices.tag.ChannelTags(airship: BaseClient)

Modify the tags for a channel

Parameters:

airship – An urbanairship.Airship instance.

set_audience(user_ids: List[str] | None = None, ios: str | None = None, android: str | None = None, amazon: str | None = None, web: str | None = None) → None

Sets the audience to be modified :param ios: an ios channel :param android: an android channel :param amazon: an amazon channel :param web: a web channel

add(group_name: str, tags: List[str]) → None

Sets group and tags to add

Parameters:

  • group_name – The name of the tag group to add

  • tags – The tags to add

remove(group_name: str, tags: List[str]) → None

Sets group and tags to remove

Parameters:

  • group_name – The name of the tag group to remove

  • tags – The tags to addremove

set(group_name: str, tags: List[str]) → None

Sets group and tags to set. Note that a set operation replaces all tags on the audience upon send.

Parameters:

  • group_name – The name of the tag group to set

  • tags – The tags to set

send() → Dict

Perform the Channel Tag operations.

Returns:

JSON response from the API

Open Channel Tags

class urbanairship.devices.tag.OpenChannelTags(airship: BaseClient)

Modify the tags for an open channel

set_audience(address: str, open_platform: str) → None

Sets the audience to be modified.

Parameters:

  • address – the open channel to be modified

  • open_platform – the name of the open platform the channel belongs to.

add(group_name: str, tags: List[str]) → None

Sets group and tags to add

Parameters:

  • group_name – The name of the tag group to add

  • tags – The tags to add

remove(group_name: str, tags: List[str]) → None

Sets group and tags to remove

Parameters:

  • group_name – The name of the tag group to remove

  • tags – The tags to addremove

set(group_name: str, tags: List[str]) → None

Sets group and tags to set. Note that a set operation replaces all tags on the audience upon send.

Parameters:

  • group_name – The name of the tag group to set

  • tags – The tags to set

send() → Dict

Perform the Open Channel Tag operations.

Returns:

JSON response from the API

Email Channel Tags

class urbanairship.devices.email.EmailTags(airship: BaseClient, address: str)

Add, remove or set tags for a list of email addresses

Parameters:

address – an email address to mutate tags for

add(group: str, tags: List[str]) → None

add tags to a given tag group :param group: the tag group to add to :param tags: a list of tags to add

remove(group: str, tags: List[str]) → None

remove tags from a given tag group :param group: the tag group to remove tags from :param tags: a list of tags to remove

set(group: str, tags: List[str]) → None

replace all tags on the given tag group with these tags :param group: the tag group to set tags on :param tags: a list of tags to set

send() → Response

commit add, remove and set operations. set cannot be used with add and remove.

Returns:

the response object from the api

Named User Tags

class urbanairship.devices.named_users.NamedUserTags(airship: BaseClient)

Modify the tags for named users

add(group_name: str, tags: List[str]) → None

Sets group and tags to add

Parameters:

  • group_name – The name of the tag group to add

  • tags – The tags to add

remove(group_name: str, tags: List[str]) → None

Sets group and tags to remove

Parameters:

  • group_name – The name of the tag group to remove

  • tags – The tags to addremove

send() → Dict

Perform the Channel Tag operations.

Returns:

JSON response from the API

set(group_name: str, tags: List[str]) → None

Sets group and tags to set. Note that a set operation replaces all tags on the audience upon send.

Parameters:

  • group_name – The name of the tag group to set

  • tags – The tags to set

set_audience(user_ids: List[str] | None = None, ios: str | None = None, android: str | None = None, amazon: str | None = None, web: str | None = None) → None

Set the named user ids to be modified.

Parameters:

user_ids – A list of named user ids.

Named User

A Named User is a proprietary identifier that maps customer-chosen IDs, e.g., CRM data, to Channels. It is useful to think of a Named User as an individual consumer who might have more than one mobile device registered with your app.

Examples can be found in the named users documentation here.

class urbanairship.devices.named_users.NamedUser(airship: BaseClient, named_user_id: str | None = None)

Perform various operations on a named user object

Parameters:

airship – Required. An instance of urbanairship.Airship.

associate(channel_id: str, device_type: str | None = None) → Response

Associate a channel_id with a named user ID. Either channel_id and device_type OR email_address must be included.

Parameters:

  • channel_id – Required. The ID of the channel you would like to associate with the named user

  • device_type – The device type of the channel, do not include for web notify channel_ids

Returns:

email_associate(email_address: str) → Response

Associate an email_address with a named user id. This call is for a literal email address.

Parameters:

email_address – Required. The email address to associate.

Returns:

disassociate(channel_id: str, device_type: str | None = None) → Response

Disassociate a channel with a named user ID

Parameters:

  • channel_id – The ID of the channel you would like to disassociate

  • device_type – The device type of the channel. Do not include for web notify channels.

Returns:

email_disassociate(email_address: str) → Response

Disassociate an email_address with a named user ID

Parameters:

channel_id – The email_address you would like to disassociate

Returns:

lookup() → Dict | str

Lookup a single named user

Returns:

The named user payload for the named user ID

tag(group: str, add: List | None = None, remove: List | None = None, set: List | None = None) → Dict

Add, remove, or set tags on a named user.

Parameters:

  • add – A list of tags to add

  • remove – A list of tags to remove

  • set – A list of tags to set

  • group – The Tag group for the add, remove, and set operations

update(associate: List | None = None, disassociate: List | None = None, tags: Dict | None = None, attributes: List | None = None) → Response

Create or update a named user by associating/disassociating channels and adding/removing tags and attributes in a single request.

If a channel has an assigned named user and you make an additional call to associate that same channel with a new named user, the original named user association will be removed and the new named user and associated data will take its place. Additionally, all tags associated to the original named user cannot be used to address this channel unless they are also associated with the new named user.

Please see https://docs.airship.com/api/ua/#operation-api-named_users-named_user_id-post

Parameters:

  • assocaite – Optional. List of objects to associate with the named user

  • disassociate – Optional. List of objects to disassociate from the named user

  • tags – Optional. Dictionary of set, add, remove objects to apply to named user

  • attributes – Optional. List of attributes to apply to named user.

Returns:

attributes(attributes: List | None) → Response

Set or remove attributes on a named user. A single request body may contain a set or remove field, or both, or a single set field. If both set and remove fields are present and the intersection of the attributes in these fields is not empty, then a 400 will be returned. If an attribute request is partially valid, i.e. at least one attribute exists, Airship returns a 200 with a warning in containing a list of attributes that failed to update. Please see https://docs.airship.com/api/ua/#operation-api-named_users-named_user_id-attributes-post for more about using Airship attributes.

Params attributes:

Required. A list of attribute objects to set or remove on the named user.

classmethod uninstall(airship: BaseClient, named_users: List[str]) → Response

Disassociate and delete all channels associated with the named_user_id(s) and also delete the named_user_id(s). This call removes all channels associated with a named user from Airship systems in compliance with data privacy laws. Uninstalling channels also removes accompanying analytic data (including Performance Analytics) from the system. Channel uninstallation, like channel creation, is an asynchronous operation, and may take some time to complete.

Parameters:

  • airship – Required. An urbanairship.Airship instance.

  • named_users – Required a list of named_user_ids to completely uninstall

Returns:

classmethod from_payload(payload: Dict)

Create NamedUser object based on results from a NamedUserList iterator.

Parameters:

payload – Payload used to create the NamedUser object

Named User List

class urbanairship.devices.named_users.NamedUserList(airship: BaseClient)

Retrieves a list of NamedUsers

Attributes

Define and manage attributes.

Examples can be found in the attributes documentation here.

class urbanairship.devices.attributes.Attribute(action: str, key: str, value: str | int | None = None, timestamp: datetime | None = None)

Creates an attribute object for use with the ModifyAttributes class to set or remove attributes from channel_ids and named_user_ids.

Parameters:

  • action – [required] The action that will be taken with the supplied attributes. Must be one of ‘set’ or ‘remove’.

  • key – [required] The attribute key to be set.

  • value – [required] a string or int. If action is ‘set’, the value to set on the key.

  • timestamp – [optional] a datetime.datetime object representing the time the attribute was modified. If not included, the time of modification call will be used.

class urbanairship.devices.attributes.ModifyAttributes(airship: BaseClient, attributes: List[Attribute], channel: str | None = None, named_user: str | None = None)

Set or remove attributes on a channel. Aside from Airship’s default attributes, you must define attributes in the Airship dashboard before you can set them on channels. A single channel_id or named_user must be included.

Parameters:

  • airship – required. An Airship object.

  • attributes – required. A list of one or more Attributes objects.

  • channel – optional. An existing UUID formatted channel_id

  • named_user – optional. An existing named_user_id

send() → AttributeResponse

Makes the call to Airship APIs to modify the channel_id or named_user passed on init.

Returns:

AttributeResponse object

Lists

Create and manage audience lists.

Attribute Lists

Examples can be found in the attributes documentation here.

class urbanairship.devices.attributes.AttributeList(airship: BaseClient, list_name: str, description: str, extra: Dict[str, str] | None = None)

Define and manage attribute lists; upload corresponding attribute data in CSV format.

Parameters:

  • airship – Required. An unbanairship.Airship instance.

  • list_name – Required. The name of your list. Must be prefixed with ua_attributes_

  • description – Required. A description of your list.

  • extra – Optional. An optional dict of up to 100 key-value (string-to-string) pairs associated with the list.

create() → Response

Create the Attribute List

upload(file_path: str) → Response

Upload a CSV that will set attribute values on the specified channels or named users. Please see the documentation at https://docs.airship.com/api/ua/#operation-api-attribute-lists-list_name-csv-put for details about list formatting, size limits, and error responses.

Parameters:

file_path – Required. Local path to the csv file to be uploaded.

get_errors() → Response

Returns csv of attribute list processing errors. During processing, after a list is uploaded, errors can occur. Depending on the type of list processing, an error file may be created, showing a user exactly what went wrong.

classmethod list(airship: BaseClient) → Response

Lists existing attribute lists.

Parameters:

airship – An urbanairship.Airship instance.

Subscription Lists

Examples can be found in the subscription lists documentation here.

class urbanairship.devices.subscription_lists.SubscriptionList(airship: BaseClient, list_id: str)

Subscribe or unsubscribe channels to/from Subscription lists. These lists must be created in the Airship web dashboard prior to making these calls. The value for list_id can be found after creating these lists.

Parameters:

  • airship – Required. An urbanairship.Airship instance.

  • list_id – Required. The list_id from the Airship web dashboard.

unsubscribe(audience: Dict) → Response

Unsubscribe an audience from a subscription list.

Parameters:

audience – Required. A single audience selector (ex: urbanairship.ios_channel) to unsubscribe.

subscribe(audience: Dict) → Response

Subscribe an audience from a subscription list.

Parameters:

  • list_id – Required. The list_id from the Airship web dashboard.

  • audience – Required. A single audience selector (ex: urbanairship.ios_channel) to subscribe.

Static Lists

Examples can be found in the static lists documentation here.

class urbanairship.devices.static_lists.StaticList(airship: BaseClient, name: str)
create() → Dict

Create a Static List

upload(csv_file: TextIOWrapper) → Dict

Upload a CSV file to a static list

Parameters:

csv_file – open file descriptor with two column format: identifier_type, identifier

Returns:

http response

update() → Dict

Update the metadata in a static list

Returns:

http response

classmethod download(airship: BaseClient, list_name: str) → Response

Allows you to download the contents of a static list. Alias and named_user values are resolved to channels.

Parameters:

  • airship – Required. An urbanairship.Airship instance.

  • list_name – Required. Name of an existing list to download.

Returns:

csv list data

lookup()

Get Information about the static list

Returns:

urbanairship.StaticList objects

delete() → Response

Delete the static list

class urbanairship.devices.static_lists.StaticLists(airship)

Gets an iterable listing of existing static lists