Setting up Web Push Notifications

With Iterable, you can send web push campaigns to Chrome, Firefox, Opera, and Safari web browsers. Google's Firebase Cloud Messaging (FCM) delivers these messages using the FCM HTTP v1 API.

Iterable supports one web push integration per project.

# In this article

# Overview

To get started sending web push notifications from Iterable, your web developer needs to make the following changes to your website or web app:

• Create a Firebase account and project.
• Configure Firebase in your website or web app, as described below.
• Create a prompt for users to opt in to web push notifications.
• Add an event listener for web push clicks that tracks them in Iterable.

# Functional requirements

To set up web push notifications, configure your website to:

• Initialize Firebase Cloud Messaging (FCM).
• Prompt users for permission to send web push notifications.
• When permission is granted, fetch the user's browser token and pass it to Iterable using the POST /api/users/registerBrowserToken API endpoint and a Web API key.
• Accept and display incoming web push notifications from FCM.
• Capture click events on web push notifications and send them to Iterable using the POST /api/events/trackWebPushClick API endpoint and a Web API key.

# Step 1: Configure Firebase

To send web push notifications from Iterable, first configure Firebase Cloud Messaging (FCM) to send messages to your users' browsers. To do this:

• Create a new Firebase project.
• Get your Firebase project's Sender ID, VAPID key, and other configuration details.
• Create a Firebase service account.
• Create and download a JSON private key for the FCM HTTP v1 API.

# Step 1.1: Create a new Firebase project

1. Log in to Firebase (or create an account if you don't already have one.)
2. Create your project in the Firebase Console and register your app by following Step 1: Create a Firebase Project and Register your app.
3. Install and initialize the Firebase SDK by following Step 2: Install the SDK and initialize Firebase.
4. Add Firebase Cloud Messaging (FCM) to your web app by following Set up a JavaScript Firebase Cloud Messaging client app.

# Step 1.2: Get your Firebase project's configuration details

Grab configuration details from your Firebase project:

1. From the Firebase console, click the gear icon next to Project Overview in the top left corner of the screen, and select Project Settings.
2. In the General tab, scroll down to the Your Apps section.
3. In the SDK setup and configuration section, see the code snipped to collect the configuration details for your Firebase project:
   • apiKey
   • authDomain
   • projectId
   • storageBucket
   • messagingSenderId
   • appId
4. In the Cloud Messaging tab, find Web Push Certificates. You can find the public key (VAPID key) here. This is used to authenticate when your website retrieves the user's browser token.

You need these values to configure your website to send web push notifications. You also need the messagingSenderId value to configure your Iterable project to use the new FCM API in step 2 below.

# Step 1.3: Create a Firebase service account

Next, create a Firebase service account for the website you're testing, and give it sufficient permission to send web push notifications on your behalf (when you create a private key in the next step, you'll associate it with this Firebase service account):

1. From the Firebase console, click the gear icon next to Project Overview in the top left corner of the screen, and select Project Settings.

2. Go to the Service Accounts tab.

3. Click Manage Service Account Permissions.

4. To create a new Firebase service account, click Create Service Account.

5. Under Service Account Details:

   • Enter a name, account ID, and description.
   • Then, click Create and Continue.

6. Under Grant This Service Account Access to Project:

   • Select a role: Firebase Cloud Messaging API Admin, or a custom role with permission cloudmessaging.messages.create.
   • Click Continue.

7. Under Grant Users Access to This Service Account:

   • Leave both fields blank.
   • Click Done.

# Step 1.4: Create and download a JSON private key for the FCM HTTP v1 API

Now, create and download a JSON private key associated with the Firebase service account you just created:

1. Make sure you're still in the Firebase console, in the correct project.
2. On the Service Accounts page, in the row for your new Firebase service account (created in the previous step), click the three dots in the Actions column. Then, choose Manage keys.
3. Select Add Key > Create new key, and choose JSON.
4. Click Create. This creates the JSON key and downloads it to your machine.

You'll use this JSON private key to configure your Iterable project to send web push notifications.

# Step 2: Configure Iterable

