Articles in this section

Web Push Overview

With Iterable, you can send web push campaigns to Chrome, Firefox, and Opera web browers. Google's Firebase Cloud Messaging (FCM) delivers these messages.

In this article

Setup instructions

To get started sending web push notifications from Iterable, follow these instructions:

Step 1: Configure Firebase

First, create a Firebase account. Then:

  1. From the Firebase Console, create a project.

  2. Set up a Firebase service account with appropriate permissions, and download JSON private keys for that account. For details about how to do this, read Web Push Notifications: Migrating to the FCM HTTP v1 API.

  3. Also, note your Firebase project's sender ID.

Step 2: Configure Iterable

To configure your Iterable project to send web push notifications:

NOTE

Iterable supports one web push integration per project.

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

  2. Navigate to Settings > Web Push.

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

    The Settings > Web Push page in Iterable

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

    Uploading a JSON private key for FCM

  5. Click Save.

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.

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

    The gcm_sender_id 103953800507 found in the manifest.json file should be the same across all projects. Please do not edit or change this.

  3. Follow Google's Firebase documentation incorporate a JavaScript snippet into your webpage.

    • Prompt the user for permission to send push notifications.

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

    • In Iterable, a browserTokens user profile field captures the user's browser token. This is an array, and can capture multiple values over time.

    • 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 leverage our placeholder.email domain convention to pass Iterable a placeholder email address with the token. For more information, read Handling Anonymous Users.

NOTES

  • 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.

Step 4: Capture click events

To capture web push clicks in Iterable, call Iterable's POST /api/events/trackWebPushClick API.

IMPORTANT

  • To call this API, use a JavaScript or Web API Key, which have limited access to Iterable's API. If possible, we recommend using JWT authentication for additional security.
  • Never embed server-side API keys in client-side code (whether JavaScript, a mobile application or otherwise), since they can be used to access all of your project's data.

Frequently asked questions

How do I create web push templates and campaigns?

Where can I find more information on Firebase?

Check out https://firebase.google.com/.

Which browsers does web push work on?

Chrome, Firefox, and Opera.

Does a user's browser token change from session to session?

A Firebase algorithm decides when to invalidate a token, in which case the client side JavaScript needs to register the new token for the user in Iterable. Generally this is about once per month.

If a user's browser window is closed, will they still receive the notification?

Yes. Even if the user closes the browser window, the service worker running in the background will display the notification. However, if the user quits out of the browser completely (not just the window or tab), then all service workers will be killed and they will receive no notification.

Will messages be queued if they are unable to display initially?

No. Messages will not deliver if the browser process isn't running at send time.

What metrics can I track with web push?

Iterable supports web push send and click events. In order to track web push click events, you must configure your website to capture click metrics. Please see above for more information on how to track web push click events.

Want to learn more?

For more information about some of the topics in this article, check out this Iterable Academy course. Iterable Academy is open to everyone — you don't need to be an Iterable customer!

Related articles