Push Notifications

Airship’s SDK provides a simple interface for managing web push notifications.

User Registration

A user is registered when they opt in to receiving notifications via the system dialog, which varies slightly from browser to browser. The dialog is presented when the page invokes the sdk.register() function. As a best practice, we discourage calling this function on page load, before the user has had a chance to assess the potential usefulness of notifications from your site. See Registration UI for a simple, sample UI element that registers a user.

In any case, this moment when a user decides whether to allow or block notifications is when we will either register a channel for them with an opt-in status, or not.

The SDK returns this registration event to Airship, along with the user’s registration status and certain metadata, namely device property tags. When you send a push notification to a web user, their registration status is returned to Airship via the push service.

Registration Status

A user’s registration status is one of:

  • Opted-in: Allowed notifications and has not subsequently disallowed them, either via browser settings or by calling the optOut() method.
  • Opted-out: Initially allowed notifications but subsequently disabled them.
  • Uninstalled: A user is considered to be Uninstalled if they have both:
    1. Opted out via the browser settings, AND
    2. Not returned to the website.
 Note

Analytics must be enabled to determine registration status. See: Analytics and Reporting.

A user can change their opt in/out status in two places:

  1. The browser’s settings.
  2. The website’s registration UI.

Registration UI

If a user is immediately presented with a notification permission dialog without knowing what sort of notifications to expect from your site, chances are higher that they will decline, making it difficult to reengage with them in the future.

It is a best practice to explain the value of your notifications before displaying the system notification opt-in prompt.

We provide plugins in the SDK to help you customize this initial prompt.

 Note

Browser Trends

Many popular web browsers have recently made updates that require a user gesture before you can trigger the notification prompt, i.e., you cannot immediately ask for permission on page load.

This is true as of Safari 12.1 and Firefox 72, and we expect this trend to continue with other browsers. This is another good reason to implement a soft prompt as part of your acquisition strategy.

Plugins

Our Web SDK plugins can be optionally loaded to help you customize the user onboarding flow.

When loading a plugin, you will provide the url for the Airship CDN-hosted plugin along with an options object. URL and options values are provided in the specific plugin sections below.

UA.then(function(sdk) {
   sdk.plugins.load('my-plugin', 'https://my.plugin.url', {my_option: 'my_value'})
     .then(plugin => plugin.myMethod())
})

Use the .load(pluginName: "html-prompt" | "registration-page", url: string, options: object) method to load the plugin.

See our Web SDK Reference for more details.

HTML Prompt

This plugin provides a utility that allows users to express their interest in receiving notifications prior to registering their channel.

It is a best practice to explain the value of your notifications before prompting the opt-in flow. Using a soft prompt also gives users the chance to politely decline for now, without setting the browser permission to denied, giving you the chance to request again at a later time.

Currently two HTML prompt templates are available:

  • alert — a basic alert, with configurable title, message, logo, and button fields:
  • bell — a small bell that stays fixed on the page:

This plugin can be used in conjuction with the Registration Page plugin, if you are integrating on any non-HTTPS (HTTP) domains.

URL, Options and Methods

When loading the plugin, you will provide the url for the CDN-hosted plugin along with an options object. URL values and available options and methods are described below.

URL

The URL will differ depending on whether you are using our North America or EU data center.

  • North America: https://aswpsdkus.com/notify/v1/ua-html-prompt.min.js
  • EU: https://aswpsdkeu.com/notify/v1/ua-html-prompt.min.js

Options

These options apply to either the alert or bell templates. Optional.

KeyTypeDefaultDescription
UAstringUAUA global variable used in your SDK snippet.
appearDelaynumber0Delay, in miliseconds, before displaying the prompt. Useful when auto is set to true.
disappearDelaynumber0Delay, in miliseconds, before the prompt to automatically. disappears.
askAgainDelaynumber1209600 (2 weeks)Delay, in seconds, before prompting uuser again after dismissing the prompt.
stylesheetstringnullCSS Stylesheet url to customize the prompt appearance.
autobooleanfalseWhether to automaticaly display the prompt on page load.
typestringalertTemplate to use. One of alert or bell.

