README.md 28.6 KB
Newer Older
Libin Lu's avatar
Libin Lu committed
1 2
[![Join the chat at https://gitter.im/evollu/react-native-fcm](https://badges.gitter.im/evollu/react-native-fcm.svg)](https://gitter.im/evollu/react-native-fcm?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)

3
## NOTES:
Libin Lu's avatar
Libin Lu committed
4
- current latest version: v10.x
Libin Lu's avatar
Libin Lu committed
5
- for iOS SDK < 4, use react-native-fcm@6.2.3 (v6.x is still compatible with Firebase SDK v4)
6 7 8
- for RN < 0.40.0, use react-native-fcm@2.5.6
- for RN < 0.33.0, use react-native-fcm@1.1.0
- for RN < 0.30.0, use react-native-fcm@1.0.15
Libin Lu's avatar
Libin Lu committed
9
- local notification is not only available in V1
Libin Lu's avatar
Libin Lu committed
10

11
- An example working project is available at: https://github.com/evollu/react-native-fcm/tree/master/Examples/simple-fcm-client
Libin Lu's avatar
Libin Lu committed
12

Libin Lu's avatar
init  
Libin Lu committed
13 14 15
## Installation

- Run `npm install react-native-fcm --save`
16
- Run `react-native link react-native-fcm` (RN 0.29.1+, otherwise `rnpm link react-native-fcm`)
Libin Lu's avatar
init  
Libin Lu committed
17

Libin Lu's avatar
Libin Lu committed
18 19 20 21
## Configure Firebase Console
### FCM config file

In [firebase console](https://console.firebase.google.com/), you can:
Sean Adkinson's avatar
Sean Adkinson committed
22
- for **Android**: download `google-services.json` file and place it in `android/app` directory
Libin Lu's avatar
Libin Lu committed
23 24 25 26 27
- for **iOS**: download `GoogleService-Info.plist` file and place it in `/ios/your-project-name` directory (next to your `Info.plist`)

Make sure you have certificates setup by following
https://firebase.google.com/docs/cloud-messaging/ios/certs

28
## Android Configuration
Libin Lu's avatar
init  
Libin Lu committed
29

Libin Lu's avatar
Libin Lu committed
30 31 32 33
- As `react-native link` sometimes has glitches, make sure you have this line added

https://github.com/evollu/react-native-fcm/blob/master/Examples/simple-fcm-client/android/app/src/main/java/com/google/firebase/quickstart/fcm/MainApplication.java#L28

34 35 36 37 38
- Edit `android/build.gradle`:
```diff
  dependencies {
    classpath 'com.android.tools.build:gradle:2.0.0'
+   classpath 'com.google.gms:google-services:3.0.0'
Libin Lu's avatar
init  
Libin Lu committed
39 40
```

Sagiv Ofek's avatar
Sagiv Ofek committed
41
- Edit `android/app/build.gradle`. Add at the bottom of the file:
42 43 44
```diff
  apply plugin: "com.android.application"
+ apply plugin: 'com.google.gms.google-services'
Libin Lu's avatar
init  
Libin Lu committed
45 46
```

47
- Edit `android/app/src/main/AndroidManifest.xml`:
Libin Lu's avatar
init  
Libin Lu committed
48

49 50 51 52 53
```diff
  <application
    ...
    android:theme="@style/AppTheme">

Libin Lu's avatar
Libin Lu committed
54
+   <service android:name="com.evollu.react.fcm.MessagingService" android:enabled="true" android:exported="true">
55 56 57 58 59 60 61 62 63 64 65 66
+     <intent-filter>
+       <action android:name="com.google.firebase.MESSAGING_EVENT"/>
+     </intent-filter>
+   </service>

+   <service android:name="com.evollu.react.fcm.InstanceIdService" android:exported="false">
+     <intent-filter>
+       <action android:name="com.google.firebase.INSTANCE_ID_EVENT"/>
+     </intent-filter>
+   </service>

    ...
Libin Lu's avatar
init  
Libin Lu committed
67
```
68

Libin Lu's avatar
Libin Lu committed
69 70 71
- Edit `{YOUR_MAIN_PROJECT}/app/build.gradle`:
```diff
 dependencies {
72
+    compile project(':react-native-fcm')
Libin Lu's avatar
Libin Lu committed
73 74 75 76 77 78
+    compile 'com.google.firebase:firebase-core:10.0.1' //this decides your firebase SDK version
     compile fileTree(dir: "libs", include: ["*.jar"])
     compile "com.android.support:appcompat-v7:23.0.1"
     compile "com.facebook.react:react-native:+"  // From node_modules
 }
```
Ashish Chaudhary's avatar
Ashish Chaudhary committed
79
- Edit `android/settings.gradle`
80 81 82 83 84 85
```diff
  ...
+ include ':react-native-fcm'
+ project(':react-native-fcm').projectDir = new File(rootProject.projectDir, '../node_modules/react-native-fcm/android')
  include ':app'
```
Libin Lu's avatar
Libin Lu committed
86

87
### Config for notification and `click_action` in Android
88 89 90 91 92 93 94 95 96 97 98 99 100

To allow android to respond to `click_action`, you need to define Activities and filter on specific intent. Since all javascript is running in MainActivity, you can have MainActivity to handle actions:

Edit `AndroidManifest.xml`:

```diff
  <activity
    android:name=".MainActivity"
    android:label="@string/app_name"
    android:windowSoftInputMode="adjustResize"
+   android:launchMode="singleTop"
    android:configChanges="keyboard|keyboardHidden|orientation|screenSize">
    <intent-filter>
101 102
      <action android:name="android.intent.action.MAIN" />
      <category android:name="android.intent.category.LAUNCHER" />
103 104
    </intent-filter>
  </activity>
105
```
106 107

Notes:
Libin Lu's avatar
Libin Lu committed
108
- `launchMode="singleTop"` is to reuse MainActivity, you can use `singleTask` or `singleInstance` as well depend on your need. [this link explains the behavior well](https://blog.mindorks.com/android-activity-launchmode-explained-cbc6cf996802)
Libin Lu's avatar
Libin Lu committed
109
- you if want to handle `click_action` you need to add custom intent-filter, check native android documentation
110 111


112
If you are using RN < 0.30.0 and react-native-fcm < 1.0.16, pass intent into package, edit `MainActivity.java`:
113

Libin Lu's avatar
Libin Lu committed
114
- RN 0.28:
115 116 117 118 119 120 121 122 123 124 125 126 127 128

```diff
  import com.facebook.react.ReactActivity;
+ import android.content.Intent;

  public class MainActivity extends ReactActivity {

+   @Override
+   public void onNewIntent (Intent intent) {
+     super.onNewIntent(intent);
+       setIntent(intent);
+   }       
```

Libin Lu's avatar
Libin Lu committed
129
NOTE: Verify that react-native links correctly in `MainApplication.java`
130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150

```diff
import android.app.application
...
+import com.evollu.react.fcm.FIRMessagingPackage;
```
....
```diff
    @Override
    protected List<ReactPackage> getPackages() {
      return Arrays.<ReactPackage>asList(
          new MainReactPackage(),
          new VectorIconsPackage(),
+         new FIRMessagingPackage(),
          new RNDeviceInfo(),
      );
    }
 ```   



151 152 153 154 155 156 157 158 159 160 161 162 163
- RN <= 0.27:

```diff
  import com.facebook.react.ReactActivity;
+ import android.content.Intent;

  public class MainActivity extends ReactActivity {

+   @Override
+   protected void onNewIntent (Intent intent) {
+     super.onNewIntent(intent);
+       setIntent(intent);
+   }       
164
```
Libin Lu's avatar
init  
Libin Lu committed
165

166 167 168
Notes:
- `@Override` is added to update intent on notification click

169
## IOS Configuration
Libin Lu's avatar
init  
Libin Lu committed
170

Libin Lu's avatar
Libin Lu committed
171 172
### Pod approach:

173
Make sure you have [Cocoapods](https://cocoapods.org/) version > 1.0
174

175
Configure the project:
Libin Lu's avatar
Libin Lu committed
176 177
```
cd ios && pod init
178 179 180 181 182 183 184 185 186 187 188 189 190
```

(In case of syntax errors, `open YOURApp.xcodeproj/project.pbxproj` and fix them.)

Edit the newly created `Podfile`:
```diff
  # Pods for YOURAPP
+ pod 'FirebaseMessaging'
```

Install the `Firebase/Messaging` pod:
```
pod install
Libin Lu's avatar
Libin Lu committed
191
```
Libin Lu's avatar
Libin Lu committed
192
NOTE: you don't need to enable `use_frameworks!`. if you have to have `use_frameworks!` make sure you don't have `inherit! :search_paths`
Libin Lu's avatar
init  
Libin Lu committed
193

Libin Lu's avatar
Libin Lu committed
194
### Non Cocoapod approach
195

Libin Lu's avatar
Libin Lu committed
196 197
1. Download the Firebase SDK framework from [Integrate without CocoaPods](https://firebase.google.com/docs/ios/setup#frameworks).
- Import libraries, add Capabilities (background running and push notification), upload APNS and etc etc etc...
Libin Lu's avatar
Libin Lu committed
198
2. Put frameworks under `ios/Pods` folder
199
2. Follow the `README` to link frameworks (Analytics+Messaging)
Libin Lu's avatar
Libin Lu committed
200 201

### Shared steps
Libin Lu's avatar
Libin Lu committed
202

Libin Lu's avatar
Libin Lu committed
203 204
Edit `AppDelegate.h`:
```diff
Libin Lu's avatar
Libin Lu committed
205 206
+ @import UserNotifications;
+
Libin Lu's avatar
Libin Lu committed
207 208 209
+ @interface AppDelegate : UIResponder <UIApplicationDelegate,UNUserNotificationCenterDelegate>
- @interface AppDelegate : UIResponder <UIApplicationDelegate>
```
Libin Lu's avatar
init  
Libin Lu committed
210

211 212 213 214 215 216 217 218 219
Edit `AppDelegate.m`:
```diff
+ #import "RNFIRMessaging.h"
  //...

  - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
  {
  //...
+   [FIRApp configure];
Libin Lu's avatar
Libin Lu committed
220
+   [[UNUserNotificationCenter currentNotificationCenter] setDelegate:self];
221 222 223

    return YES;
 }
Sean Adkinson's avatar
Sean Adkinson committed
224

Libin Lu's avatar
Libin Lu committed
225
+
Libin Lu's avatar
Libin Lu committed
226
+ - (void)userNotificationCenter:(UNUserNotificationCenter *)center willPresentNotification:(UNNotification *)notification withCompletionHandler:(void (^)(UNNotificationPresentationOptions))completionHandler
Libin Lu's avatar
Libin Lu committed
227
+ {
Libin Lu's avatar
Libin Lu committed
228
+   [RNFIRMessaging willPresentNotification:notification withCompletionHandler:completionHandler];
Libin Lu's avatar
Libin Lu committed
229
+ }
Libin Lu's avatar
Libin Lu committed
230
+
Libin Lu's avatar
Libin Lu committed
231
+ #if defined(__IPHONE_11_0)
Libin Lu's avatar
Libin Lu committed
232
+ - (void)userNotificationCenter:(UNUserNotificationCenter *)center didReceiveNotificationResponse:(UNNotificationResponse *)response withCompletionHandler:(void (^)(void))completionHandler
Libin Lu's avatar
Libin Lu committed
233
+ {
Libin Lu's avatar
Libin Lu committed
234
+   [RNFIRMessaging didReceiveNotificationResponse:response withCompletionHandler:completionHandler];
Libin Lu's avatar
Libin Lu committed
235
+ }
Libin Lu's avatar
Libin Lu committed
236 237 238 239 240 241
+ #else
+ - (void)userNotificationCenter:(UNUserNotificationCenter *)center didReceiveNotificationResponse:(UNNotificationResponse *)response withCompletionHandler:(void(^)())completionHandler
+ {
+   [RNFIRMessaging didReceiveNotificationResponse:response withCompletionHandler:completionHandler];
+ }
+ #endif
Libin Lu's avatar
Libin Lu committed
242
+
Libin Lu's avatar
Libin Lu committed
243
+ //You can skip this method if you don't want to use local notification
Libin Lu's avatar
Libin Lu committed
244
+ -(void)application:(UIApplication *)application didReceiveLocalNotification:(UILocalNotification *)notification {
Libin Lu's avatar
Libin Lu committed
245
+   [RNFIRMessaging didReceiveLocalNotification:notification];
Libin Lu's avatar
Libin Lu committed
246
+ }
247
+
Libin Lu's avatar
Libin Lu committed
248
+ - (void)application:(UIApplication *)application didReceiveRemoteNotification:(nonnull NSDictionary *)userInfo fetchCompletionHandler:(nonnull void (^)(UIBackgroundFetchResult))completionHandler{
Libin Lu's avatar
Libin Lu committed
249
+   [RNFIRMessaging didReceiveRemoteNotification:userInfo fetchCompletionHandler:completionHandler];
250 251
+ }
```
252

Libin Lu's avatar
Libin Lu committed
253
### Add Capabilities
254 255 256
- Select your project **Capabilities** and enable:
  - **Push Notifications**
  - *Background Modes* > **Remote notifications**.
257

Libin Lu's avatar
Libin Lu committed
258
### FirebaseAppDelegateProxyEnabled
Libin Lu's avatar
Libin Lu committed
259
This instruction assumes that you have FirebaseAppDelegateProxyEnabled=YES (default) so that Firebase will hook on push notification registration events. If you turn this flag off, you will be on your own to manage APNS tokens and link with Firebase token.
Libin Lu's avatar
Libin Lu committed
260

Libin Lu's avatar
Libin Lu committed
261
## Setup Local Notifications
Libin Lu's avatar
Libin Lu committed
262
NOTE: local notification does NOT have any dependency on FCM library but you still need to include Firebase to compile. If there are enough demand to use this functionality alone, I will separate it out into another repo
Libin Lu's avatar
Libin Lu committed
263

Libin Lu's avatar
Libin Lu committed
264
### IOS
Libin Lu's avatar
Libin Lu committed
265
No change required
266

Libin Lu's avatar
Libin Lu committed
267
### Android
Libin Lu's avatar
Libin Lu committed
268 269 270 271 272
Edit AndroidManifest.xml
```diff
  <uses-permission android:name="android.permission.INTERNET" />
+ <uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED" />
+ <uses-permission android:name="android.permission.VIBRATE" />
273

Libin Lu's avatar
Libin Lu committed
274
  <application
Libin Lu's avatar
Libin Lu committed
275
+    <meta-data android:name="com.google.firebase.messaging.default_notification_icon" android:resource="@mipmap/ic_notif"/>
Libin Lu's avatar
Libin Lu committed
276 277 278 279 280 281 282 283 284 285
+      <receiver android:name="com.evollu.react.fcm.FIRLocalMessagingPublisher"/>
+      <receiver android:enabled="true" android:exported="true"  android:name="com.evollu.react.fcm.FIRSystemBootEventReceiver">
+          <intent-filter>
+              <action android:name="android.intent.action.BOOT_COMPLETED"/>
+              <action android:name="android.intent.action.QUICKBOOT_POWERON"/>
+              <action android:name="com.htc.intent.action.QUICKBOOT_POWERON"/>
+              <category android:name="android.intent.category.DEFAULT" />
+          </intent-filter>
+      </receiver>
  </application>
286
```
Libin Lu's avatar
Libin Lu committed
287 288
NOTE: `com.evollu.react.fcm.FIRLocalMessagingPublisher` is required for presenting local notifications. `com.evollu.react.fcm.FIRSystemBootEventReceiver` is required only if you need to schedule future or recurring local notifications

Libin Lu's avatar
init  
Libin Lu committed
289

Libin Lu's avatar
Libin Lu committed
290
## Usage
Libin Lu's avatar
init  
Libin Lu committed
291 292

```javascript
Sarath's avatar
Sarath committed
293
import {Platform} from 'react-native';
Libin Lu's avatar
Libin Lu committed
294
import FCM, {FCMEvent, RemoteNotificationResult, WillPresentNotificationResult, NotificationType} from 'react-native-fcm';
Goran Gajic's avatar
Goran Gajic committed
295

Libin Lu's avatar
Libin Lu committed
296 297 298 299 300 301 302
// this shall be called regardless of app state: running, background or not running. Won't be called when app is killed by user in iOS
FCM.on(FCMEvent.Notification, async (notif) => {
    // there are two parts of notif. notif.notification contains the notification payload, notif.data contains data payload
    if(notif.local_notification){
      //this is a local notification
    }
    if(notif.opened_from_tray){
Libin Lu's avatar
Libin Lu committed
303 304
      //iOS: app is open/resumed because user clicked banner
      //Android: app is open/resumed because user clicked banner or tapped app icon
Libin Lu's avatar
Libin Lu committed
305
    }
Libin Lu's avatar
Libin Lu committed
306
    // await someAsyncCall();
Libin Lu's avatar
Libin Lu committed
307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330

    if(Platform.OS ==='ios'){
      //optional
      //iOS requires developers to call completionHandler to end notification process. If you do not call it your background remote notifications could be throttled, to read more about it see the above documentation link.
      //This library handles it for you automatically with default behavior (for remote notification, finish with NoData; for WillPresent, finish depend on "show_in_foreground"). However if you want to return different result, follow the following code to override
      //notif._notificationType is available for iOS platfrom
      switch(notif._notificationType){
        case NotificationType.Remote:
          notif.finish(RemoteNotificationResult.NewData) //other types available: RemoteNotificationResult.NewData, RemoteNotificationResult.ResultFailed
          break;
        case NotificationType.NotificationResponse:
          notif.finish();
          break;
        case NotificationType.WillPresent:
          notif.finish(WillPresentNotificationResult.All) //other types available: WillPresentNotificationResult.None
          break;
      }
    }
});
FCM.on(FCMEvent.RefreshToken, (token) => {
    console.log(token)
    // fcm token may not be available on first load, catch it here
});
        
331
class App extends Component {
Libin Lu's avatar
Libin Lu committed
332
    componentDidMount() {
Libin Lu's avatar
Libin Lu committed
333 334 335 336
        // iOS: show permission prompt for the first call. later just check permission in user settings
        // Android: check permission in user settings
        FCM.requestPermissions().then(()=>console.log('granted')).catch(()=>console.log('notification permission rejected'));
        
Libin Lu's avatar
Libin Lu committed
337 338 339 340
        FCM.getFCMToken().then(token => {
            console.log(token)
            // store fcm token in your server
        });
Libin Lu's avatar
Libin Lu committed
341
        
Libin Lu's avatar
Libin Lu committed
342
        this.notificationListener = FCM.on(FCMEvent.Notification, async (notif) => {
Libin Lu's avatar
Libin Lu committed
343
            // optional, do some component related stuff
Libin Lu's avatar
Libin Lu committed
344
        });
Libin Lu's avatar
Libin Lu committed
345
        
Libin Lu's avatar
Libin Lu committed
346 347
        // initial notification contains the notification that launchs the app. If user launchs app by clicking banner, the banner notification info will be here rather than through FCM.on event
        // sometimes Android kills activity when app goes to background, and when resume it broadcasts notification before JS is run. You can use FCM.getInitialNotification() to capture those missed events.
Libin Lu's avatar
Libin Lu committed
348
        // initial notification will be triggered all the time even when open app by icon so send some action identifier when you send notification
Alex Dunne's avatar
Alex Dunne committed
349
        FCM.getInitialNotification().then(notif => {
Libin Lu's avatar
Libin Lu committed
350 351
           console.log(notif)
        });
Libin Lu's avatar
Libin Lu committed
352
    }
Goran Gajic's avatar
Goran Gajic committed
353

Libin Lu's avatar
Libin Lu committed
354
    componentWillUnmount() {
355 356
        // stop listening for events
        this.notificationListener.remove();
Libin Lu's avatar
Libin Lu committed
357
    }
358

Libin Lu's avatar
Libin Lu committed
359
    otherMethods(){
360

Libin Lu's avatar
Libin Lu committed
361 362 363 364 365 366 367 368
        FCM.subscribeToTopic('/topics/foo-bar');
        FCM.unsubscribeFromTopic('/topics/foo-bar');
        FCM.presentLocalNotification({
            id: "UNIQ_ID_STRING",                               // (optional for instant notification)
            title: "My Notification Title",                     // as FCM payload
            body: "My Notification Message",                    // as FCM payload (required)
            sound: "default",                                   // as FCM payload
            priority: "high",                                   // as FCM payload
Libin Lu's avatar
Libin Lu committed
369 370 371
            click_action: "ACTION",                             // as FCM payload
            badge: 10,                                          // as FCM payload IOS only, set 0 to clear badges
            number: 10,                                         // Android only
Libin Lu's avatar
Libin Lu committed
372 373
            ticker: "My Notification Ticker",                   // Android only
            auto_cancel: true,                                  // Android only (default true)
Libin Lu's avatar
Libin Lu committed
374
            large_icon: "ic_launcher",                           // Android only
Libin Lu's avatar
Libin Lu committed
375
            icon: "ic_launcher",                                // as FCM payload, you can relace this with custom icon you put in mipmap
Libin Lu's avatar
Libin Lu committed
376 377 378
            big_text: "Show when notification is expanded",     // Android only
            sub_text: "This is a subText",                      // Android only
            color: "red",                                       // Android only
Libin Lu's avatar
Libin Lu committed
379
            vibrate: 300,                                       // Android only default: 300, no vibration if you pass 0
Libin Lu's avatar
Libin Lu committed
380
            group: "group",                                     // Android only
Libin Lu's avatar
Libin Lu committed
381
            picture: "https://google.png",                      // Android only bigPicture style
Libin Lu's avatar
Libin Lu committed
382
            ongoing: true,                                      // Android only
Libin Lu's avatar
Libin Lu committed
383
            my_custom_data:'my_custom_field_value',             // extra data you want to throw
384
            lights: true,                                       // Android only, LED blinking (default false)
Libin Lu's avatar
Libin Lu committed
385
            show_in_foreground                                  // notification when app is in foreground (local & remote)
Libin Lu's avatar
Libin Lu committed
386
        });
387

Libin Lu's avatar
Libin Lu committed
388
        FCM.scheduleLocalNotification({
Libin Lu's avatar
Libin Lu committed
389
            fire_date: new Date().getTime(),      //RN's converter is used, accept epoch time and whatever that converter supports
Libin Lu's avatar
Libin Lu committed
390
            id: "UNIQ_ID_STRING",    //REQUIRED! this is what you use to lookup and delete notification. In android notification with same ID will override each other
Libin Lu's avatar
Libin Lu committed
391 392
            body: "from future past",
            repeat_interval: "week" //day, hour
Libin Lu's avatar
Libin Lu committed
393
        })
Libin Lu's avatar
Libin Lu committed
394 395

        FCM.getScheduledLocalNotifications().then(notif=>console.log(notif));
396

Libin Lu's avatar
Libin Lu committed
397 398 399
        //these clears notification from notification center/tray
        FCM.removeAllDeliveredNotifications()
        FCM.removeDeliveredNotification("UNIQ_ID_STRING")
400

Libin Lu's avatar
Libin Lu committed
401 402 403
        //these removes future local notifications
        FCM.cancelAllLocalNotifications()
        FCM.cancelLocalNotification("UNIQ_ID_STRING")
404

405
        FCM.setBadgeNumber(1);                                       // iOS only and there's no way to set it in Android, yet.
406
        FCM.getBadgeNumber().then(number=>console.log(number));     // iOS only and there's no way to get it in Android, yet.
407
        FCM.send('984XXXXXXXXX', {
408
          my_custom_data_1: 'my_custom_field_value_1',
409 410
          my_custom_data_2: 'my_custom_field_value_2'
        });
Sean Adkinson's avatar
Sean Adkinson committed
411

412 413 414 415 416 417
        FCM.deleteInstanceId()
            .then( () => {
              //Deleted instance id successfully
              //This will reset Instance ID and revokes all tokens.
            })
            .catch(error => {
Sean Adkinson's avatar
Sean Adkinson committed
418
              //Error while deleting instance id
419
            });
Libin Lu's avatar
Libin Lu committed
420
    }
421
}
Libin Lu's avatar
init  
Libin Lu committed
422 423
```

Lucas Bento's avatar
Lucas Bento committed
424
### Build custom push notification for Android
Libin Lu's avatar
Libin Lu committed
425 426
Firebase android misses important feature of android notification like `group`, `priority` and etc. As a work around you can send data message (no `notification` payload at all) and this repo will build a local notification for you. If you pass `custom_notification` in the payload, the repo will treat the content as a local notification config and shows immediately.

Libin Lu's avatar
Libin Lu committed
427
NOTE: By using this work around, you will have to send different types of payload for iOS and Android devices because custom_notification isn't supported on iOS
Libin Lu's avatar
Libin Lu committed
428 429

WARNING: `custom_notification` **cannot** be used together with `notification` attribute. use `data` **ALONE**
Libin Lu's avatar
Libin Lu committed
430 431 432 433 434 435 436 437

Example of payload that is sent to FCM server:
```
{
  "to":"FCM_TOKEN",
  "data": {
    "type":"MEASURE_CHANGE",
    "custom_notification": {
Libin Lu's avatar
Libin Lu committed
438
      "body": "test body",
Libin Lu's avatar
Libin Lu committed
439 440 441 442 443
      "title": "test title",
      "color":"#00ACD4",
      "priority":"high",
      "icon":"ic_notif",
      "group": "GROUP",
Libin Lu's avatar
Libin Lu committed
444 445
      "id": "id",
      "show_in_foreground": true
Libin Lu's avatar
Libin Lu committed
446 447 448 449 450 451 452
    }
  }
}
```

Check local notification guide below for configuration.

Sean Adkinson's avatar
Sean Adkinson committed
453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472
**IMPORTANT**: When using the `admin.messaging` API, you need to `JSON.stringify` the `custom_notification` value:

```
let tokens = [...];
let payload = {
  data: {
    custom_notification: JSON.stringify({
      body: 'Message body',
      title: 'Message title'
      ...
    })
  }
};
let options = { priority: "high" };

admin
  .messaging()
  .sendToDevice(tokens, payload, options);
```

473
### Behaviour when sending `notification` and `data` payload through GCM
Libin Lu's avatar
Libin Lu committed
474
- When user clicks notification to **launch** the application, you can get that notification by calling `FCM.getInitialNotification`. (NOTE: reloading javascript or resuming from background won't change the value)
Libin Lu's avatar
Libin Lu committed
475

Libin Lu's avatar
Libin Lu committed
476 477 478 479 480
- When app is running in background (the tricky one, I strongly suggest you try it out yourself)
 - IOS will receive notificaton from `FCMNotificationReceived` event
    * if you pass `content_available` flag true, you will receive one when app is in background and another one when user resume the app. [more info](http://www.rahuljiresal.com/2015/03/retract-push-notifications-on-ios/)
    * if you just pass `notification`, you will only receive one when user resume the app.
    * you will not see banner if `notification->body` is not defined.
481
 - Android will receive notificaton from `FCMNotificationReceived` event
Naisheel Verdhan's avatar
Naisheel Verdhan committed
482
    * if you pass `notification` payload, it will receive data when user click on notification
483 484 485 486 487
    * if you pass `data` payload only, it will receive data when in background

   e.g. fcm payload looks like:

   ```json
Libin Lu's avatar
Libin Lu committed
488 489 490 491 492 493 494 495 496 497 498 499 500
   {
      "to":"some_device_token",
      "content_available": true,
      "notification": {
          "title": "hello",
          "body": "yo",
          "click_action": "fcm.ACTION.HELLO"
      },
      "data": {
          "extra":"juice"
      }
    }
    ```
501 502

    and event callback will receive as:
503

504 505 506 507
    - Android
      ```json
      {
        "fcm": {"action": "fcm.ACTION.HELLO"},
Libin Lu's avatar
Libin Lu committed
508
        "opened_from_tray": 1,
509 510 511
        "extra": "juice"
      }
      ```
512

513 514 515 516
    - iOS
      ```json
      {
        "apns": {"action_category": "fcm.ACTION.HELLO"},
Libin Lu's avatar
Libin Lu committed
517
        "opened_from_tray": 1,
518 519 520
        "extra": "juice"
      }
      ```
521

Libin Lu's avatar
Libin Lu committed
522
- When app is running in foreground
Naisheel Verdhan's avatar
Naisheel Verdhan committed
523
 - IOS will receive notification and android **won't** (better not to do anything in foreground for hybrid and send a separate data message.)
524

Naisheel Verdhan's avatar
Naisheel Verdhan committed
525
NOTE: it is recommended not to rely on `data` payload for click_action as it can be overwritten (check [this](http://stackoverflow.com/questions/33738848/handle-multiple-notifications-with-gcm)).
526

527 528 529 530 531
### Quick notes about upstream messages
If your app server implements the [XMPP Connection Server](https://firebase.google.com/docs/cloud-messaging/server#implementing-the-xmpp-connection-server-protocol) protocol, it can receive upstream messages from a user's device to the cloud. To initiate an upstream message, call the `FCM.send()` method with your Firebase `Sender ID` and a `Data Object` as parameters as follows:

```javascript
FCM.send('984XXXXXXXXX', {
532
  my_custom_data_1: 'my_custom_field_value_1',
533 534 535 536 537 538
  my_custom_data_2: 'my_custom_field_value_2'
});
```

The `Data Object` is message data comprising as many key-value pairs of the message's payload as are needed (ensure that the value of each pair in the data object is a `string`). Your `Sender ID` is a unique numerical value generated when you created your Firebase project, it is available in the `Cloud Messaging` tab of the Firebase console `Settings` pane. The sender ID is used to identify each app server that can send messages to the client app.

Libin Lu's avatar
init  
Libin Lu committed
539
## Q & A
540

Libin Lu's avatar
Libin Lu committed
541 542 543 544 545 546
#### Why do you build another local notification
Yes there are `react-native-push-notification` and `react-native-system-notification` which are great libraries. However
- We want a unified local notification library but people are reporting using react-native-push-notification with this repo has compatibility issue as `react-native-push-notification` also sets up GCM.
- We want to have local notification to have similar syntax as remote notification payload.
- The PushNotificationIOS by react native team is still missing features that recurring, so we are adding it here

547
#### My Android build is failing
Libin Lu's avatar
Libin Lu committed
548 549 550 551 552 553 554 555 556 557 558 559 560
Try update your SDK and google play service. If you are having multiple plugins requiring different version of play-service sdk, use force to lock in version
```
dependencies {
    ...
    compile ('com.android.support:appcompat-v7:25.0.1') {
        exclude group: 'com.google.android', module: 'support-v4'
    }
    compile ('com.google.android.gms:play-services-gcm:10.0.1') {
        force = true;
    }
   ...
}
```
561

Libin Lu's avatar
Libin Lu committed
562 563
#### My App throws FCM function undefined error
There seems to be link issue with rnpm. Make sure that there is `new FIRMessagingPackage(),` in your `Application.java` file
Libin Lu's avatar
Libin Lu committed
564

Libin Lu's avatar
Libin Lu committed
565 566
#### I can't get notification in iOS emulator
Remote notification can't reach iOS emulator since it can't fetch APNS token. Use real device.
567

Libin Lu's avatar
Libin Lu committed
568 569 570 571
#### I'm not getting notfication when app is in background
1. Make sure you've uploaded APNS certificates to Firebase and test with Firebase's native example to make sure certs are correct
2. Try simple payload first, sometimes notification doesn't show up because of empty body, wrong sound name etc.

Libin Lu's avatar
Libin Lu committed
572
#### App running in background doesn't trigger `FCMNotificationReceived` when receiving hybrid notification [Android]
573
These is [an issue opened for that](https://github.com/google/gcm/issues/63). Behavior is not consistent between 2 platforms
574

Libin Lu's avatar
Libin Lu committed
575
#### Android notification is showing a white icon
576 577
Since Lollipop, the push notification icon is required to be all white, otherwise it will be a white circle.

Libin Lu's avatar
Libin Lu committed
578 579 580
#### iOS not receiving notification when the app running in the background
- Try adding Background Modes permission in Xcode->Click on project file->Capabilities tab->Background Modes->Remote Notifications

581 582 583 584 585 586 587
#### I am using Proguard
You need to add this to your `android/app/proguard-rules.pro`:
```
# Google Play Services
-keep class com.google.android.gms.** { *; }
-dontwarn com.google.android.gms.**
```
Libin Lu's avatar
init  
Libin Lu committed
588

Libin Lu's avatar
Libin Lu committed
589 590 591
#### I'm getting `com.android.dex.DexException: Multiple dex files define Lcom/google/android/gms/internal/zzqf;`
It is most likely that you are using other react-native-modules that requires conflicting google play service
search for `compile "com.google.android.gms` in android and see who specifies specific version. Resolve conflict by loosing their version or specify a version resolve in gradle.
Libin Lu's avatar
Libin Lu committed
592
Check this article https://medium.com/@suchydan/how-to-solve-google-play-services-version-collision-in-gradle-dependencies-ef086ae5c75f#.9l0u84y9t
Libin Lu's avatar
Libin Lu committed
593

Libin Lu's avatar
Libin Lu committed
594
#### How do I tell if user clicks the notification banner?
Naisheel Verdhan's avatar
Naisheel Verdhan committed
595
Check open from tray flag in notification. It will be either 0 or 1 for iOS and undefined or 1 for android. I decide for iOS based on [this](http://stackoverflow.com/questions/20569201/remote-notification-method-called-twice), and for android I set it if notification is triggered by intent change.
Libin Lu's avatar
Libin Lu committed
596

Libin Lu's avatar
Libin Lu committed
597
#### Android notification doesn't vibrate/show head-up display etc
598
All available features are [here](https://firebase.google.com/docs/cloud-messaging/http-server-ref#notification-payload-support). FCM may add more support in the future but there is no timeline.
Libin Lu's avatar
Libin Lu committed
599
In the mean time, you can pass "custom_notification" in a data message. This repo will show a local notification for you so you can set priority etc
Libin Lu's avatar
Libin Lu committed
600

Libin Lu's avatar
Libin Lu committed
601 602 603
#### How do I do xxx with FCM?
check out [official docs and see if they support](https://firebase.google.com/docs/cloud-messaging/concept-options)

Libin Lu's avatar
Libin Lu committed
604
#### I want to add advanced feature that FCM doesn't support for remote notification
Libin Lu's avatar
Libin Lu committed
605
You can either wait for FCM to develop it or you have to write native code to create notifications.
Libin Lu's avatar
Libin Lu committed
606 607
- for iOS, you can do it in `didReceiveRemoteNotification` in `appDelegate.m`
- for android, you can do it by implementing a service similar to "com.evollu.react.fcm.MessagingService"
Libin Lu's avatar
Libin Lu committed
608

Libin Lu's avatar
Libin Lu committed
609 610
Or if you have a good way to wake up react native javascript thread please let me know, although I'm worring waking up the whole application is too expensive.

Libin Lu's avatar
Libin Lu committed
611 612 613 614 615 616 617 618 619 620 621 622
#### What about new notifications in iOS 10
Congratulations, now you have 5 notification handler to register!
in sum
- `willPresentNotification` is introduced in iOS 10 and will only be called when local/remote notification will show up. This allows you to run some code **before** notification shows up. You can also decide how to show the notification.
- `didReceiveNotificationResponse` is introduced in iOS 10 and provides user's response together with local/remote notification. It could be swipe, text input etc.
- `didReceiveLocalNotification` is for iOS 9 and below. Triggered when user clicks local notification. replaced by `didReceiveNotificationResponse`
- `didReceiveRemoteNotification` is for iOS 9 and below. Triggered when remote notification received.
- `didReceiveRemoteNotification:fetchCompletionHandler` is for both iOS 9 and 10. it gets triggered 2 times for each remote notification. 1st time when notification is received. 2nd time when notification is clicked. in iOS 9, it serves us the purpose of both `willPresentNotification` and `didReceiveNotificationResponse` but for remote notification only. in iOS 10, you don't need it in most of the case unless you need to do background fetching

Great, how do I configure for FCM?
It is up to you! FCM is just a bridging library that passes notification into javascript world. You can define your own NSDictionary and pass it into notification.

Libin Lu's avatar
Libin Lu committed
623
#### I want to show notification when app is in foreground
Libin Lu's avatar
Libin Lu committed
624
Use `show_in_foreground` attribute to tell app to show banner even if the app is in foreground.
Libin Lu's avatar
Libin Lu committed
625
NOTE: this flag doesn't work for Android push notification, use `custom_notification` to achieve this.
Libin Lu's avatar
Libin Lu committed
626

Libin Lu's avatar
Libin Lu committed
627 628 629
#### Do I need to handle APNS token registration?
No. Method swizzling in Firebase Cloud Messaging handles this unless you turn that off. Then you are on your own to implement the handling. Check this link https://firebase.google.com/docs/cloud-messaging/ios/client

Libin Lu's avatar
Libin Lu committed
630 631 632
#### I want to add actions in iOS notification
Check this https://github.com/evollu/react-native-fcm/issues/325

Libin Lu's avatar
Libin Lu committed
633 634 635
#### React/RCTBridgeModule.h not found
This is mostly caused by React Native upgrade. Here is a fix http://stackoverflow.com/questions/41477241/react-native-xcode-upgrade-and-now-rctconvert-h-not-found

636 637
#### Some features are missing
Issues and pull requests are welcome. Let's make this thing better!
638

Libin Lu's avatar
Libin Lu committed
639
#### Credits
Libin Lu's avatar
Libin Lu committed
640
Local notification implementation is inspired by react-native-push-notification by zo0r