Ban Lists

About Ban Lists

A Ban List has these components:

• Your record of banned users — These may be users compiled from “Do not contact me” responses or any other reason to omit them from messaging.

  You decide the record’s format and storage location outside of Airship. Each user must be associated with a Channel IDAn Airship-specific unique identifier used to address a channel instance, e.g., a smartphone, web browser, email address. or Named UserA customer-provided identifier used for mapping multiple devices and channels to a specific individual.. We recommend Named User since it maps to all Channel IDs associated with a user. Named User must already be implemented for your project.

• An external webhook  — This is an HTTP callback Airship uses to access your record of banned users. You configure the callback and provide Airship with a request URL formatted for querying your data.

  The webhook must provide a specific response when a match is found. You can format the request URL to use Channel ID, Named User, or both. You can also format it to pass variables. You set a default value for the variable when setting up the URL and can override the values for individual messages.

• A Ban List configuration in your Airship project — You will enter your request URL and confirm Airship is authorized to use it for its intended purpose.

Once the above items are in place, this is the Ban List workflow:

1. Airship makes an API call to your webhook for every Channel ID in a message audience. For In-App Automations and Scenes, the Ban List is checked immediately before display. For all other messages, it is checked at send time.
2. Your webhook checks your record of banned users for matches for each Channel ID. If a match is found, the webhook sends a response telling Airship to drop the matched user.
3. Airship drops the send for each match.

Only necessary data to prevent users from receiving messages is captured during time of send and is not stored beyond what is necessary for that purpose. Airship does not access or store administrative configurations related to your Ban List.

You can set up one Ban List per project.

Support for In-App AutomationMessages cached on users’ devices and displayed when users meet certain conditions within your app, such as viewing a particular screen or opening the app a certain number of times. and ScenesA single or multi-screen in-app experience cached on users’ devices and displayed when users meet certain conditions in your app or website, such as viewing a particular screen or when a Custom Event occurs. They can be presented in fullscreen, modal, or embedded format using the default swipe/click mode or as a Story. Scenes can also contain survey questions. requires: iOS SDK 18.4+Android SDK 18+

Throttling

Using an external Ban List can mean a lot of API calls in a short period of time. When configuring your Ban List in Airship, you can set a frequency rate for your requests. The minimum rate is 100 requests per second.

Bypassing

You can bypass your Ban List when sending business-critical or otherwise required messages, such as privacy policy update notifications. Bypass is supported for both the API and dashboard.

Reporting

A SEND_ABORTED event occurs when a recipient is dropped from our system before delivery is attempted, with reason value FEED_BANNED_RESPONSE.

SEND_ABORTED is not reported for dropped In-App Automations or Scenes. Instead, the app SDK sends an IN_APP_MESSAGE event with resolution IN_APP_MESSAGE_EXCLUSION when a recipient is dropped.

See the events and examples in the Real-Time Data Streaming API reference:

• Send Aborted
• In-App Message Exclusion

Each dropped recipient counts toward the Not Sent count in a message report.

Webhook requirements

When you send a message, Airship will make an API call to your webhook with a URL parameter containing a Named User ID and/or Channel ID. Your server must return a header indicating Airship should drop a matched user from the send.

Set up your webhook to return an X-UA-Segmentation-Action header to specify an action to be taken by Airship. The only value supported is drop, to drop the recipient from the send. This header is valid only for 200- and 400-level status codes and is ignored if provided for 300- or 500-level status codes. It is also ignored if the value is not recognized or the header is missing. Any response with a 200-level status code that does not contain a drop value in the header will allow sending to the recipient.

Formatting your request URL

Your request URL is used to retrieve the user data. You will enter it in the dashboard when configuring your Ban List. It comprises your domain, protocol, path, and any variables you want to include.

Guidelines:

• The URL must contain a parameter for the identifiers in your Ban List, one of:
  • ?channel_id={{$channel.id}}
  • ?named_user={{ua_named_user_id}}
  • ?named_user={{ua_named_user_id}}&channel_id={{$channel.id}}
• Use double square brackets ([[var]]) for send time, or message-level, variables.

This example request URL has a send time variable category and the parameter for Named User: https://api.example.com/ban-list/[[category]]?named_user={{ua_named_user_id}}.

Configuring your Ban List

Owners and Administrators can configure a project’s Ban List.

In the Airship dashboard:

1. Go to Settings.
2. Under Project Configuration, select Manage for Dashboard Settings.
3. Select Configure for Ban List.
4. Configure the list settings:

   Setting	Description	Steps
   Request URL	The URL to retrieve the user data from. See Formatting your request URL.	Enter the request URL.
   Default value for <variable>	The default value for each send time variable included in the request URL.	Enter a default value.
   Confirm request URL domain	The domain in the request URL. For example, api.example.com. Do not include the protocol or variables.	Enter the domain.
   Headers	Optional. HTTP request headers that may be required to successfully communicate with the external webhook. For example, authorization headers. Header information is not a part of the request URL.	Select Add header, and then enter a key and value. Repeat for additional headers.
   Throttle requests	Optional. Allows setting a frequency rate for your requests. See Throttling. The minimum rate is 100 requests per second.	Enter the number of API requests to allow per second.

5. Select Confirm access rights for request URL.
6. Select Done.

Now you can toggle the Ban List setting to enable it for your project.

Overriding variable default values

If your project has a Ban List enabled and the request URL includes send time variables, you can override their default values for individual messages.

When sending messages using the API, use the ban_list_parameters push option to override values for variables.

In the dashboard, you can override the default values:

• In the Delivery step of the Message, A/B Test, Automation composers
• In the Delivery step when composing each message in a Sequence

In the Delivery step, go to Ban List. Each variable is listed under the heading Default value for <variable>. Enter a new value for any variable.

Bypassing your Ban List

Using the API, include the bypass_ban_list_processing push option and set it to true.

To use this feature in the dashboard, your project Owner or Administrator must first enable the option:

1. Go to Settings.
2. Under Project Configuration, select Manage for Dashboard Settings.
3. Enable Bypass Ban List.
    Important

   Disable this setting when no longer needed to avoid accidentally sending messages to banned users.

Then, when creating messages, enable Bypass Ban List in the Delivery step. Location per ComposerA tool for creating messages in the dashboard. Composers are defined by what you can include and control: message types, delivery, and automation.:

Success, Retry, and Error Conditions

Airship considers any 2xx response from a feed to be a success and will continue a message using the feed response. Airship considers any 3xx and 5xx codes (except 502/503) to be error conditions.