Skip to content

Commit 13f97e7

Browse files
kevinthecheungkevinthecheung
authored
docs(in-app-messaging): add official content (#8284)
1 parent 54fe61b commit 13f97e7

File tree

6 files changed

+260
-99
lines changed

6 files changed

+260
-99
lines changed

‎docs/in-app-messaging/customize-messages.mdx

+35
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
---
2+
title: Customize your Firebase In-App Messaging messages
3+
sidebar_label: Customize messages
4+
---
5+
6+
Firebase In-App Messaging provides a useful set of preconfigured behaviors and
7+
message types with a default look and feel, but in some cases you may want to
8+
extend behaviors and message content. In-App Messaging allows you to add actions
9+
to messages and customize message look and feel.
10+
11+
## Add an action to your message
12+
13+
With actions you can use your in-app messages to direct users to a
14+
website or a specific screen in your app.
15+
16+
### Implement a deep link handler
17+
18+
Firebase In-App Messaging uses link handlers to process actions. The SDK is
19+
able to use a number of handlers, so if your app already has one, Firebase
20+
In-App Messaging can use that without any further setup. If you don't yet have
21+
a handler, you can use [Firebase Dynamic Links](../dynamic-links/overview).
22+
23+
### Add the action to your message using the Firebase console
24+
25+
Once your app has a link handler, you're ready to compose a campaign with
26+
an action. Open the Firebase console to
27+
[In-App Messaging](https://console.firebase.google.com/project/_/inappmessaging),
28+
and start a new campaign or edit an existing campaign. In that campaign, provide
29+
a **Card**, **Button text** and **Button action**, an **Image action**, or a **Banner
30+
action**, where the action is a relevant deep link.
31+
32+
The action's format depends on which message layout you choose. Modals get
33+
action buttons with customizable button text content, text color, and background
34+
color. Images and top banners, on the other hand, become interactive and invoke
35+
the specified action when tapped.

‎docs/in-app-messaging/get-started.mdx

+99
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,99 @@
1+
---
2+
title: Get started with Firebase In-App Messaging
3+
sidebar_label: Get started
4+
---
5+
6+
This quickstart shows you how to set up Firebase In-App Messaging and send your first message.
7+
8+
## Before you begin
9+
10+
[Install and initialize the Firebase SDKs for Flutter](../overview) if you
11+
haven't already done so.
12+
13+
## Add the Firebase In-App Messaging SDK to your project
14+
15+
1. From the root directory of your Flutter project, run the following
16+
command to install the Firebase In-App Messaging plugin:
17+
18+
```bash
19+
flutter pub add firebase_in_app_messaging
20+
```
21+
22+
1. Rebuild your project:
23+
24+
```bash
25+
flutter run
26+
```
27+
28+
1. Import the Firebase In-App Messaging plugin:
29+
30+
```dart
31+
import 'package:firebase_in_app_messaging/firebase_in_app_messaging.dart';
32+
```
33+
34+
## Send a test message
35+
36+
### Get your app's installation ID
37+
38+
To conserve power, Firebase In-App Messaging only retrieves messages from the
39+
server once per day. That can make testing difficult, so the
40+
Firebase console allows you to specify a test device that displays messages
41+
on demand.
42+
43+
That testing device is determined by a FID.
44+
Find your testing app's FID by checking the console
45+
output when you run your app.
46+
47+
On Android, the message looks like the following:
48+
49+
```
50+
I/FIAM.Headless: Starting InAppMessaging runtime with Installation ID YOUR_INSTALLATION_ID
51+
```
52+
53+
On iOS, run the app with the runtime command argument `-FIRDebugEnabled`:
54+
55+
1. With your Xcode project open, select **Product > Scheme > Edit scheme...** from
56+
the top menu bar.
57+
1. Open the **Arguments** tab of the dialog that pops up.
58+
1. Click **+ Add items** under **Arguments Passed On Launch**.
59+
1. Enter "-FIRDebugEnabled" in the newly-created field.
60+
1. Click **Close**, then run your app.
61+
62+
Once your app starts running, look for the following line in the Xcode console's logs:
63+
64+
```
65+
[Firebase/InAppMessaging][I-IAM180017] Starting InAppMessaging runtime with Firebase Installation ID YOUR_INSTALLATION_ID
66+
```
67+
68+
69+
### Send a message to your testing device
70+
71+
Once you've launched your app on the testing device and you have its
72+
Firebase installation ID (FID), you can try out your Firebase In-App Messaging
73+
setup by sending a test message:
74+
75+
1. In the Firebase console, open [In-App Messaging](https://console.firebase.google.com/project/_/inappmessaging/).
76+
1. Click **New Campaign**.
77+
1. Enter a **Title** for your first message.
78+
1. Click **Test on your Device**
79+
1. Enter your app's Firebase installation ID in the
80+
**Add an installation ID** field.
81+
1. Click **Test** to send the message.
82+
83+
Firebase In-App Messaging sends your test message as soon as you click **Test**. To see the
84+
message, you need to close, then reopen the app on your testing device.
85+
86+
To confirm whether your device is a test device, look for one of the following
87+
log messages.
88+
89+
**Android**
90+
91+
```
92+
I/FIAM.Headless: Setting this device as a test device
93+
```
94+
95+
**iOS**
96+
97+
```
98+
[Firebase/InAppMessaging][I-IAM180017] Seeing test message in fetch response. Turn the current instance into a testing instance.
99+
```

‎docs/in-app-messaging/modify-message-behavior.mdx

+114
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,114 @@
1+
---
2+
title: Modify behavior of Firebase In-App Messaging messages
3+
sidebar_label: Modify message behavior
4+
---
5+
6+
With little to no coding effort, Firebase In-App Messaging allows you to create,
7+
configure and target rich user interactions, leveraging
8+
the capabilities of Google Analytics out of the box
9+
to tie messaging events to actual user characteristics, activities, and choices.
10+
With some additional Firebase In-App Messaging SDK integration, you can tailor
11+
the behavior of in-app messages even further, responding when users interact
12+
with messages, triggering message events outside the Analytics
13+
framework, and allowing users to control sharing of their personal data related
14+
to messaging interactions.
15+
16+
## Respond when users interact with in-app messages
17+
18+
With actions you can use your in-app messages to direct users to a
19+
website or a specific screen in your app.
20+
21+
Your code can respond to basic interactions (clicks and dismissals), to
22+
impressions (verified views of your messages), and to display errors logged and
23+
confirmed by the SDK. For example, when your message is composed as a Card
24+
modal, you might want to track and follow-up on which of two URLs the user
25+
clicked on the Card.
26+
27+
To do so, you will have to use the platform-native APIs.
28+
See the documentation for [iOS](https://firebase.google.com/docs/in-app-messaging/modify-message-behavior?platform=ios#respond_when_users_interact_with_in-app_messages)
29+
and [Android](https://firebase.google.com/docs/in-app-messaging/modify-message-behavior?platform=android#respond_when_users_interact_with_in-app_messages).
30+
31+
## Trigger in-app messages programmatically
32+
33+
Firebase In-App Messaging by default allows you to trigger in-app messages with
34+
Google Analytics for Firebase events, with no additional integration. You can
35+
also manually trigger events programmatically with the Firebase In-App Messaging SDK's
36+
programmatic triggers.
37+
38+
In the In-App Messaging campaign composer, create a new campaign or select an
39+
existing campaign, and in the Scheduling step of the composer workflow, note the
40+
event ID of a newly-created or existing messaging event. Once noted, instrument
41+
your app to trigger the event by its ID.
42+
43+
```dart
44+
FirebaseInAppMessaging.instance.triggerEvent("eventName");
45+
```
46+
47+
## Use campaign custom metadata
48+
49+
In your campaigns, you can specify custom data in a series of key/value pairs.
50+
When users interact with messages, this data is available for you to, for example,
51+
display a promo code.
52+
53+
To do so, you will have to use the platform-native APIs.
54+
See the documentation for [iOS](https://firebase.google.com/docs/in-app-messaging/modify-message-behavior?platform=ios#use_campaign_custom_metadata)
55+
and [Android](https://firebase.google.com/docs/in-app-messaging/modify-message-behavior?platform=android#use_campaign_custom_metadata).
56+
57+
58+
## Temporarily disable in-app messages
59+
60+
By default, Firebase In-App Messaging renders messages whenever a triggering
61+
condition is satisfied, regardless of an app's current state. If you'd like to
62+
suppress message displays for any reason, for example to avoid interrupting a
63+
sequence of payment processing screens, you can do that with the SDK's
64+
`setMessagesSuppressed()` method:
65+
66+
```dart
67+
FirebaseInAppMessaging.instance.setMessagesSuppressed(true);
68+
```
69+
70+
Passing `true` to the method prevents Firebase In-App Messaging from displaying
71+
messages, while `false` reenables message display. The SDK turns off message
72+
suppression on app restart. Suppressed messages are ignored by the SDK. Their
73+
trigger conditions must be met again while suppression is off before Firebase
74+
In-App Messaging can display them.
75+
76+
## Enable opt-out message delivery
77+
78+
By default, Firebase In-App Messaging automatically delivers messages to all app users you target
79+
in messaging campaigns. To deliver those messages, the Firebase In-App Messaging SDK uses
80+
installation IDs to identify each user's app. This means
81+
that In-App Messaging has to send client data, linked to the
82+
installation ID, to Firebase servers. If you'd like to give users
83+
more control over the data they send, disable automatic data collection and give
84+
them a chance to approve data sharing.
85+
86+
To do that, you have to disable automatic initialization for Firebase In-App Messaging, and
87+
initialize the service manually for opt-in users:
88+
89+
1. Turn off automatic initialization.
90+
91+
**Apple platforms**: Add a new key to your `Info.plist` file:
92+
93+
- Key: `FirebaseInAppMessagingAutomaticDataCollectionEnabled`
94+
- Value: `NO`
95+
96+
**Android**: Add a `meta-data` tag to your `AndroidManifest.xml` file:
97+
98+
```xml
99+
<meta-data
100+
android:name="firebase_inapp_messaging_auto_data_collection_enabled"
101+
android:value="false" />
102+
```
103+
104+
1. Initialize Firebase In-App Messaging for selected users manually:
105+
106+
```dart
107+
FirebaseInAppMessaging.instance.setAutomaticDataCollectionEnabled(true);
108+
```
109+
110+
Once you set a data collection preference manually, the value persists
111+
through app restarts, overriding the value in your `Info.plist` or
112+
`AndroidManifest.xml`. If you'd like to disable initialization again, for
113+
example if a user opts out of collection later, pass `false` to the
114+
`setAutomaticDataCollectionEnabled()` method.

‎docs/in-app-messaging/overview.mdx

+1-31
Original file line numberDiff line numberDiff line change
@@ -16,36 +16,6 @@ your social media app.
1616

1717
<YouTube id="5MRKpvKV2pg" />
1818

19-
## Installation
20-
21-
### 1. Make sure to initialize Firebase
22-
23-
[Follow this guide](../overview.mdx) to install `firebase_core` and initialize Firebase if you haven't already.
24-
25-
:::caution
26-
Dart-only initialization **is currently not supported** with `firebase_in_app_messaging`,
27-
please follow the Platform Setup section from the [manual installation guide](../manual-installation.mdx)
28-
for the supported platforms.
29-
:::
30-
31-
### 2. Add dependency
32-
33-
On the root of your Flutter project, run the following command to install the plugin:
34-
35-
```bash {5}
36-
flutter pub add firebase_in_app_messaging
37-
```
38-
39-
### 3. Rebuild your app
40-
41-
Once complete, rebuild your Flutter application:
42-
43-
```bash
44-
$ flutter run
45-
```
46-
4719
## Next Steps
4820

49-
Once installed, you're ready to start using In-App Messaging in your Flutter Project.
50-
51-
View the [Usage documentation](usage.mdx) to get started.
21+
[Get started](get-started) using In-App Messaging in your Flutter Project.

‎docs/in-app-messaging/usage.mdx

-67
This file was deleted.

‎docs/sidebars.js

+11-1
Original file line numberDiff line numberDiff line change
@@ -226,7 +226,17 @@ module.exports = {
226226
],
227227
'In-App Messaging': [
228228
'in-app-messaging/overview',
229-
'in-app-messaging/usage',
229+
'in-app-messaging/get-started',
230+
toFirebase(
231+
"Explore use cases",
232+
"/docs/in-app-messaging/explore-use-cases",
233+
),
234+
toFirebase(
235+
"Compose a campaign",
236+
"/docs/in-app-messaging/compose-campaign",
237+
),
238+
'in-app-messaging/modify-message-behavior',
239+
'in-app-messaging/customize-messages',
230240
toReferenceAPI('firebase_in_app_messaging'),
231241
toGithubExample('firebase_in_app_messaging'),
232242
],

0 commit comments

Comments
 (0)