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, in part of the screen, close it from your app or preview it.

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.

Question typeThe answer
Single choiceOne choice
Multiple choiceOne or more choices
RatingA whole number from 1 to 5
Yes or noTrue or false
NumberA number
Slider0 to 10 in steps of 0.5; no thumb shows until it's touched
Open-endedText, up to 2000 characters

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#

Sandbox workspaces aren't open on production yet. This applies to a workspace that has one.

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.

KOTLIN
val message = BubblMessage.fromJson(savedJson) ?: return   // null if it isn't one
Bubbl.present(message)
SWIFT
guard let message = BubblMessage(json: savedJson) else { return }   // failable
Bubbl.present(message)
DART
// Keep the BubblMessage you were given (its json field is the notification as Bubbl sent it)
await Bubbl.present(message);
TS
// Keep the BubblMessage you were given (Bubbl uses its json field)
Bubbl.present(message);

Showing a message in part of the screen#

Since 5.2.0, present can lay the card out inside a region of the screen instead of across it, for a foldable's one pane or a split layout, say. Pass a BubblPresentationRegion: insets from the screen's edges, an optional maxWidth for the card and an optional scrimOpacity for the dimmed background. Without a region, present(message) works as before.

KOTLIN
// The card sits in the part of the screen left of a 400 dp pane
Bubbl.present(message, BubblPresentationRegion(trailing = 400f, maxWidth = 360f, scrimOpacity = 0.3f))
SWIFT
// The card sits in the part of the screen left of a 400 pt pane
Bubbl.present(message, region: BubblPresentationRegion(trailing: 400, maxWidth: 360, scrimOpacity: 0.3))
DART
// The card sits in the part of the screen left of a 400 px pane
await Bubbl.present(message, region: const BubblPresentationRegion(trailing: 400, maxWidth: 360, scrimOpacity: 0.3));
TS
// The card sits in the part of the screen left of a 400 px pane
Bubbl.present(message, { trailing: 400, maxWidth: 360, scrimOpacity: 0.3 });
  • The insets are measured from the screen's own edges, in points on iOS and dp on Android. leading and trailing are the screen's left and right, not the text direction's. Any you leave out are 0.
  • The card is centred in the area the insets leave, up to maxWidth wide (480 by default), and scrolls inside it if it's too tall. scrimOpacity is 0 to 1; leave it out for Bubbl's usual dimming.
  • Bubbl's screen still covers the whole screen. A tap outside the card lands on the dimmed background, not on your app behind it, and doesn't close the card.
  • On iOS the insets ignore the safe area. On Android the card also keeps clear of the system bars, the display cutout and the keyboard.
  • A region applies only to present. Notifications Bubbl shows itself, from a push or a geofence, still use the whole screen.

See Presentation region for the fields on each platform.

Closing it from your app#

Since 5.2.0, Bubbl.dismissPresented() closes the notification screen that's showing, if any. Bubbl reports it dismissed just as it does when the person taps the close button; if they had already answered, opened the media or tapped the call to action, nothing more is reported. It does nothing when no screen is showing, so it's safe to call when your layout changes.

KOTLIN
Bubbl.dismissPresented()
SWIFT
Bubbl.dismissPresented()
DART
await Bubbl.dismissPresented();
TS
Bubbl.dismissPresented();

On iOS, Bubbl queues notifications that arrive while one is showing. dismissPresented() closes the one on screen and doesn't clear the queue, so the next one shows straight afterwards, as after any close. Android shows one at a time, with no queue.

Previewing a notification#

Since 5.2.0, present has a preview mode for a notification that no campaign delivered to this device, such as a list of sample notifications your app keeps. Such a notification has no campaign delivery behind it, so Bubbl can't report its normal events. With preview set, Bubbl reports none of its notification, survey or media events (for example notification.displayed, notification.dismissed, survey.submitted and media.viewed), including the dismissal from dismissPresented(). Showing it records exactly one custom event instead, showcase.preview_opened, with the message's id as notification_id. Your own event listeners are still told about everything.

KOTLIN
Bubbl.present(message, preview = true)                  // add region = … to confine it
SWIFT
Bubbl.present(message, preview: true)                   // add region: … to confine it
DART
await Bubbl.present(message, preview: true);            // add region: … to confine it
TS
Bubbl.present(message, undefined, { preview: true });   // pass a region instead of undefined to confine it
  • Preview is opt-in. Without it, nothing changes.
  • A preview is shown on screen only, never as a system notification, and it combines with a region.
  • The custom event goes through Bubbl's usual event queue, so it shows in the activity log like any custom event.