Alert Template Options

Specific options to the alert template. All are optional.

KeyTypeDefaultDescription
positionstringtopThe position of the alert on the webpage, top or bottom.
i18n.{lang}.titlestring‘Subscribe to our notifications’Alert title.
i18n.{lang}.messagestringen: ‘Stay tuned and get our best offers by subscribing to our push notifications.’Alert message.
i18n.{lang}.acceptstringen: ‘Yes, Subscribe me!’‘Accept’ button label.
i18n.{lang}.denystringen: ‘No thanks’‘Deny’ button label.
logostringnullLogo URL to be displayed in the alert.

Bell Template Options

KeyTypeDefaultDescription
positionstringbottom-leftThe position of the bell on the webpage. One of top-left, top-right, bottom-left, or bottom-right.

Methods

  • .prompt(options = {}): Trigger the display of the HTML prompt. More options can be passed into this method to override the ones passed when loading the plugin.
UA.then(function(sdk) {
   sdk.plugins.load('html-prompt', 'https://aswpsdkus.com/notify/v1/ua-html-prompt.min.js', {stylesheet: 'https://my.domain/path/to/some.css', askAgainDelay: 3600})
    .then(plugin => plugin.prompt())

Registration Page

When integrating the Airship SDK on a non-HTTPS website, this plugin allows you to open a registration page inside a popup on the correct HTTPS-enabled registration domain to collect user opt-in permission.

It can be used in conjunction with the HTML Prompt plugin.

 Note

Prerequisite: You must upload the registration-page.html file from the SDK bundle to your website and make it accessible through HTTPS.

URL, Options, and Methods

When loading the plugin, you will provide the url for the CDN-hosted plugin along with an options object. URL values and available options and methods are described below.

URL

The URL will differ depending on whether you are using our North America or EU data center.

  • North America: https://aswpsdkus.com/notify/v1/ua-registration-page.min.js
  • EU: https://aswpsdkeu.com/notify/v1/ua-registration-page.min.js

Options

The following attributes are optional but we strongly recommend setting url with the fully-qualified HTTPS URL of your registration-page.html file, and i18n according to your users’ primary region.

KeyTypeDefaultDescription
defaultLanguagestring‘en’Default language to be used when translation is not available
widthnumber600Popup width
heightnumber390Popup height
urlstring‘./registration-page.html’Registration page URL
i18n.{lang}.titlestring‘…’Popup title
i18n.{lang}.messagestring‘…’Message displayed in the popup
i18n.{lang}.bubblestring‘…’Message displayed when permission is denied
i18n.{lang}.buttonstring‘…’Message displayed in button when user interaction is needed
positionstring‘middle_center’Popup position. One of top_center, top_left, top_right, bottom_center, bottom_left, bottom_right, middle_center, middle_left, middle_right

Methods

  • .open(options = {}): Open the registration page popup. More options can be passed into this method to override the ones passed when loading the plugin.
// this a just a simple example - you should bind this code to a click event
// to get it compatible with most browsers
UA.then(function(sdk) {
  sdk.plugins
    .load('registration-page', 'https://aswpsdkus.com/notify/v1/ua-registration-page.min.js', {
      i18n: {
        fr: {
          title: 'Autoriser les notifications Web',
          message: 'Souscrivez aux notifications',
          bubble: 'Changez la permission pour permettre les notifications',
          button: 'Autoriser'
        },
        en: {
          title: 'Opt in to Web Notifications',
          message:
            'Subscribe to web notifications by clicking [Allow] in the prompt.',
          bubble: 'Unlock permission to allow notifications',
           button: 'Allow'
        }
        // you can also use locales to set more specific messages
        // 'en-US': [...],
        // 'fr-CA':  [...]
      }
    })
    .then(plugin => plugin.open())
})