Skip to content

Commit 0931d1e

Browse files
OmbuwebOmbuweb
authored
docs(firebase-in-app-messaging): update (#202)
1 parent c4a3ead commit 0931d1e

File tree

1 file changed

+91
-17
lines changed

1 file changed

+91
-17
lines changed

‎packages/firebase-in-app-messaging/README.md

Lines changed: 91 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -1,38 +1,59 @@
11
# @nativescript/firebase-in-app-messaging
22

3-
```cli
4-
npm install @nativescript/firebase-in-app-messaging
5-
```
6-
7-
## What does it do
8-
9-
Firebase In-App Messaging helps you to engage your apps active users by sending them targeted, contextual messages that encourage them to use key app features. For example, you could send an in-app message to get users to subscribe, watch a video, complete a level, or buy an item. You can customize messages as cards, banners, modals, or images, and set up triggers so that they appear exactly when they'd benefit your users most.
10-
3+
## Contents
4+
5+
- [Intro](#intro)
6+
- [Set up your app for Firebase](#set-up-your-app-for-firebase)
7+
- [Add the Firebase In-App Messaging SDK to your app](#add-the-firebase-in-app-messaging-sdk-to-your-app)
8+
- [Firebase In-App Messaging limitations](#firebase-in-app-messaging-limitations)
9+
- [Create message campaigns](#create-message-campaigns)
10+
- [Control messages display](#control-messages-display)
11+
- [Trigger contextual messages](#trigger-contextual-messages)
12+
- [API](#api)
13+
- [InAppMessaging class](#inappmessaging-class)
14+
- [app](#app)
15+
- [isAutomaticDataCollectionEnabled](#isautomaticdatacollectionenabled)
16+
- [isMessagesDisplaySuppressed](#ismessagesdisplaysuppressed)
17+
- [triggerEvent()](#triggerevent)
18+
- [License](#license)
19+
## Intro
20+
21+
This plugin allows you to use the [Firebase In-App Messaging SDK](https://firebase.google.com/docs/in-app-messaging) in your NativeScript app.
1122

1223
[![image](https://img.youtube.com/vi/5MRKpvKV2pg/hqdefault.jpg)](https://www.youtube.com/watch?v=5MRKpvKV2pg)
1324

25+
## Set up your app for Firebase
1426

15-
## Usage
16-
17-
Most of the set up occurs on [Firebase Console](https://console.firebase.google.com/u/0/project/_/inappmessaging) in the In-App Messaging tab. You can create campaigns and customize elements such as Image, Banner, Modal & Cards to appear on predefined events (e.g. purchase). This involves no code for the developer to implement. Any published campaigns from the Firebase Console are automatically handled and displayed on your user's device.
27+
You need to set up your app for Firebase before you can use the Firebase in-app messaging. To set up and initialize Firebase for your NativeScript app, follow the instructions on the documentation of the [@nativescript/firebase-core](../firebase-core/) plugin.
1828

19-
This module provides a JavaScript API to allow greater control of the displaying of these messages.
2029

30+
## Add the Firebase In-App Messaging SDK to your app
2131

22-
## Limitations
32+
To add the Firebase In-App Messaging SDK to your app follow these steps:
2333

34+
1. Install the `@nativescript/firebase-in-app-messaging` plugin by running the following command in the root directory of your project.
2435

25-
According to github issue https://github.com/firebase/firebase-ios-sdk/issues/4768 Firebase In-App Messaging allows only 1 campaign per day on app foreground or app launch. This limit is to prevent you from accidentally overwhelming your users with non-contextually appropriate messages. However, if you use the contextual triggers (for example: Analytics event or programmatically triggered in-app-messaging campaigns), there is no daily rate limit.
36+
```cli
37+
npm install @nativescript/firebase-in-app-messaging
38+
```
39+
2. Add the SDK by importing the `@nativescript/firebase-in-app-messaging` module in your app's main file (e.g. `app.ts` or `main.ts`).
40+
```ts
41+
import '@nativescript/firebase-in-app-messaging';
42+
```
2643

44+
## Firebase In-App Messaging limitations
2745

28-
## Displaying Messages
46+
According to a github issue https://github.com/firebase/firebase-ios-sdk/issues/4768, Firebase In-App Messaging allows only 1 campaign per day on app foreground or app launch. This limit is to prevent you from accidentally overwhelming your users with non-contextually appropriate messages. However, if you use contextual triggers (for example Analytics events or programmatically triggered in-app-messaging campaigns), there is no daily rate limit.
2947

30-
The isMessagesDisplaySuppressed property allows you to control when messages can/cannot be displayed. Below illustrates a use case for controlling the flow of messages:
48+
## Create message campaigns
3149

50+
To create a message campaign, go to the `In-App Messaging` page in the [Firebase Console](https://console.firebase.google.com/u/0/project/_/inappmessaging) and follow the instructions there. You can create campaigns and customize elements such as Image, Banner, Modal & Cards to appear on predefined events (e.g. purchase).
3251

33-
> **Note:** The suppressed state is not persisted between restarts, so ensure it is called as early as possible.
52+
Any published campaigns from the Firebase Console are automatically handled and displayed on your user's device.
3453

54+
## Control messages display
3555

56+
To control whether to display messages or not, set the `isMessagesDisplaySuppressed` property of the `InAppMessaging` instance to `true` or `false`. The `InAppMessaging` instance is returneb calling the `inAppMessaging()` on the FirebaseApp instance. By default, `isMessagesDisplaySuppressed` is set to `false` which means messages will be displayed.
3657

3758
```ts
3859
import { firebase } from '@nativescript/firebase-core';
@@ -47,9 +68,62 @@ async function onSetup(user) {
4768
// Allow user to receive messages now setup is complete
4869
firebase().inAppMessaging().isMessagesDisplaySuppressed = false;
4970
}
71+
```
72+
> **Note:** The suppressed state is not persisted between restarts, so ensure it is called as early as possible ideally in the app bootstrapping file(`app.ts` or `main.ts`).
73+
74+
## Trigger contextual messages
5075

76+
To trigger contextual messages, call the `triggerEvent()` method of the `InAppMessaging` instance with the event name as a parameter. This triggers the display of any messages that are configured on the Firebase Console.
77+
```ts
78+
import { firebase } from '@nativescript/firebase-core';
79+
80+
firebase().inAppMessaging().triggerEvent('purchase');
5181
```
5282

83+
## API
84+
85+
### InAppMessaging class
86+
87+
#### app
88+
```ts
89+
inAppMessagingApp = firebase().inAppMessaging().app;
90+
```
91+
92+
The `app` property returns the `FirebaseApp` instance that the current `InAppMessaging` instance is associated with.
93+
94+
95+
---
96+
#### isAutomaticDataCollectionEnabled
97+
```ts
98+
firebase().inAppMessaging().isAutomaticDataCollectionEnabled = true;
99+
```
100+
101+
For the description of this property, see [isAutomaticDataCollectionEnabled](https://firebase.google.com/docs/reference/android/com/google/firebase/inappmessaging/FirebaseInAppMessaging#isAutomaticDataCollectionEnabled()) on the Firebase documentation.
102+
103+
---
104+
#### isMessagesDisplaySuppressed
105+
```ts
106+
firebase().inAppMessaging().isMessagesDisplaySuppressed = true;
107+
// or
108+
firebase().inAppMessaging().isMessagesDisplaySuppressed = false;
109+
```
110+
111+
For the description of this property, see [areMessagesSuppressed](https://firebase.google.com/docs/reference/android/com/google/firebase/inappmessaging/FirebaseInAppMessaging#areMessagesSuppressed()) on the Firebase documentation.
112+
113+
---
114+
#### triggerEvent()
115+
```ts
116+
firebase().inAppMessaging().triggerEvent(eventId);
117+
```
118+
| Parameter | Type | Description |
119+
| --- | --- | --- |
120+
| `eventId` | `string` | The name of the event to trigger.
121+
122+
For the description of this method, see [triggerEvent](https://firebase.google.com/docs/reference/android/com/google/firebase/inappmessaging/FirebaseInAppMessaging#triggerEvent(java.lang.String)) on the Firebase documentation.
123+
124+
---
125+
126+
53127
## License
54128

55129
Apache License Version 2.0

0 commit comments

Comments
 (0)