Skip to content

In-App Messaging reference

At a glance

  • InAppMessaging.in_app_messaging(): message_display_suppressed, automatic_data_collection_enabled, trigger_event(name)
  • Listeners: add_impression_listener(fn(message)), add_click_listener(fn(message, action)), add_dismiss_listener(fn(message, dismiss_type)), add_error_listener(fn(message, error)); each returns a function that removes it
  • Your own display: set_display(handler(message, delegate)), use_default_display(); DisplayDelegate: impression(), clicked(action=None), dismissed(dismiss_type), failed(code, description), finished
  • Messages: ModalMessage, BannerMessage, CardMessage, ImageOnlyMessage (all InAppMessage: campaign, type, trigger_type, app_data); CampaignInfo, ImageData, ActionButton, Action, default_action(message)
  • Constants: MessageType, TriggerType, DismissType, InAppMessagingErrorCode; errors are InAppMessagingError

pyios_firebase.in_app_messaging

Firebase In-App Messaging: messages shown inside the app, from campaigns made in the Firebase console.

Not the same product as Cloud Messaging (pyios_firebase.messaging): these messages are not push notifications; they show while the app is open.

Firebase fetches the campaigns and shows their messages by itself, with its own screens, when the app comes to the foreground or on an Analytics event::

from pyios_firebase.in_app_messaging import InAppMessaging

iam = InAppMessaging.in_app_messaging()
iam.add_click_listener(lambda message, action: open_screen(action.url))
iam.trigger_event("level_done")          # show the campaigns of this event
iam.message_display_suppressed = True    # not now (for example mid-game)

To draw the messages yourself (a Kivy popup...), see InAppMessaging.set_display.

Needs the FirebaseInAppMessaging-Beta Swift package product.

Modules:

Name Description
in_app_messaging

InAppMessaging: settings, events, listeners, and showing messages your way.

messages

