Notifications and surveys

How Bubbl shows a notification, what its notification screen does with media, calls to action and surveys, and how to show a message again.

A notification reaches the device in one of three ways: a geofence the device entered, a push, or a pull (missed pushes are fetched when the app comes to the front). Whichever way it came, Bubbl shows it the same way, once per install.

How a notification shows#

• Your app is in front: Bubbl's notification screen opens straight away over your app.
• Your app is in the background or closed: Bubbl posts a system notification. Tapping it opens the notification screen.
• The same notification twice (say, by push and by pull): it's shown once. Bubbl remembers the last 200 notifications per install.

On iOS, a push's alert is drawn by iOS itself without running your app. Its picture needs a notification service extension: see Pictures on iOS pushes. On Android, Bubbl draws every notification itself, on its own channel. On Android 13 and later that needs the notification permission; without it, a notification that arrives with the app in the background isn't shown.

If you'd rather show a notification in your own UI, set a notification listener: see Drawing notifications yourself.

The notification screen#

The screen is a card over your app, following the system's light or dark appearance:

• a close button inside the card's top-right corner, over any media;
• the headline and body;
• media: an image, video, audio, or a YouTube video. Video and YouTube play inside the card (YouTube as a youtube-nocookie embed; links open outside, and full screen works). Audio has its own player with play and pause, a seek bar, and elapsed and total time. Nothing plays until the user taps Play;
• a call to action button, which opens the notification's link.

You can change its colours, sizes and every piece of text: see Appearance and text.

Surveys#

A survey opens as a wizard, one question per step, with progress, Back and Next. A required question blocks Next until it's answered. After the last question, a thank-you step carries the call to action, if the survey has one. Answers are checked against the same rules the server uses before they're sent.

What Bubbl records#

Bubbl records each step of a notification's life for your campaign reports: received, displayed, opened (from its system notification), the call to action, dismissed, media viewed and completed, and survey started and submitted. You don't report anything yourself unless you draw notifications in your own UI. Your app can listen to the same steps as events: see Segments and events.

On iOS, notification.received can't come on delivery, because iOS draws alert pushes without running the app. It comes when the app first sees the notification: a push arriving with the app in front, a push tapped, a pull, or a geofence's notification. The server counts delivery when Apple accepts the push.

Sandbox notifications#

A notification from a Sandbox workspace has a headline starting "Sandbox · " and shows a SANDBOX ribbon on Bubbl's screen, so nobody mistakes it for a live campaign. isSandbox is true on its message.

The message#

Your notification listener and events hand you a BubblMessage:

• id: the notification's ID; echo it on anything you report about it;
• headline, body;
• isSurvey, isSandbox;
• mediaType (image, video, audio, youtube, application, text or file, or null without media), mediaUrl, mediaThumbnailUrl;
• ctaLabel, ctaUrl;
• questions: a survey's questions in order, empty for a message;
• json: the whole notification as Bubbl sent it.

See BubblMessage for the types on each platform.

Showing a message again#

To keep messages in an in-app inbox, store the message's json, then turn it back into a message and hand it to present, which opens Bubbl's notification screen. openCta opens a message's call to action the way the screen would, and reports the click.

val message = BubblMessage.fromJson(savedJson) ?: return   // null if it isn't one
Bubbl.present(message)

guard let message = BubblMessage(json: savedJson) else { return }   // failable
Bubbl.present(message)

// Keep the BubblMessage you were given (its json field is the notification as Bubbl sent it)
await Bubbl.present(message);

// Keep the BubblMessage you were given (Bubbl uses its json field)
Bubbl.present(message);