To configure your Iterable project to send web push notifications:

1. Sign in to your Iterable project with a user who has the Setup and Manage Channels permission.

2. Go to Settings > Web Push.

3. In the HTTP V1 row of the Integrations table, click Configure.

   

4. In the Configure Firebase Integration window, upload your JSON private key file, and enter your Firebase project's Sender ID (both from step 1, above).

   

5. Click Save.

Once you save the configuration, Iterable offers to send a test web push notification to verify that the new private keys work as expected.

After configuration, Iterable does not display the sender ID again or allow downloading of the JSON private keys from the UI. If you need to update them, you can do so by re-uploading the JSON private key file.

# Step 3: Configure your website

To send web push notifications from Firebase to a given user, you need to first get the user's permission. If they consent, you'll retrieve the user's browser token and save it on their Iterable user profile, so Iterable can use it for future sends.

To do this, follow these steps:

1. Add <link rel="manifest" href="/manifest.json"/> in the <head> section of your webpage.

   Example:

   <!doctype html>
   <html lang="en">
   <head>
       <link rel="manifest" href="manifest.json"/>
       <!-- ... -->
   </head>
   <body></body>
   </html>
   

2. Download manifest.json and firebase-messaging-sw.js from the Firebase quick start samples, and place them in the root directory of your website.

   The line "gcm_sender_id": "103953800507", found in the manifest.json file, is the same across all projects. It is a constant value for Firebase. Do not edit or change this line.

   You can customize the display value in the manifest.json file to determine how your web app appears when launched from the home screen. For Safari, the value should be "standalone" or "fullscreen". (Learn more about Safari-specific configurations below.)

   You can also add any other available settings you might want to use in the manifest. To learn more about configuring this file, read MDN Web Docs: Web App Manifests.

3. Follow Google's Firebase documentation to set up Firebase Cloud Messaging on your website.

   Make sure your site meets these functional requirements for sending Iterable web push notifications using FCM:

   • The site should prompt the user for permission to send push notifications.

   • If permission is granted, it should fetch the user's browser token and then pass it to Iterable using the POST /api/users/registerBrowserToken API endpoint and a Web API key.

   • The site needs to accept and display incoming web push notifications from Firebase Cloud Messaging. You can accept notifications in the foreground to display to your user while they are on your website and/or in the background which sends a true push notification when the service worker is online. For instructions, read Firebase: Receive messages in a JavaScript client.

   • The site should also capture click events on web push notifications and send them to Iterable using the POST /api/events/trackWebPushClick API endpoint and a Web API key.

# FCM message JSON payload

When you send a web push notification from Iterable, the message payload is delivered to Firebase Cloud Messaging (FCM), which then sends the notification to the user's browser.

This payload includes fields from Iterable that you can use to track web push events in Iterable, including:

• Campaign details (campaignId, templateId)
• User details (userId and/or email)

Example FCM message payload:

{
  "from": "<YOUR-FCM-SENDER-ID>",
  "messageId": "<UNIQUE-FCM-MESSAGE-ID>",
  "notification": {
    "title": "My notification title",
    "body": "Example message body.",
    "icon": "<YOUR-ICON_URL>"
  },
  "data": {
    "userId": "some-user-id",
    "messageId": "<UNIQUE-ITERABLE-MESSAGE-ID>",
    "templateId": "00000000",
    "campaignId": "00000000",
    "email": "user@example.com",
    "projectId": "00000" // Your Iterable project ID
  },
  "fcmOptions": {
    "link": "<YOUR-CLICK-URL>"
  }
}

# Tips for managing browser tokens

• In Iterable, a browserTokens user profile field captures the user's browser token. This is an array, and can capture multiple values over time. Calling Iterable's registerBrowserToken API endpoint with a new token appends the new token to the browserTokens array on the user's profile. It does not de-register or replace existing tokens.

• Firebase manages and sometimes disables browser tokens, using their own algorithm. If Firebase determines that a token is outdated, you may need to re-prompt users for web push permission. Users who have not enabled browser tokens on their profiles will be suppressed from web push send attempts.