The in-app messages Firebase shows, as plain Python (from the SDK's

Classes:

Name Description
DisplayDelegate

What a custom display tells Firebase about the message it shows.

InAppMessaging

Firebase In-App Messaging. Get it with InAppMessaging.in_app_messaging().

InAppMessagingError

A message that could not be shown.

InAppMessagingErrorCode

The error.code values of display errors (FIAMDisplayRenderErrorType).

Action

What the user tapped (FIRInAppMessagingAction): a button's text

ActionButton

A button of a message (FIRInAppMessagingActionButton).

BannerMessage

A banner at the top: title, body and an optional image. Tapping it

CampaignInfo

The campaign a message belongs to (FIRInAppMessagingCampaignInfo).

CardMessage

A card: title, body, images, a primary and an optional secondary button.

DismissType

How the user closed a message (FIRInAppMessagingDismissType).

ImageData

An image of a message (FIRInAppMessagingImageData).

ImageOnlyMessage

Only an image. Tapping it opens action_url.

InAppMessage

What every message has (FIRInAppMessagingDisplayMessage).

MessageType

The layout of a message (FIRInAppMessagingDisplayMessageType).

ModalMessage

A dialog: title, body, an optional image and an optional button.

TriggerType

What made the message show (FIRInAppMessagingDisplayTriggerType).

Functions:

Name Description
default_action

The main action of a message: its button (the primary one of a card)

Attributes:

Name Type Description
IN_APP_MESSAGING_ERROR_DOMAIN Final

The error.domain of the errors a message display reports.

DisplayHandler

Gets the message and its DisplayDelegate; shows the message (for

IN_APP_MESSAGING_ERROR_DOMAIN module-attribute

IN_APP_MESSAGING_ERROR_DOMAIN: Final = (
    "com.firebase.inappmessaging"
)

The error.domain of the errors a message display reports.

DisplayHandler module-attribute

DisplayHandler = Callable[
    [InAppMessage, DisplayDelegate], None
]

Gets the message and its DisplayDelegate; shows the message (for example in a Kivy popup).

DisplayDelegate

DisplayDelegate(
    message: InAppMessage,
    native_message: ObjCObject,
    native_delegate: ObjCObject,
)

What a custom display tells Firebase about the message it shows.

Call impression() once the message is on screen, then exactly one of clicked(), dismissed() or failed() when it goes away: until then, Firebase shows no other message.

Parameters:

Name Type Description Default
message InAppMessage

the message, as Python.

required
native_message ObjCObject

the FIRInAppMessagingDisplayMessage.

required
native_delegate ObjCObject

the FIRInAppMessagingDisplayDelegate Firebase gave.

required

Methods:

Name Description
impression

The message is on screen: Firebase counts an impression (once; later

clicked

The user tapped the message's action. Firebase opens the action's

dismissed

The user closed the message (or it timed out).

failed

The message could not be shown.

Attributes:

Name Type Description
finished bool

Whether clicked, dismissed or failed was called.

finished property

finished: bool

Whether clicked, dismissed or failed was called.

impression

impression() -> None

The message is on screen: Firebase counts an impression (once; later calls do nothing).

clicked

clicked(action: Action | None = None) -> None

The user tapped the message's action. Firebase opens the action's URL, if it has one (a web link, or a deep link to the app).

Parameters:

Name Type Description Default
action Action | None

what was tapped. By default, the message's main action (its button, or the primary one of a card, with its URL).

None

Raises:

Type Description
RuntimeError

the message already finished.

dismissed

dismissed(dismiss_type: int = USER_TAP_CLOSE) -> None

The user closed the message (or it timed out).

Parameters:

Name Type Description Default
dismiss_type int

a DismissType.

USER_TAP_CLOSE

Raises:

Type Description
RuntimeError

the message already finished.

failed

failed(
    code: int = UNSPECIFIED,
    description: str = "the message could not be shown",
) -> None

The message could not be shown.

Parameters:

Name Type Description Default
code int

an InAppMessagingErrorCode.

UNSPECIFIED
description str

why.

'the message could not be shown'

Raises:

Type Description
RuntimeError

the message already finished.

InAppMessaging

InAppMessaging(native: ObjCObject)

Firebase In-App Messaging. Get it with InAppMessaging.in_app_messaging().

Messages come from campaigns made in the Firebase console. Firebase fetches them and shows them by itself (with its own screens) when the app comes to the foreground, or on an Analytics event. Nothing has to be called for that: linking the framework is enough.

Parameters:

Name Type Description Default
native ObjCObject

the native FIRInAppMessaging.

required

Methods:

Name Description
in_app_messaging

The shared InAppMessaging, of the default app.

trigger_event

Show the messages of campaigns triggered by this event, without

add_impression_listener

Call listener(message) when a message is seen.

add_click_listener

Call listener(message, action) when the user taps a message's

add_dismiss_listener

Call listener(message, dismiss_type) when a message is closed

add_error_listener

Call listener(message, error) when a message could not be shown.

set_display

Show messages with Python instead of Firebase's screens.

use_default_display

Show messages with Firebase's own screens again (the default).

Attributes:

Name Type Description
native ObjCObject

The FIRInAppMessaging.

message_display_suppressed bool

Stop showing messages while True (for example during a payment

automatic_data_collection_enabled bool

Fetch messages (and send the data that needs) at start-up. Setting

native property

native: ObjCObject

The FIRInAppMessaging.

message_display_suppressed property writable

message_display_suppressed: bool

Stop showing messages while True (for example during a payment or a game level). Off at every launch; not kept.

automatic_data_collection_enabled property writable

automatic_data_collection_enabled: bool

Fetch messages (and send the data that needs) at start-up. Setting it is kept across launches; to start with it off, set FirebaseInAppMessagingAutomaticDataCollectionEnabled to NO in Info.plist, then turn it on once the user agrees.

in_app_messaging classmethod

in_app_messaging() -> InAppMessaging

The shared InAppMessaging, of the default app.

Raises:

Type Description
RuntimeError

Firebase is not configured yet (call core.configure() first).

trigger_event

trigger_event(name: str) -> None

Show the messages of campaigns triggered by this event, without logging an Analytics event. (An Analytics event with the same name triggers them too.)

Parameters:

Name Type Description Default
name str

the event name set on the campaign.

required

Raises:

Type Description
TypeError

a name that is not a str.

ValueError

an empty name.

add_impression_listener

add_impression_listener(
    listener: ImpressionListener,
) -> Callable[[], None]

Call listener(message) when a message is seen.

Parameters:

Name Type Description Default
listener ImpressionListener

gets the InAppMessage.

required

Returns:

Type Description
Callable[[], None]

A function that removes the listener.

add_click_listener

add_click_listener(
    listener: ClickListener,
) -> Callable[[], None]

Call listener(message, action) when the user taps a message's action. Firebase opens action.url itself afterwards: a deep link reaches the app as an opened URL.

Parameters:

Name Type Description Default
listener ClickListener

gets the InAppMessage and the Action.

required

Returns:

Type Description
Callable[[], None]

A function that removes the listener.

add_dismiss_listener

add_dismiss_listener(
    listener: DismissListener,
) -> Callable[[], None]

Call listener(message, dismiss_type) when a message is closed without a tap on its action.

Parameters:

Name Type Description Default
listener DismissListener

gets the InAppMessage and a DismissType.

required

Returns:

Type Description
Callable[[], None]

A function that removes the listener.

add_error_listener

add_error_listener(
    listener: ErrorListener,
) -> Callable[[], None]

Call listener(message, error) when a message could not be shown.

Parameters:

Name Type Description Default
listener ErrorListener

gets the InAppMessage and the InAppMessagingError.

required

Returns:

Type Description
Callable[[], None]

A function that removes the listener.

set_display

set_display(handler: DisplayHandler | None) -> None

Show messages with Python instead of Firebase's screens.

handler(message, delegate) runs on the main thread. It shows the message (a Kivy popup, a Toga window...), calls delegate.impression() once it is visible, and later exactly one of delegate.clicked(), delegate.dismissed() or delegate.failed(). If the handler raises, the message counts as failed.

Parameters:

Name Type Description Default
handler DisplayHandler | None

the display, or None to show no message at all (they are not counted as seen).

required

use_default_display

use_default_display() -> None

Show messages with Firebase's own screens again (the default).

InAppMessagingError

Bases: FirebaseError

A message that could not be shown.

Attributes:

Name Type Description
name str

The InAppMessagingErrorCode name of code, or "" for errors

name instance-attribute

name: str

The InAppMessagingErrorCode name of code, or "" for errors from other domains (for example a failed image download).

InAppMessagingErrorCode

The error.code values of display errors (FIAMDisplayRenderErrorType).

Attributes:

Name Type Description
IMAGE_DATA_INVALID Final

The message's image could not be loaded or read.

IMAGE_DATA_INVALID class-attribute instance-attribute

IMAGE_DATA_INVALID: Final = 0

The message's image could not be loaded or read.

Action dataclass

Action(text: str | None = None, url: str | None = None)

What the user tapped (FIRInAppMessagingAction): a button's text (None for a tap on the message itself, or on an image), and the URL the message opens (None when it has none).

ActionButton dataclass

ActionButton(
    text: str,
    text_color: str | None = None,
    background_color: str | None = None,
)

A button of a message (FIRInAppMessagingActionButton).

BannerMessage dataclass

BannerMessage(
    campaign: CampaignInfo,
    type: int,
    trigger_type: int,
    app_data: dict[str, Any] = dict(),
    title: str = "",
    body: str | None = None,
    text_color: str | None = None,
    background_color: str | None = None,
    image: ImageData | None = None,
    action_url: str | None = None,
)

Bases: InAppMessage

A banner at the top: title, body and an optional image. Tapping it opens action_url.

CampaignInfo dataclass

CampaignInfo(
    message_id: str,
    campaign_name: str,
    render_as_test_message: bool = False,
)

The campaign a message belongs to (FIRInAppMessagingCampaignInfo).

Attributes:

Name Type Description
render_as_test_message bool

A test message sent from the console to this device: it is not counted

render_as_test_message class-attribute instance-attribute

render_as_test_message: bool = False

A test message sent from the console to this device: it is not counted in the campaign's statistics.

CardMessage dataclass

CardMessage(
    campaign: CampaignInfo,
    type: int,
    trigger_type: int,
    app_data: dict[str, Any] = dict(),
    title: str = "",
    body: str | None = None,
    text_color: str | None = None,
    background_color: str | None = None,
    portrait_image: ImageData | None = None,
    landscape_image: ImageData | None = None,
    primary_button: ActionButton | None = None,
    primary_action_url: str | None = None,
    secondary_button: ActionButton | None = None,
    secondary_action_url: str | None = None,
)

Bases: InAppMessage

A card: title, body, images, a primary and an optional secondary button.

DismissType

How the user closed a message (FIRInAppMessagingDismissType).

Attributes:

Name Type Description
AUTO Final

Closed by itself (a banner times out).

AUTO class-attribute instance-attribute

AUTO: Final = 2

Closed by itself (a banner times out).

ImageData dataclass

ImageData(image_url: str, image_data: bytes | None = None)

An image of a message (FIRInAppMessagingImageData).

Attributes:

Name Type Description
image_data bytes | None

The image file (PNG, JPEG, ...), already downloaded by Firebase.

image_data class-attribute instance-attribute

image_data: bytes | None = field(default=None, repr=False)

The image file (PNG, JPEG, ...), already downloaded by Firebase.

ImageOnlyMessage dataclass

ImageOnlyMessage(
    campaign: CampaignInfo,
    type: int,
    trigger_type: int,
    app_data: dict[str, Any] = dict(),
    image: ImageData | None = None,
    action_url: str | None = None,
)

Bases: InAppMessage

Only an image. Tapping it opens action_url.

InAppMessage dataclass

InAppMessage(
    campaign: CampaignInfo,
    type: int,
    trigger_type: int,
    app_data: dict[str, Any] = dict(),
)

What every message has (FIRInAppMessagingDisplayMessage).

Attributes:

Name Type Description
type int

A MessageType.

trigger_type int

A TriggerType.

app_data dict[str, Any]

The custom data (key-value pairs) set on the campaign in the console.

type instance-attribute

type: int

A MessageType.

trigger_type instance-attribute

trigger_type: int

A TriggerType.

app_data class-attribute instance-attribute

app_data: dict[str, Any] = field(default_factory=dict)

The custom data (key-value pairs) set on the campaign in the console.

MessageType

The layout of a message (FIRInAppMessagingDisplayMessageType).

Attributes:

Name Type Description
MODAL Final

A dialog in the middle of the screen.

BANNER Final

A strip at the top of the screen.

IMAGE_ONLY Final

Only an image.

CARD Final

A card with one or two buttons, and images for portrait and landscape.

MODAL class-attribute instance-attribute

MODAL: Final = 0

A dialog in the middle of the screen.

BANNER class-attribute instance-attribute

BANNER: Final = 1

A strip at the top of the screen.

IMAGE_ONLY class-attribute instance-attribute

IMAGE_ONLY: Final = 2

Only an image.

CARD class-attribute instance-attribute

CARD: Final = 3

A card with one or two buttons, and images for portrait and landscape.

ModalMessage dataclass

ModalMessage(
    campaign: CampaignInfo,
    type: int,
    trigger_type: int,
    app_data: dict[str, Any] = dict(),
    title: str = "",
    body: str | None = None,
    text_color: str | None = None,
    background_color: str | None = None,
    image: ImageData | None = None,
    action_button: ActionButton | None = None,
    action_url: str | None = None,
)

Bases: InAppMessage

A dialog: title, body, an optional image and an optional button.

TriggerType

What made the message show (FIRInAppMessagingDisplayTriggerType).

Attributes:

Name Type Description
ON_APP_FOREGROUND Final

The app came to the foreground.

ON_ANALYTICS_EVENT Final

An Analytics event, or InAppMessaging.trigger_event.

ON_APP_FOREGROUND class-attribute instance-attribute

ON_APP_FOREGROUND: Final = 0

The app came to the foreground.

ON_ANALYTICS_EVENT class-attribute instance-attribute

ON_ANALYTICS_EVENT: Final = 1

An Analytics event, or InAppMessaging.trigger_event.

default_action

default_action(message: InAppMessage) -> Action

The main action of a message: its button (the primary one of a card) and its URL.

Parameters:

Name Type Description Default
message InAppMessage

the message.

required