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 5 6 7 8 9 10
[react-native-firebase](https://github.com/invertase/react-native-firebase/releases/tag/v4.0.0) has introduced new firebase messaging and remote/local notification features. It has good integration with other firebase features.  I would recommend new comers to check that.

Note that there are some advanced features still in progress 
- handle iOS remote notification when app is not running
- custom iOS notification actions 

### To existing react-native-fcm users
Libin Lu's avatar
Libin Lu committed
11 12
`react-native-firebase` now can do what `react-native-fcm` can so it is a waste of effort to build the same thing in parallel. 

Libin Lu's avatar
Libin Lu committed
13
Since I'm getting busier these days and start feeling challenging to maintain this repo every day while `react-native-firebase` has a larger team/company backing it, existing users may consider migrating to `react-native-firebase`.
Libin Lu's avatar
Libin Lu committed
14 15 16 17 18 19

I've created [an example project](https://github.com/evollu/react-native-fcm/tree/firebase/Examples/firebase-migration) using react-native-firebase as a migration reference

`react-native-fcm` will still take PRs and bug fixes, but possibly no new feature developement any more.


Libin Lu's avatar
Libin Lu committed
20 21

### Versions
Libin Lu's avatar
Libin Lu committed
22
- after v16.0.0, Android target SDK has be to >= 26 and build tool has to be >= 26.0.x
Libin Lu's avatar
Libin Lu committed
23
- for iOS SDK < 4, use react-native-fcm@6.2.3 (v6.x is still compatible with Firebase SDK v4)
24 25 26
- 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
27

Libin Lu's avatar
Libin Lu committed
28
### Example
29
- 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
30

Libin Lu's avatar
init  
Libin Lu committed
31 32 33
## Installation

- Run `npm install react-native-fcm --save`
Libin Lu's avatar
Libin Lu committed
34 35
- [Link libraries](https://facebook.github.io/react-native/docs/linking-libraries-ios.html)
  Note: the auto link doesn't work with xcworkspace so CocoaPods user needs to do manual linking
Libin Lu's avatar
Libin Lu committed
36
- You many need [this package for huawei phone](https://github.com/pgengoux/react-native-huawei-protected-apps)
Libin Lu's avatar
init  
Libin Lu committed
37

Libin Lu's avatar
Libin Lu committed
38 39 40 41
## Configure Firebase Console
### FCM config file

In [firebase console](https://console.firebase.google.com/), you can:
Sean Adkinson's avatar
Sean Adkinson committed
42
- for **Android**: download `google-services.json` file and place it in `android/app` directory
Libin Lu's avatar
Libin Lu committed
43 44 45 46 47
- 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

48
## Android Configuration
Libin Lu's avatar
init  
Libin Lu committed
49

Libin Lu's avatar
Libin Lu committed
50 51 52 53
- 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

54 55 56 57 58
- 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
59 60
```

Sagiv Ofek's avatar
Sagiv Ofek committed
61
- Edit `android/app/build.gradle`. Add at the bottom of the file:
62 63
```diff
  apply plugin: "com.android.application"
KazuyaKitahara's avatar
KazuyaKitahara committed
64
  ...
65
+ apply plugin: 'com.google.gms.google-services'
Libin Lu's avatar
init  
Libin Lu committed
66 67
```

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

70 71 72 73 74
```diff
  <application
    ...
    android:theme="@style/AppTheme">

Libin Lu's avatar
Libin Lu committed
75
+    <meta-data android:name="com.google.firebase.messaging.default_notification_icon" android:resource="@mipmap/ic_notif"/>
Libin Lu's avatar
Libin Lu committed
76
+    <meta-data android:name="com.google.firebase.messaging.default_notification_channel_id" android:value="my_default_channel"/>
Libin Lu's avatar
Libin Lu committed
77

Libin Lu's avatar
Libin Lu committed
78
+   <service android:name="com.evollu.react.fcm.MessagingService" android:enabled="true" android:exported="true">
79 80 81 82 83 84 85 86 87 88 89 90
+     <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
91
```
92

Libin Lu's avatar
Libin Lu committed
93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127
- Edit `{YOUR_MAIN_PROJECT}/build.gradle`:
```diff
buildscript {
    repositories {
        jcenter()
+        maven {
+            url 'https://maven.google.com/'
+            name 'Google'
+        }
    }
    dependencies {
+        classpath 'com.android.tools.build:gradle:3.1.1'
+        classpath 'com.google.gms:google-services:3.1.2'

        // NOTE: Do not place your application dependencies here; they belong
        // in the individual module build.gradle files
    }
}

allprojects {
    repositories {
        mavenLocal()
        jcenter()
        maven {
            // All of React Native (JS, Obj-C sources, Android binaries) is installed from npm
            url "$rootDir/../node_modules/react-native/android"
        }
+        maven {
+            url 'https://maven.google.com/'
+            name 'Google'
+        }
    }
}
```

Libin Lu's avatar
Libin Lu committed
128 129
- Edit `{YOUR_MAIN_PROJECT}/app/build.gradle`:
```diff
Libin Lu's avatar
Libin Lu committed
130 131 132 133 134 135 136 137 138 139 140 141 142 143
+ compileSdkVersion 27
+    buildToolsVersion "27.0.3"

    defaultConfig {
        applicationId "com.google.firebase.quickstart.fcm"
        minSdkVersion 16
+        targetSdkVersion 27
        versionCode 1
        versionName "1.0"
        ndk {
            abiFilters "armeabi-v7a", "x86"
        }
    }

Libin Lu's avatar
Libin Lu committed
144
 dependencies {
145
+    compile project(':react-native-fcm')
Libin Lu's avatar
Libin Lu committed
146 147 148
     compile fileTree(dir: "libs", include: ["*.jar"])
     compile "com.facebook.react:react-native:+"  // From node_modules
 }
Libin Lu's avatar
Libin Lu committed
149 150 151
 
 //bottom
 + apply plugin: "com.google.gms.google-services"
Libin Lu's avatar
Libin Lu committed
152
```
Libin Lu's avatar
Libin Lu committed
153 154
If you are using other firebase libraries, check this for solving dependency conflicts https://github.com/evollu/react-native-fcm/blob/master/Examples/simple-fcm-client/android/app/build.gradle#L133

Ashish Chaudhary's avatar
Ashish Chaudhary committed
155
- Edit `android/settings.gradle`
156 157 158 159 160 161
```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
162

Libin Lu's avatar
Libin Lu committed
163 164 165 166 167 168 169 170 171 172 173 174 175
- Edit `MainActivity.java`. This fixes [a bug](https://stackoverflow.com/questions/14853327/intent-not-restored-correctly-after-activity-is-killed-if-clear-top-and-single-t/18307360#18307360)
```diff
+ 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
176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193
- Make sure in `MainApplication.java` you have
```diff
    @Override
    protected List<ReactPackage> getPackages() {
      return Arrays.<ReactPackage>asList(
          new MainReactPackage(),
            new MapsPackage(),
+           new FIRMessagingPackage()
      );
    }

+ @Override
+  public void onCreate() { // <-- Check this block exists
+    super.onCreate();
+    SoLoader.init(this, /* native exopackage */ false); // <-- Check this line exists within the block
+  }
```

194
### Config for notification and `click_action` in Android
195 196 197 198 199 200 201 202 203 204 205 206 207

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>
208 209
      <action android:name="android.intent.action.MAIN" />
      <category android:name="android.intent.category.LAUNCHER" />
210 211
    </intent-filter>
  </activity>
212
```
213 214

Notes:
Libin Lu's avatar
Libin Lu committed
215
- `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
216
- you if want to handle `click_action` you need to add custom intent-filter, check native android documentation
217 218


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

Libin Lu's avatar
Libin Lu committed
221
- RN 0.28:
222 223 224 225 226 227 228 229 230 231 232 233 234 235

```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
236
NOTE: Verify that react-native links correctly in `MainApplication.java`
237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257

```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(),
      );
    }
 ```   



258 259 260 261 262 263 264 265 266 267 268 269 270
- 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);
+   }       
271
```
Libin Lu's avatar
init  
Libin Lu committed
272

273 274 275
Notes:
- `@Override` is added to update intent on notification click

276
## IOS Configuration
Libin Lu's avatar
init  
Libin Lu committed
277

Libin Lu's avatar
Libin Lu committed
278 279
### Pod approach:

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

282
Configure the project:
Libin Lu's avatar
Libin Lu committed
283 284
```
cd ios && pod init
285 286 287 288 289 290 291
```

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

Edit the newly created `Podfile`:
```diff
  # Pods for YOURAPP
Nick Sarafa's avatar
Nick Sarafa committed
292
+ pod 'Firebase/Messaging'
293 294 295 296 297
```

Install the `Firebase/Messaging` pod:
```
pod install
Libin Lu's avatar
Libin Lu committed
298
```
Libin Lu's avatar
Libin Lu committed
299
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
Libin Lu committed
300
NOTE: there is a working example in `master` branch
Libin Lu's avatar
init  
Libin Lu committed
301

Libin Lu's avatar
Libin Lu committed
302
### Non Cocoapod approach
303

Libin Lu's avatar
Libin Lu committed
304
1. Follow the instruction on [Integrate without CocoaPods](https://firebase.google.com/docs/ios/setup#frameworks).
Libin Lu's avatar
Libin Lu committed
305
- Import libraries, add Capabilities (background running and push notification), upload APNS and etc etc etc...
Libin Lu's avatar
Libin Lu committed
306 307 308
2. Put frameworks under `ios/Frameworks` folder, and drag those files into your xcode solution -> Frameworks
3. Put `firebase.h` and `module.modulemap` under `ios/Frameworks` folder, no need to drag into solution
4. Modify your project's `User Header Search Paths` and add `$(PROJECT_DIR)/Frameworks`
Libin Lu's avatar
Libin Lu committed
309 310
<img width="796" alt="screen shot 2018-03-05 at 2 17 03 pm" src="https://user-images.githubusercontent.com/9213224/36994792-263f05c4-2080-11e8-9d46-9b11ef49962a.png">
NOTE: There is a working example in `no-pod` branch
Libin Lu's avatar
Libin Lu committed
311 312

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

Libin Lu's avatar
Libin Lu committed
314 315
Edit `AppDelegate.h`:
```diff
Libin Lu's avatar
Libin Lu committed
316 317
+ @import UserNotifications;
+
Libin Lu's avatar
Libin Lu committed
318 319 320
+ @interface AppDelegate : UIResponder <UIApplicationDelegate,UNUserNotificationCenterDelegate>
- @interface AppDelegate : UIResponder <UIApplicationDelegate>
```
Libin Lu's avatar
init  
Libin Lu committed
321

322 323 324 325 326 327 328 329 330
Edit `AppDelegate.m`:
```diff
+ #import "RNFIRMessaging.h"
  //...

  - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
  {
  //...
+   [FIRApp configure];
Libin Lu's avatar
Libin Lu committed
331
+   [[UNUserNotificationCenter currentNotificationCenter] setDelegate:self];
332 333 334

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

Libin Lu's avatar
Libin Lu committed
336
+
Libin Lu's avatar
Libin Lu committed
337
+ - (void)userNotificationCenter:(UNUserNotificationCenter *)center willPresentNotification:(UNNotification *)notification withCompletionHandler:(void (^)(UNNotificationPresentationOptions))completionHandler
Libin Lu's avatar
Libin Lu committed
338
+ {
Libin Lu's avatar
Libin Lu committed
339
+   [RNFIRMessaging willPresentNotification:notification withCompletionHandler:completionHandler];
Libin Lu's avatar
Libin Lu committed
340
+ }
Libin Lu's avatar
Libin Lu committed
341
+
Libin Lu's avatar
Libin Lu committed
342
+ #if defined(__IPHONE_11_0)
Libin Lu's avatar
Libin Lu committed
343
+ - (void)userNotificationCenter:(UNUserNotificationCenter *)center didReceiveNotificationResponse:(UNNotificationResponse *)response withCompletionHandler:(void (^)(void))completionHandler
Libin Lu's avatar
Libin Lu committed
344
+ {
Libin Lu's avatar
Libin Lu committed
345
+   [RNFIRMessaging didReceiveNotificationResponse:response withCompletionHandler:completionHandler];
Libin Lu's avatar
Libin Lu committed
346
+ }
Libin Lu's avatar
Libin Lu committed
347 348 349 350 351 352
+ #else
+ - (void)userNotificationCenter:(UNUserNotificationCenter *)center didReceiveNotificationResponse:(UNNotificationResponse *)response withCompletionHandler:(void(^)())completionHandler
+ {
+   [RNFIRMessaging didReceiveNotificationResponse:response withCompletionHandler:completionHandler];
+ }
+ #endif
Libin Lu's avatar
Libin Lu committed
353
+
Libin Lu's avatar
Libin Lu committed
354
+ //You can skip this method if you don't want to use local notification
Libin Lu's avatar
Libin Lu committed
355
+ -(void)application:(UIApplication *)application didReceiveLocalNotification:(UILocalNotification *)notification {
Libin Lu's avatar
Libin Lu committed
356
+   [RNFIRMessaging didReceiveLocalNotification:notification];
Libin Lu's avatar
Libin Lu committed
357
+ }
358
+
Libin Lu's avatar
Libin Lu committed
359
+ - (void)application:(UIApplication *)application didReceiveRemoteNotification:(nonnull NSDictionary *)userInfo fetchCompletionHandler:(nonnull void (^)(UIBackgroundFetchResult))completionHandler{
Libin Lu's avatar
Libin Lu committed
360
+   [RNFIRMessaging didReceiveRemoteNotification:userInfo fetchCompletionHandler:completionHandler];
361 362
+ }
```
363

Libin Lu's avatar
Libin Lu committed
364
### Add Capabilities
365 366 367
- Select your project **Capabilities** and enable:
  - **Push Notifications**
  - *Background Modes* > **Remote notifications**.
368

Libin Lu's avatar
Libin Lu committed
369
### FirebaseAppDelegateProxyEnabled
Libin Lu's avatar
Libin Lu committed
370
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
371

Libin Lu's avatar
Libin Lu committed
372
## Setup Local Notifications
Libin Lu's avatar
Libin Lu committed
373
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
374

Libin Lu's avatar
Libin Lu committed
375
### IOS
Libin Lu's avatar
Libin Lu committed
376
No change required
377

Libin Lu's avatar
Libin Lu committed
378
### Android
Libin Lu's avatar
Libin Lu committed
379 380 381 382 383
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" />
384

Anmol Wassan's avatar
Anmol Wassan committed
385
  <application>
Libin Lu's avatar
Libin Lu committed
386 387 388 389 390 391 392 393 394 395
+      <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>
396
```
Libin Lu's avatar
Libin Lu committed
397 398
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
399

Libin Lu's avatar
Libin Lu committed
400
## Usage
Libin Lu's avatar
Libin Lu committed
401
[Check example project](https://github.com/evollu/react-native-fcm/blob/master/Examples/simple-fcm-client/app/App.js#L68)
Libin Lu's avatar
init  
Libin Lu committed
402 403


Lucas Bento's avatar
Lucas Bento committed
404
### Build custom push notification for Android
Libin Lu's avatar
Libin Lu committed
405 406
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
407
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
408 409

WARNING: `custom_notification` **cannot** be used together with `notification` attribute. use `data` **ALONE**
Libin Lu's avatar
Libin Lu committed
410 411 412 413 414 415 416 417

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
418
      "body": "test body",
Libin Lu's avatar
Libin Lu committed
419 420 421 422 423
      "title": "test title",
      "color":"#00ACD4",
      "priority":"high",
      "icon":"ic_notif",
      "group": "GROUP",
Libin Lu's avatar
Libin Lu committed
424 425
      "id": "id",
      "show_in_foreground": true
Libin Lu's avatar
Libin Lu committed
426 427 428 429 430
    }
  }
}
```

Libin Lu's avatar
Libin Lu committed
431 432 433
Example of payload that is sent through firebase console:
<img width="753" alt="screen shot 2018-04-04 at 1 18 09 pm" src="https://user-images.githubusercontent.com/9213224/38323255-bbbfdd66-380a-11e8-95c2-bf32ced959b8.png">

Libin Lu's avatar
Libin Lu committed
434 435
Check local notification guide below for configuration.

Sean Adkinson's avatar
Sean Adkinson committed
436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455
**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);
```

456
### Behaviour when sending `notification` and `data` payload through GCM
Libin Lu's avatar
Libin Lu committed
457
- 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
458

Libin Lu's avatar
Libin Lu committed
459 460 461 462 463
- 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.
464
 - Android will receive notificaton from `FCMNotificationReceived` event
Naisheel Verdhan's avatar
Naisheel Verdhan committed
465
    * if you pass `notification` payload, it will receive data when user click on notification
466 467 468 469 470
    * 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
471 472 473 474 475 476 477 478 479 480 481 482 483
   {
      "to":"some_device_token",
      "content_available": true,
      "notification": {
          "title": "hello",
          "body": "yo",
          "click_action": "fcm.ACTION.HELLO"
      },
      "data": {
          "extra":"juice"
      }
    }
    ```
484 485

    and event callback will receive as:
486

487 488 489 490
    - Android
      ```json
      {
        "fcm": {"action": "fcm.ACTION.HELLO"},
Libin Lu's avatar
Libin Lu committed
491
        "opened_from_tray": 1,
492 493 494
        "extra": "juice"
      }
      ```
495

496 497 498 499
    - iOS
      ```json
      {
        "apns": {"action_category": "fcm.ACTION.HELLO"},
Libin Lu's avatar
Libin Lu committed
500
        "opened_from_tray": 1,
501 502 503
        "extra": "juice"
      }
      ```
504

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

Naisheel Verdhan's avatar
Naisheel Verdhan committed
508
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)).
509

510 511 512 513 514
### 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', {
515
  my_custom_data_1: 'my_custom_field_value_1',
516 517 518 519 520 521
  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.

522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541
### Sending remote notifications with category on iOS
If you want to send notification which will have actions as you defined in app it's important to correctly set it's `category` (`click_action`) property. It's also good to set `"content-available" : 1` so app will gets enough time to handle actions in background.

So the fcm payload should look like this:
```javascript
{
   "to": "some_device_token",
   "content_available": true,
   "notification": {
       "title": "Alarm",
       "subtitle": "First Alarm",
       "body": "First Alarm",
       "click_action": "com.myapp.MyCategory" // The id of notification category which you defined with FCM.setNotificationCategories
   },
   "data": {
       "extra": "juice"
   }
 }
 ```

Libin Lu's avatar
init  
Libin Lu committed
542
## Q & A
543

Libin Lu's avatar
Libin Lu committed
544 545 546 547 548 549
#### 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

550
#### My Android build is failing
delvedor's avatar
delvedor committed
551
Try update your SDK and google play service.
Libin Lu's avatar
Libin Lu committed
552
If you are having multiple plugins requiring different version of play-service sdk, skip conflicting group. The example project shows for how to colive with react-native-maps
Libin Lu's avatar
Libin Lu committed
553
```
Libin Lu's avatar
Libin Lu committed
554 555
    compile(project(':react-native-maps')) {
        exclude group: 'com.google.android.gms', module: 'play-services-base'
Libin Lu's avatar
Libin Lu committed
556 557
    }
```
558

Libin Lu's avatar
Libin Lu committed
559 560
#### 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
561

Libin Lu's avatar
Libin Lu committed
562 563
#### 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.
564

Libin Lu's avatar
Libin Lu committed
565 566 567 568
#### 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
569
#### App running in background doesn't trigger `FCMNotificationReceived` when receiving hybrid notification [Android]
570
These is [an issue opened for that](https://github.com/google/gcm/issues/63). Behavior is not consistent between 2 platforms
571

Libin Lu's avatar
Libin Lu committed
572
#### Android notification is showing a white icon
573 574
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
575 576 577
#### 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

578 579 580 581 582 583 584
#### 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
585

Libin Lu's avatar
Libin Lu committed
586 587 588
#### 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
589
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
590

Libin Lu's avatar
Libin Lu committed
591
#### How do I tell if user clicks the notification banner?
Naisheel Verdhan's avatar
Naisheel Verdhan committed
592
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
593

Libin Lu's avatar
Libin Lu committed
594
#### Android notification doesn't vibrate/show head-up display etc
595
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
596
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
597

Libin Lu's avatar
Libin Lu committed
598 599 600
#### 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
601
#### I want to add advanced feature that FCM doesn't support for remote notification
Libin Lu's avatar
Libin Lu committed
602
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
603 604
- 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
605

Libin Lu's avatar
Libin Lu committed
606 607
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
608 609 610 611 612 613 614 615 616 617 618 619
#### 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
620
#### I want to show notification when app is in foreground
Libin Lu's avatar
Libin Lu committed
621
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
622

Libin Lu's avatar
Libin Lu committed
623
NOTE: this flag doesn't work for Android push notification, use `custom_notification` to achieve this.
Libin Lu's avatar
Libin Lu committed
624

Libin Lu's avatar
Libin Lu committed
625 626
NOTE: foreground notification is not available on iOS 9 and below

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
Noitidart's avatar
Noitidart committed
641

delvedor's avatar
delvedor committed
642 643 644 645 646 647
#### I get the notifications in the logs, but the native prompt does not show up
Did you remember to ask the user permissions? ;)
```js
await FCM.requestPermissions({ badge: false, sound: true, alert: true })
```

Noitidart's avatar
Noitidart committed
648
## Sending remote notification
Noitidart's avatar
Noitidart committed
649 650 651 652

How to send a push notification from your server? You should `POST` to this endpoint:

    https://fcm.googleapis.com/fcm/send
delvedor's avatar
delvedor committed
653

Noitidart's avatar
Noitidart committed
654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697
You need to set the headers of `Content-Type` to `application/json` and `Authorization` to `key=******` where you replace `******` with the "Legacy server key" from here the Firebase dashbaord. Get this information by first going to:

1. https://console.firebase.google.com/
2. Click on "Gear" icon and click "Project Settingss". Screenshot: https://screenshotscdn.firefoxusercontent.com/images/35b93de8-44e1-49af-89d7-140b74c267c7.png
3. Click on "Cloud Message" tab and find "Legacy server key" here. Screenshot: https://screenshotscdn.firefoxusercontent.com/images/c52ec383-783d-47d3-a1e6-75249fb6f3fb.png

The body should be json like this:

```
{
  "to":"FCM_DEVICE_TOKEN_GOES_HERE",
  "data": {
    "custom_notification": {
      "body": "test body",
      "title": "test title",
      "color":"#00ACD4",
      "priority":"high",
      "icon":"ic_launcher",
      "group": "GROUP",
      "sound": "default",
      "id": "id",
      "show_in_foreground": true
    }
  }
}
```

Example:

```
fetch('https://fcm.googleapis.com/fcm/send', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json'
        'Authorization': 'key=EFefklefwef9efwefkejfwf'
    },
    body: JSON.stringify({
        "to":"kajfsdf:efawefwe_fsdfdsf-asfawefwefwf_asdfsdfasd-asdfasdfsd9A_asdfsdf_asdf",
        "data": {
            "custom_notification": {
            "body": "test body",
            "title": "test title",
            "color":"#00ACD4",
            "priority":"high",
Noitidart's avatar
Noitidart committed
698
            "icon":"ic_notif",
Noitidart's avatar
Noitidart committed
699 700 701 702 703 704 705 706 707
            "group": "GROUP",
            "sound": "default",
            "id": "id",
            "show_in_foreground": true
            }
        }
    })
})
```