• If you have collected users' browser tokens in the past, you can import them into Iterable using the same POST /api/users/registerBrowserToken API endpoint mentioned in step 3, above.

• If you're working in an email-based project and the user's email address isn't available (for example, if the user hasn't logged in), you can register the browser token for an unknown user by leveraging our placeholder.email domain convention to pass Iterable a placeholder email address with the token. For more information, read Handling Anonymous Users.

# Supporting web push on Safari browsers

To send web push notifications to Safari users, there are a few additional steps to take after completing the steps above to enable web push notifications on Sarafi browsers for macOS and iOS.

Iterable supports web push notifications on these versions of Safari:

• macOS - Safari 16 for macOS Ventura (13) or later
• iOS - iOS 16.4 or later

To learn more about supporting web push on Apple devices, read Sending Web Push Notifications in Web Apps and Browsers (Apple).

For a complete guide to updating your web app to support Safari, read Safari Web Push Notifications (Firebase blog).

# Limitations

There are some limitations when sending web push notifications to Safari users:

• Images - Safari does not display images in web push notifications, so if you attach an icon to your web push template, Safari users will not see it.

• Tracking clicks - iOS does not support web push click tracking in the Safari browser. This is because the necessary functionality for the notificationclick event is not supported by the operating system. To learn more, read ServiceWorkerGlobalScope: notificationclick event (MDN web docs).

  You may consider an alternative approach to tracking web push clicks on iOS, such as a redirect URL in the click location for the web push campaign template.

• Home screen - To receive web push notifications on iOS, users must add your website to their home screen. This is a requirement for web push notifications to work on iOS. Apple does not provide a way to prompt users to add your website to the home screen, so you'll need to instruct users to do this manually.

# Supporting web push on Safari for macOS

To enable web push for Safari, wrap the requestPermission() API inside a user action, like a button click.

To see an example of how to do this, read Mozilla's developer documentation here: requestPermission() API.

# Supporting web push on Safari for iOS

iOS users can receive notifications from your website when these conditions are met:

• The user has added your website to their home screen.
• The user has granted permission to receive notifications.

To get Iterable's web push working on iOS, you need to:

• Add "display": "standalone" or "display": "fullscreen" to the manifest.json file. Depending on when you created your project, you may already have this set. This determines how your web app appears when launched from the home screen.

  To understand the difference between these options, read MDN Web Docs: display.

  Example manifest.json:

  {
    "gcm_sender_id": "103953800507",
    "display": "standalone"
  }
  

• Ask your users to add your web app to the home screen. For web push notifications to work on iOS, this is a requirement.

  To instruct iPhone and iPad users to add your website to the home screen, ask them to tap the share icon in Safari, then tap Add to Home Screen.

  

# Sending a test web push notification

After you've configured your website and Iterable project to send web push notifications, you can send a test notification to verify that everything is working as expected.

To send a test web push notification:

1. First, set up a test user in your website who has agreed to receive web push notifications and has a browser token associated with your local machine.
2. In Iterable, go to Settings > Web Push.
3. In the row for HTTP V1, click the Test Push button.
4. In the Test Firebase integration window, enter a browser token for a test user who has agreed to receive web push notifications from your website.
5. Click Send test push notification.

# Troubleshooting web push notifications

If a test message doesn't arrive as expected, try the following:

• Make sure that the user to whom you're sending the test message has agreed to receive web push notifications from the website in question.
• Make sure you're using the correct browser token.
• Make sure the FCM private key file (JSON) you uploaded to Iterable is connected to a Firebase service account associated with the website you're testing.
• Make sure the Firebase service account associated with the FCM private key has permission cloudmessaging.messages.create.

If the test user still doesn't receive your test web push notification, contact Iterable support.

# Re-uploading your private key

If you accidentally uploaded the wrong private key (JSON file), follow these steps to try again:

1. In Iterable, in the row associated with the web push integration you're updating, click the overflow menu (three dots). From this menu, select Edit Integration.
2. In the Configure Firebase Integration window, upload the correct private key (JSON file), enter the correct Sender ID, and click Save.
3. In the Test Firebase integration window, send a test push notification.