Implementing Web SDK v2

The v2 Web SDK supports features not included in v1:

• Web 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., including survey questions and Story format
• Registering browsers without Push Notification Opt-in

Removed Support and Known Issues

Before continuing, confirm that you do not use or require the following features of the v1 SDK, as support for them has been removed:

• HTTP setups — This is also referred to as “secure bridge.” The v2 SDK requires HTTPS on all pages. We removed the registration page plugin, as it was only needed for these setups.
• Multi-domain setups — This is where a single registration was shared across multiple domains or subdomains.
• Safari versions older than 16 (APNs Safari) — Apple started supporting VAPID push in Safari 16 on macOS 13 and above, which was released October 2022.
• AMP — We will continue to support Web configurations that previously had Accelerated Mobile Pages (AMP) enabled, but AMP is not supported for new configurations.

Additionally, APNs Safari registrations are not automatically migrated to VAPID. They must be re-registered using the sdk.register() method.

Integration

Follow the below instructions depending on whether you are performing a new Installation or upgrade.

Setting Up a New Integration

If you have not previously integrated the Airship Web SDK, follow these steps in the Web Getting Started guide:

• Airship Setup
• Add JavaScript Snippet to Web Pages
• Place Service Worker

Then proceed to Channel Registration below.

Updating an Existing Integration

Follow these steps in the Web Getting Started guide to redownload your SDK bundle and replace your existing JavaScript snippets and service worker with the bundle’s updated contents:

• Airship Setup
• Add JavaScript Snippet to Web Pages
• Place Service Worker

Also follow our Developer Migration Guide, which instructs you on migrating your integration to the updated API.

Then proceed to Channel Registration below.

Channel Registration

To use the new features of the v2 Web SDK, you will need to register a channel for browsers that visit your web site. Channel registration no longer requires push notification opt-in. When you choose to do this will be up to your integration, but Airship recommends registering a channel only once a visitor is considered relevant to you.

The following methods are relevant to channel registration:

• UaSDK.create —  Create a channel without prompting for notification opt-in.
• UaSDK.register —  Create a channel prompting for notification opt-in. If the user denies notification permissions, has previously denied it, or if the browser is in an unsupported context this method will throw an error, and not register a channel. See the example below for details on how to approach a push notification registration.

const sdk = await UA
const {channelId} = await sdk.create()
console.debug('registered channel with id:', channelId)

You may decide to register that channel for push notifications at a later date using the register() method, as usual. Note that if you are calling register() you do not need to also call create():

const sdk = await UA
if (sdk.isWebPushSupported && sdk.isAllowedPushRegistrationContext) {
  // prompt the user to install to their home screen so notification
  // registration may be requested.
} else if (await sdk.canRegister()) {
  const {channelId} = await sdk.register()
  console.debug('opted in push notifications for channel with id:', channelId)
}

Using the v2 SDK and Instrumenting Your Application

For detailed v2 SDK usage information, see the API Documentation.

To get the most out of the v2 SDK, we recommend instrumenting your website or web application to emit events for triggering and event segmentation. See Instrument your Application in the In-App Experiences documentation.

Custom Domain Proxy

If you intend to use Web 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., you should send Airship traffic through your own domain in order to provide a consistent brand experience and avoid blocked content. See Custom Domain Proxy.