Content-Type: application/json
Accept: application/vnd.urbanairship+json; version=3
{
"audience": {
"named_user": "sven_svensson"
},
"device_types": [
"web",
"ios",
"android"
],
"notification": {
"alert": "Hello, World!",
"web": {
"alert": "Hello, Web!",
"title": "My First Web Push Title",
"require_interaction": true,
"icon": {
"url": "https://example.com/icon.png"
}
}
}
}
```
### Additional Resources
* [Web Content](https://www.airship.com/docs/guides/messaging/messages/content/web/)
* [Web Platform Overrides](https://www.airship.com/docs/developer/rest-api/ua/schemas/platform-overrides/#weboverrideobject)
## Web SDK
This section is an introduction to the Web SDK and associated methods.
Please visit our [Airship Web SDK Reference](https://www.airship.com/docs/reference/libraries/web-notify-sdk/v2-latest/index.html)
for a complete reference.
### UaSDK
The main Web SDK object. It cannot be instantiated manually. It is returned by the async loader.
#### Creating a Channel
You may create a channel by using the Airship SDK's `create` method; using this
method will make the current browser known to Airship, and allow you to use the
SDK features.
```js
const sdk = await UA
await sdk.create()
```
#### Registering for Push Notifications
Follow these steps to register the current browser with Airship.
* Fetch the browser's subscription object, prompting the user for permission if
necessary.
* Collect browser information for out-of-the-box tag segmentation.
* Register with Airship and resolve the returned channel object.
* Resolves an error that can be caught if there is an error while registering or
if the browser is in an unsupported context.
> **Note:** A request to register for push notifications _must_ happen as the result of a
> user interaction, otherwise the registration will be rejected by the browser
> without prompting the user.
**Example registration**
```js
const sdk = await UA
// now that the SDK is available, add a registration button to the DOM
const button = document.createElement('button')
button.innerHTML = "Register for Notifications"
button.onclick = async (el) => {
await sdk.register()
}
document.body.append(button)
```
#### Checking Browser Capabilities
Make sure that the current browser has web push features AND is in a secure
context capable of attempting registration.
- `sdk.isSupported` is `true` if the SDK can load and track events; web push
support is not considered
- `sdk.isWebPushSupported` is `true` if the browser is supported _and_ supports
web push; it does not consider if the current _context_ is supported (such as
requiring it be added to the home screen on iOS)
- `sdk.isAllowedPushRegistrationContext` is `true` if the browser is currently
in an allowed registration context; note this does not otherwise check for
browser features, so should only be checked after an `sdk.isWebPushSupported`
check
- `sdk.canRegister()` is a comprehensive check against _all_ checks required for
web push registration, and returns a promise that resolves to `true` if:
- the browser supports web push
- the page is a secure context
- the browser is in an allowable context (such as being saved to the home
screen on iOS)
- push permission has not already been denied
Using these methods may be important if you wish to support Safari on iOS or
iPad OS, as those have special requirements before push notification
registration is allowed:
**Checking for Push Notification Registration Support**
```js
const permission = await sdk.getNotificationPermission()
if (permission === 'granted') {
await sdk.register()
}
if (permission === 'denied') {
// user has denied notifications at the browser level, and opt-in is not
// possible without the user changing their browser settings
} else if (sdk.isWebPushSupported && !sdk.isAllowedPushRegistrationContext) {
// prompt user to add the website to their home screen
} else if (await sdk.canRegister()) {
// is in an allowed context; prompt the user to opt into push notifications
}
```
### Channel Object {#channel-object}
The property `sdk.channel` returns the channel interface for the current
browser. It contains methods for retrieving or setting information on the
channel.
**Example**
```js
const sdk = await UA
// the current channel id, a string. will be `null` if no channel exists
const channelId = await sdk.channel.id()
// the current opted-in status, a boolean
const optedIn = await sdk.channel.optedIn()
// opt out the channel for push notifications
const optedIn = await sdk.channel.optOut()
```
### Event Listeners
The channel interface fires a `channel` event when a channel is loaded or
registered.
> **Note:** If you intend to set attributes, tags, named user, or anything that could modify
> the channel within your event listener, make sure to set the `once` option to
> `true` in order to prevent an infinite loop.
```js
const sdk = await UA
sdk.channel.addEventListener('channel', ev => {
console.log('channel id:', ev.detail.id)
}, { once: true })
```
If you are on a page that is in-scope of your push-worker.js: The main SDK
object fires a `push` event when the browser receives a push.
```js
const sdk = await UA
sdk.addEventListener('push', ev => {
// ev.detail is the push payload object
})
```
## Apple Safari Web Push certificates
If your [Web channel was already configured for Safari support](#airship-setup), you must maintain your existing Safari certificate to keep supporting existing users who have opted in to web notifications, even if/when they upgrade to Safari 16 or above. Otherwise, you will need to rebuild your audience.
To create an Apple Safari Website Push certificate, you will need:
* An Apple Developer account
* A Certificate Signing Request (CSR). If you don't already have this file saved locally, [follow Apple's instructions](https://developer.apple.com/help/account/create-certificates/create-a-certificate-signing-request) to create one.
First, download your SSL certificate:
1. Log in to your [Apple Developer account](https://developer.apple.com/account).
1. Go to **Account**, then **Certificates, Identifiers & Profiles**.
1. Select **Identifiers**, select the **Website Push IDs** filter, and then select your web push identifier from the list.
1. Select **Create Certificate** under **Production Certificates**. This will generate a Website Push Notification service SSL (Sandbox & Production) certificate compatible with both the Production and Development environments.
1. Select **Choose File** and upload your CSR file, and then select **Continue**.
1. Select **Download** and save the SSL certificate file for use in the next step. You may need to reload the page if the Download button is not yet active.
Next, install your certificate, export it as a .p12 file, and create a password:
1. Open the certificate you downloaded in the previous step. It should open in the Keychain Access app and be listed in **My Certificates**.
1. 
Select the certificate in the list, then go to the **File** menu and select **Export Items...**.Also be sure to select the **My Certificates** category in the sidebar. If **My Certificates** is not highlighted, you will not be able to export the certificate as a .p12 file.
1. 
Save the file in the Personal Information Exchange (.p12) format.
You will be prompted to create a certificate password, which you will enter when you upload the .p12 file in the Airship dashboard.
Now you can upload the .p12 file and provide the password when [configuring the Web channel in the Airship dashboard](#airship-setup).