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(allInAppMessage:campaign,type,trigger_type,app_data);CampaignInfo,ImageData,ActionButton,Action,default_action(message) - Constants:
MessageType,TriggerType,DismissType,InAppMessagingErrorCode; errors areInAppMessagingError
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 |
|
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 |
InAppMessagingError |
A message that could not be shown. |
InAppMessagingErrorCode |
The |
Action |
What the user tapped ( |
ActionButton |
A button of a message ( |
BannerMessage |
A banner at the top: title, body and an optional image. Tapping it |
CampaignInfo |
The campaign a message belongs to ( |
CardMessage |
A card: title, body, images, a primary and an optional secondary button. |
DismissType |
How the user closed a message ( |
ImageData |
An image of a message ( |
ImageOnlyMessage |
Only an image. Tapping it opens |
InAppMessage |
What every message has ( |
MessageType |
The layout of a message ( |
ModalMessage |
A dialog: title, body, an optional image and an optional button. |
TriggerType |
What made the message show ( |
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 |
DisplayHandler |
Gets the message and its |
IN_APP_MESSAGING_ERROR_DOMAIN
module-attribute
¶
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 |
required |
native_delegate
|
ObjCObject
|
the |
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 |
impression
¶
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
¶
The user closed the message (or it timed out).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
dismiss_type
|
int
|
a |
USER_TAP_CLOSE
|
Raises:
| Type | Description |
|---|---|
RuntimeError
|
the message already finished. |
failed
¶
The message could not be shown.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
code
|
int
|
an |
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 |
required |
Methods:
| Name | Description |
|---|---|
in_app_messaging |
The shared |
trigger_event |
Show the messages of campaigns triggered by this event, without |
add_impression_listener |
Call |
add_click_listener |
Call |
add_dismiss_listener |
Call |
add_error_listener |
Call |
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 |
message_display_suppressed |
bool
|
Stop showing messages while |
automatic_data_collection_enabled |
bool
|
Fetch messages (and send the data that needs) at start-up. Setting |
message_display_suppressed
property
writable
¶
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
¶
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
|
trigger_event
¶
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 |
ValueError
|
an empty name. |
add_impression_listener
¶
Call listener(message) when a message is seen.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
listener
|
ImpressionListener
|
gets the |
required |
Returns:
| Type | Description |
|---|---|
Callable[[], None]
|
A function that removes the listener. |
add_click_listener
¶
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 |
required |
Returns:
| Type | Description |
|---|---|
Callable[[], None]
|
A function that removes the listener. |
add_dismiss_listener
¶
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 |
required |
Returns:
| Type | Description |
|---|---|
Callable[[], None]
|
A function that removes the listener. |
add_error_listener
¶
Call listener(message, error) when a message could not be shown.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
listener
|
ErrorListener
|
gets the |
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 |
required |
use_default_display
¶
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 |
name
instance-attribute
¶
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
¶
The message's image could not be loaded or read.
Action
dataclass
¶
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
¶
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
¶
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
¶
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,
)
DismissType
¶
ImageData
dataclass
¶
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
¶
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,
)
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 |
trigger_type |
int
|
A |
app_data |
dict[str, Any]
|
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. |
CARD
class-attribute
instance-attribute
¶
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,
)
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 |
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 |