Articles in this section

Web Push Overview

Avatar
Chris
  • Updated
Follow

Iterable's web push offering allows you to push blast and triggered notifications to subscribers using the Chrome, Firefox or Opera browsers (Safari support will be added in a future release). Google's Firebase Cloud Messaging (FCM) service is used to deliver these messages. You can find more information about Firebase on their website.

A web push notification will resemble the following:

 

Getting Started

Configuring Firebase

In order to leverage the web push service, you will first need to register for Google Firebase and then follow the steps below.

  1. Create a project within the Firebase Console
  2. Within the Console, navigate to Project Settings > Cloud Messaging, and take note of your server key and sender ID

 

Integrating Firebase into Your Website

In order to send Firebase-based messages, you will need to first prompt users with a message asking for permission. If permission is given, you will retrieve the user's browser token and then feed it to Iterable for use with future sends. The following setup is required in order to do this.

  1. Add <link rel="manifest" href="/manifest.json" /> in the <head> section of your webpage
  2. Download the manifest.json file here and firebase-messaging-sw.js here, 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 here to incorporate a JavaScript snippet into your webpage. This snippet should serve two purposes:
    1. It should prompt the user with a pop-up asking for permission to send push notifications
    2. If permission is granted, it should fetch the user's browser token and then pass it to Iterable using the registerBrowserToken API endpoint
      • A user profile field, browserTokens, will then reflect the browser token value for each user who accepts notifications. This is an array, which is capable of accepting multiple values over time.
      • If the user's email address is not available (for example, if the user is not logged in), you may leverage our placeholder.email convention to pass Iterable a placeholder email address with the token.

Note that browser tokens are managed and sometimes disabled by Firebase using their own algorithm. If Firebase determines a token to be 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.

Also worth noting, if you have collected users' browser tokens in the past, you can import them into Iterable using the same registerBrowserToken endpoint as in step 3.1 above.

Configuring Your Website to Capture Click Metrics

In order to capture web push clicks in Iterable, you must call on our trackWebPushClick endpoint. Feel free to reference the below JavaScript when setting this up.

notification.onclick = function () {
   window.open(payload.notification.click_action);
   // This is how to track web clicks.
   var url = "https://api.iterable.com/api/events/trackWebPushClick";
   var method = "POST";
   var postData = {
      'email': 'bryan@iterable.com', // Put identifier here
      'messageId': payload.data.messageId,
      'campaignId': payload.data.campaignId,
      'templateId': payload.data.templateId
   };
   var async = true;
   var request = new XMLHttpRequest();
   request.open(method, url, async);
   request.setRequestHeader('Content-Type', 'application/json; charset=UTF-8');
   request.send(JSON.stringify(postData));

   var xhr = new XMLHttpRequest(); };

 NOTE: campaignId must be an integer

Connecting Your Firebase Instance to Iterable

In order to send Firebase-based messages via Iterable, you will need to navigate to the Integrations > Web Push page in Iterable. From here:

  1. Click "Create Push Integration" to add a new integration
  2. Select "FCM" and then enter your Firebase server key and sender ID (from Step 2 in "Configuring Firebase" above)

 

Creating Web Push Templates and Campaigns

The same steps apply for campaign creation as for email, SMS, push and in-app notifications - you will want to select the associated message format, seed and suppression lists, and template. More information can be found here for blast campaigns and here for triggered campaigns. Documentation for the specific API call for triggered web push messages can be found here.

The template creation and editing process is similar to what you'll find with the other formats.

  1. Name your template
  2. [Optional] Give your notification a title, which will display in bold on the top of the message
  3. [Optional] Give your notification a body message, which will display under the title if there is one
  4. [Optional] Provide an icon URL, which will display the associated image on the left side of the message
  5. [Optional] Provide an HTTPS click action URL, which will dictate the page that the user will be directed to if he or she clicks on the notification

Note that title or body contents are required in order to save the template. This acts as a safeguard against sending blank messages.

Note: Your project name will display under the title and body in the preview. In proofs and the live sends, however, this will display your website name (eg. "iterable.com").

 

Frequently Asked Questions

Q: Does Firebase have any associated costs?
A: No, Firebase is free (as of September 2017).

Q: Where can I find more information on Firebase?
A: See Google's Firebase support page here.

Q: Which browsers does web push work on?
A: Currently, Chrome, Firefox and Opera. We plan to support Safari in the future via Apple's Push Notification Service.

Q: Does a user's browser token change from session to session?
A: 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.

Q: If a user's browser window is closed, will they still receive the notification?
A: 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.

Q: Will messages be queued if they are unable to display initially?
A: No. Messages will not deliver if the browser process isn't running at send time.

Q: What metrics can I track with web push?
A: We support both 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.

 

Related articles

Comments

0 comments

Please sign in to leave a comment.