Introduction to In-Browser Messaging

Iterable can send in-app messages to your mobile apps, and to your websites. When you send an in-app messages to a website, it's called an in-browser message.

You might use in-browser messages for welcome messages, offers, account-related updates, or anything else you want your users to see as they're using your website.

Here's how to send in-browser messages from Iterable:

1. In Iterable, define a website integration, which tells Iterable about your website. This allows you to send in-browser messages to it (in-app messages that target a website).

2. Create a Web API key, enabling its JWT authentication setting. You'll use this API key when adding Iterable's web SDK to your website.

3. Set up your servers to handle JWT token requests from Iterable's SDK.

4. Add our web SDK to your website, and configure it to fetch in-app messages, display them, and track related events. This SDK uses JWT authentication.

5. Create an in-app message template, making sure to target your website. In-app message templates targeting a website (in other words, in-browser messages) can contain HTML (a ready-to-display message), raw JSON (for your website to parse and use as needed to display a message or trigger custom functionality), or a combination of both. Also, they can use use in-app message features such as animations, overlays, and priorities.

6. Send your campaign!

# Notes about in-browser messages and Iterable's web SDK

Here are some things to remember about in-browser messages and Iterable's web SDK:

• In-browser messages (in-app messages that target a website) support standard in-app message configurations like message priority, animations, expiration, background overlay, etc.

• You can use Iterable's web SDK to set custom margins and display intervals, autogenerate close buttons, and more. For complete documentation about the web SDK, check out https://github.com/Iterable/iterable-web-sdk.

• The web SDK supports action:// and iterable:// URLs (but not itbl://).

• Iterable's web SDK requires the use of a JWT-enabled API key of type Web. Because of this, to use the web SDK, you'll need to set up a URL (on your servers) from which the SDK can fetch user-specific JWT tokens. To generate these tokens, use the JWT secret Iterable creates alongside your API key.

• The web SDK does not poll for new messages. Instead, it checks for messages when getMessages method is called, which can happen whenever you like (on page refresh, on button click, etc.). If the SDK fetches multiple messages, it will show them in sequence, at a configurable interval.

• The web SDK can be used to pause the display of in-browser messages, for situations where they shouldn't be shown. For example, you might not want to show in-browser messages when a user is viewing a shopping cart.

• The web SDK does not display in-browser messages configured for silent delivery.

• There are no events or metrics specific to in-browser messages. In-browser messages are in-app messages that target a website, and their events have platform set to Web, deviceId set to the user agent associated with the event, and appPackageName set to your app's package name.

• In Messaging Insights and Campaign Analytics, you can view an app-by-app breakdown of some in-app metrics. To do this, hover over or click on a supported metric (for example, Click Rate, Total Clicks, Total Opens, and Total Deliveries).

• The read state of an in-browser message syncs across platforms and devices that can display in-app messages. That is, when you send an in-app message campaign to multiple apps and websites, a user will see it only once.

• The Iterable API endpoint that the web SDK uses to fetch in-browser messages caches them for four hours. Because of this, each time the SDK grabs the same message in that four-hour window, its content will be exactly the same–even if underlying dynamic data (user profile fields, etc.) have changed. This ensures consistent content across devices that fetch data within that period of time.

# Limitations

Some limitations to keep in mind:

• Iterable's Web SDK does not provide an out-of-the-box mobile inbox implementation.

• When displayed by Iterable's web SDK in the Safari web browser, in-browser messages have various limitations:

  • In Safari, standard links embedded in in-browser messages work as expected. However, iterable:// and action:// links are not supported. Clicking them does not do anything.

  • Safari prevents Iterable's web SDK from tracking events when users interact with in-browser messages, which affects your campaign metrics.

  • Iterable's web SDK does not auto-generate close buttons in Safari, regardless of how the SDK is configured (since Safari limitations would prevent them from working). In Safari, users can close in-app messages by clicking outside of them.

# Beta web SDK deprecation

If you've been beta testing in-browser messages (in-app messages that target a website), work with your website engineers to upgrade your website to a non-beta version of Iterable's web SDK as soon as possible. The beta SDK will stop working on January 31, 2023. Starting on that day, the SDK will no longer display in-browser messages or track events.

# Next steps

Next, read Adding Your Website to Iterable.