Skip to content

Commit 970ee0e

Browse files
committed
Update Android info on README, also LICENSE
1 parent 4c846f0 commit 970ee0e

File tree

2 files changed

+84
-15
lines changed

2 files changed

+84
-15
lines changed

LICENSE

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
The MIT License (MIT)
22

3-
Copyright (c) 2013 Steve
3+
Copyright (c) 2016 Wix.com LTD
44

55
Permission is hereby granted, free of charge, to any person obtaining a copy of
66
this software and associated documentation files (the "Software"), to deal in

README.md

+83-14
Original file line numberDiff line numberDiff line change
@@ -17,9 +17,14 @@ Handle all the aspects of push notifications for your app, including remote and
1717

1818
![Interactive notifications example](https://s3.amazonaws.com/nrjio/interactive.gif)
1919

20-
### <img src="https://cdn1.iconfinder.com/data/icons/ios-7-style-metro-ui-icons/512/MetroUI_OS_Android.png" width=25 height=25/> Android
20+
### Android
2121

22-
TODO
22+
- Receiving notifications in any App state (foreground, background, "dead")
23+
- Built-in notification drawer management
24+
- High degree of code extensibility to allow for advanced custom layouts and specific notifications behavior as available by [Android's API](https://developer.android.com/training/notify-user/build-notification.html)
25+
- Android equivalent of React-Native's implementation of [`PushNotificationsIOS.getInitialNotification()`](https://facebook.github.io/react-native/docs/pushnotificationios.html#getinitialnotification).
26+
27+
>Upcoming: local notifications, background-state Rx queue (iOS equivalent)
2328
2429
## Installation
2530

@@ -63,27 +68,29 @@ And the following methods to support registration and receiving notifications:
6368
}
6469
```
6570

66-
### <img src="https://cdn1.iconfinder.com/data/icons/ios-7-style-metro-ui-icons/512/MetroUI_OS_Android.png" width=25 height=25/> Android
71+
### Android
6772

68-
> Note: Explicit installation on Android is only required if you're planning on **receiving push notifications**. It is **not** needed if you're only going to use 'local' notifications.
73+
> Installation on Android is necessary in case you wish to receive push notifications on your React-Native app.
6974
70-
Push notifications on Android are managed and dispatched using [Google's GCM service](https://developers.google.com/cloud-messaging/gcm) (now integrated into Firebase). The following installation steps are a TL;DR of [Google's GCM setup guide](https://developers.google.com/cloud-messaging/android/client). You can follow them to get GCM integrated quickly, but we recommend you in the very least have a peek at the guide's overview.
75+
Push notifications on Android are managed and dispatched using [Google's GCM service](https://developers.google.com/cloud-messaging/gcm) (now integrated into Firebase). The following installation steps are a TL;DR of [Google's GCM setup guide](https://developers.google.com/cloud-messaging/android/client). You can follow them to get GCM integrated quickly, but we recommend that you will in the very least have a peek at the guide's overview.
7176

7277
#### Step #1: Subscribe to Google's GCM
7378

74-
To set GCM in your app, you must first create a Google Firebase API-project and obtain a **Sender ID** and a **Server API Key**. If you have no existing API projects yet, the easiest way to go about is to create a project and get these attributes using [this step-by-step installation process](https://developers.google.com/mobile/add); Use [this tutorial](https://code.tutsplus.com/tutorials/how-to-get-started-with-push-notifications-on-android--cms-25870) for insturctions.
79+
To set GCM in your app, you must first create a Google API-project and obtain a **Sender ID** and a **Server API Key**. If you have no existing API projects yet, the easiest way to go about in creating one is using [this step-by-step installation process](https://developers.google.com/mobile/add); Use [this tutorial](https://code.tutsplus.com/tutorials/how-to-get-started-with-push-notifications-on-android--cms-25870) for insturctions.
7580

7681
Alternatively, follow [Google's complete guide](https://developers.google.com/cloud-messaging/android/client#create-an-api-project).
7782

7883
#### Step #2: Add Sender ID to Manifest File
7984

85+
Once obtained, bundle the Sender ID onto your main `manifest.xml` file:
86+
8087
```
8188
<manifest>
8289
...
8390
<application>
8491
...
8592
// Replace '1234567890' with your sender ID.
86-
// Important: Leave the trailing \0 intact!
93+
// IMPORTANT: Leave the trailing \0 intact!!!
8794
<meta-data android:name="com.wix.reactnativenotifications.gcmSenderId" android:value="1234567890\0"/>
8895
</application>
8996
</manifest>
@@ -111,7 +118,7 @@ class App extends Component {
111118
}
112119

113120
onPushRegistered(deviceToken) {
114-
console.log("Device Token Received: " + deviceToken);
121+
console.log("Device Token Received", deviceToken);
115122
}
116123

117124
componentWillUnmount() {
@@ -124,10 +131,29 @@ class App extends Component {
124131

125132
When you have the device token, POST it to your server and register the device in your notifications provider (Amazon SNS, Azure, etc.).
126133

134+
### Android
135+
136+
The React-Native code equivalent on Android is:
137+
138+
```javascript
139+
import {NotificationsAndroid} from 'react-native-notifications';
140+
141+
// On Android, we allow for only one (global) listener per each event type.
142+
NotificationsAndroid.setRegistrationTokenUpdateListener((deviceToken) => {
143+
console.log('Push-notifications regsitered!', deviceToken)
144+
});
145+
146+
```
147+
148+
`deviceToken` being the token used to identify the device on the GCM.
149+
127150
---
128151

152+
129153
## Handling Received Notifications
130154

155+
### iOS
156+
131157
When you receive a notification, the application can be in one of the following states:
132158

133159
1. **Forground**- When the app in running and is used by the user right now. in this case, `notificationReceivedForeground` event will be fired.
@@ -144,15 +170,15 @@ constructor() {
144170
}
145171

146172
onNotificationReceivedForeground(notification) {
147-
console.log("Notification Received Foreground: " + JSON.stringify(notification));
173+
console.log("Notification Received - Foreground", notification);
148174
}
149175

150176
onNotificationReceivedBackground(notification) {
151-
console.log("Notification Received Background: " + JSON.stringify(notification));
177+
console.log("Notification Received - Background", notification);
152178
}
153179

154180
onNotificationOpened(notification) {
155-
console.log("Notification Opened: " + JSON.stringify(notification));
181+
console.log("Notification opened by device user", notification);
156182
}
157183

158184
componentWillUnmount() {
@@ -163,7 +189,7 @@ componentWillUnmount() {
163189
}
164190
```
165191

166-
### Notification Object
192+
#### Notification Object
167193
When you receive a push notification, you'll get an instance of `IOSNotification` object, contains the following methods:
168194

169195
- **`getMessage()`**- returns the notification's main message string.
@@ -173,17 +199,60 @@ When you receive a push notification, you'll get an instance of `IOSNotification
173199
- **`getData()`**- returns the data payload (additional info) of the notification.
174200
- **`getType()`**- returns `managed` for managed notifications, otherwise returns `regular`.
175201

176-
177-
### Background Queue (Important!)
202+
#### Background Queue (Important!)
178203
When a push notification is opened but the app is not running, the application will be in a **cold launch** state, until the JS engine is up and ready to handle the notification.
179204
The application will collect the events (notifications, actions, etc.) that happend during the cold launch for you.
180205

181206
When your app is ready (most of the time it's after the call to `requestPermissions()`), just call to `NotificationsIOS.consumeBackgroundQueue();` in order to consume the background queue. For more info see `index.ios.js` in the example app.
182207

208+
### Android
209+
210+
```javascript
211+
import {NotificationsAndroid} from 'react-native-notifications';
212+
213+
// On Android, we allow for only one (global) listener per each event type.
214+
NotificationsAndroid.setNotificationReceivedListener((notification) => {
215+
console.log("Notification received on device", notification.getData());
216+
});
217+
NotificationsAndroid.setNotificationOpenedListener((notification) => {
218+
console.log("Notification opened by device user", notification.getData());
219+
});
220+
```
221+
222+
#### Notification Object
223+
- **`getData()`**- content of the `data` section of the original message (sent to GCM).
224+
- **`getTitle()`**- Convenience for returning `data.title`.
225+
- **`getMessage()`**- Convenience for returning `data.body`.
226+
183227
---
184228

229+
## Querying initial notification
230+
231+
React-Native's [`PushNotificationsIOS.getInitialNotification()`](https://facebook.github.io/react-native/docs/pushnotificationios.html#getinitialnotification) allows for the async retrieval of the original notification used to open the App on iOS, but it has no equivalent implementation for Android.
232+
233+
We provide a similar implementation on Android using `PendingNotifications.getInitialNotification()` which returns a promise:
234+
235+
```javascript
236+
import {NotificationsAndroid, PendingNotifications} from 'react-native-notifications';
237+
238+
PendingNotifications.getInitialNotification()
239+
.then((notification) => {
240+
console.log("Initial notification was:", (notification ? notification.getData() : 'N/A');
241+
})
242+
.catch((err) => console.error("getInitialNotifiation() failed", err));
243+
244+
```
245+
246+
> Notifications are considered 'initial' under the following terms:
247+
248+
> - User tapped on a notification, _AND_ -
249+
> - App was either not running at all ("dead" state), _OR_ it existed in the background with **no running activities** associated with it.
250+
251+
185252
## Triggering Local Notifications
186253
254+
> Currently, an iOS-only feture
255+
187256
You can schedule a local notification for future presentation.
188257
Triggering local notifications is fully compatible with React Native `PushNotificationsIOS` library.
189258

0 commit comments

Comments
 (0)