Merge pull request #5 from jamesisaac/0.2

Native Android implementation

Author: jamesisaac

.gitignore

@@ -1,3 +1,11 @@
-/.idea
-/node_modules
-npm-debug.log
+/.idea/
+/android/.idea/
+/android/gen/
+/android/gradle/
+/android/gradlew
+/android/gradlew.bat
+/android/local.properties
+/node_modules/
+npm-debug.log
+yarn.lock
+yarn-debug.log

LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2017 James Isaac
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -1,63 +1,150 @@
 # react-native-background-task
 
-**WORK IN PROGRESS / NOT YET READY FOR PRODUCTION USE**
+[![npm version](https://img.shields.io/npm/v/react-native-background-task.svg)](https://www.npmjs.com/package/react-native-background-task)
+[![license](https://img.shields.io/github/license/jamesisaac/react-native-background-task.svg)](https://opensource.org/licenses/MIT)
+[![npm downloads](https://img.shields.io/npm/dm/react-native-background-task.svg)](https://www.npmjs.com/package/react-native-background-task)
 
-Periodic background tasks for React Native apps, cross-platform (iOS and Android), which run even when the app is closed.
+Periodic background tasks for React Native apps, cross-platform (iOS and
+Android), which run even when the app is closed.
 
-This builds on top of the native modules provided by the following two libraries:
+This library allows the scheduling of a single periodic task, which executes
+when the app is in the background or closed, no more frequently than every 15
+minutes.  Network, AsyncStorage etc can be used (anything except UI), so
+perfect for things like a background data sync for offline support.
 
-- **iOS**: [react-native-background-fetch](https://github.com/transistorsoft/react-native-background-fetch), which uses the iOS-specific `Background Fetch` technique.
-- **Android**: [react-native-background-job](https://github.com/vikeri/react-native-background-job), which provides a job scheduler on RN's built-in [Headless JS](https://facebook.github.io/react-native/docs/headless-js-android.html) (Android only).
+Behind the scenes, this library takes a different approach with each platform:
 
-To achieve a unified API, this package exposes the lowest common denominator (e.g. only support for a single task, even though Android can support multiple).
+- **Android**: A native implementation, which provides scheduling on top of
+  RN's built-in [Headless JS](https://facebook.github.io/react-native/docs/headless-js-android.html)
+  (Android only).
+  - Min API level: 16 (Android 4.1).
+- **iOS**: [react-native-background-fetch](https://github.com/transistorsoft/react-native-background-fetch),
+  which uses the iOS-specific `Background Fetch` technique.
 
-For more per-platform flexibility, those libraries should be used individually.
+To achieve a unified API, this library exposes the lowest common denominator
+(e.g. only support for a single task, even though Android can support multiple).
+
+For more per-platform flexibility, there are other platform-specific libraries
+with more granular customisation.
 
 ## Installation
 
 ```bash
-$ npm install --save react-native-background-task
+$ npm install react-native-background-task --save
 ```
+  
+### Android
+
+1. The linking of the library can be done automatically by running:
+
+  ```bash
+  $ react-native link react-native-background-task
+  ```
+
+2. One manual step is still needed - in your project file
+  `android/app/src/main/java/myapp/MainApplication.java`, add the following to
+  the end of the `onCreate()` method:
+  
+  ```java
+  BackgroundTaskPackage.useContext(this);
+  ```
+
+### iOS
 
-* **iOS**: Follow native iOS module installation instructions from
-  [react-native-background-fetch](https://github.com/transistorsoft/react-native-background-fetch)
-* **Android**: Follow native Android module installation instructions from
-  [react-native-background-job](https://github.com/vikeri/react-native-background-job)
-  * Recommended version: v1.1.0 (API has changed as of v1.1.3)
+For iOS support, this library relies on version 2.0.x of
+[react-native-background-fetch](https://github.com/transistorsoft/react-native-background-fetch)
+which can be installed as follows:
+
+```bash
+$ npm install [email protected] --save
+$ react-native link react-native-background-fetch
+```
+  
+This library will behave correctly on iOS as long as `react-native-background-fetch`
+is installed alongside it, and has been linked with your project.
 
 ## API
 
-### `register(task, options)`
+### `define(task)`
 
-Define the task that this module should be executing.
+Define the JS code that this module should be executing.
 
-- Will overwrite any previously registered task.
-- Should be called at the root of your main app entrypoint file.
-- Should `console.error` if it can't register the task
+- Should be called at the top level of your JS, **not** inside a component.
+  This is because in headless mode no components are mounted, but the code
+  still needs to be accessible.
+- Will overwrite any previously defined task.
 
 Parameters:
 
-* **`task`**: **required** `() => void` - Function to be executed in the background
-* **`options`**: `?object` - Any configuration you want to be set with
+- **`task`**: **required** `() => void` - Function to be executed in the background
+
+### `schedule(options)`
+
+Specify the scheduling options for the task, and register it with the
+platform's scheduler.
+
+- Should be called from inside a component (e.g. your App's
+  `componentDidMount`).  This is to avoid double-scheduling when the task
+  launches in headless mode.
+- Will `console.warn` if the device is task was unable to be scheduled.
+
+Parameters:
+
+- **`options?`**: `Object` - Any configuration you want to be set with
   the task.  Note that most of these will only work on one platform.
 
-  * **`period`** `number` - (Android only) Desired number of seconds between each
+  - **`period?`** `number` - (Android only) Desired number of seconds between each
     execution of the task.  Even on Android, the OS will only take this as a
-    recommendation, and will likely enforce a minimum of 15 minutes (similar to
-    iOS).  Default is 900 (15 minutes)
-  * **`timeout`** `number` - (Android only) Number of seconds the task will have
+    recommendation, and will enforce a minimum of 15 minutes (similar to iOS).
+    Default is 900 (15 minutes)
+  - **`timeout?`** `number` - (Android only) Number of seconds the task will have
     to execute.  iOS has a hardcoded limit of 30 seconds.  Default 30 seconds.
 
+### `finish()`
+
+**Must be called at the end of your task** to indicate to the OS that it's
+finished.  (Only required on iOS, no-op on Android).
+
 ### `cancel()`
 
-Cancels any currently registered task.
+Cancels any currently scheduled task.
 
-### `finish()`
+### `statusAsync()`
+
+Query the status of background tasks within this app.  Returns a Promise with
+an object of the following shape:
+
+- **`available`** `boolean` - Whether background tasks are available to the app.
+  On Android this will always be true, but on iOS background tasks could be
+  blocked (see [UIBackgroundRefreshStatus](https://developer.apple.com/documentation/uikit/uibackgroundrefreshstatus)).
+- **`unavailableReason?`** `string` - If unavailable, gives the reason:
+    - **`BackgroundTask.UNAVAILABLE_DENIED`** - The user explicitly disabled
+      background behavior for this app or for the whole system.
+    - **`BackgroundTask.UNAVAILABLE_RESTRICTED`** - Background updates
+      unavailable and can't be enabled by the user (e.g. parental controls).
+
+## Caveats
+
+- The exact timings of tasks are unpredictable (depends on device sleep state
+  etc.), and cannot be more frequent than every 15 minutes.  This library
+  should only be used for tasks that can have inexact timing, such as the
+  periodic background syncing of data.
+  
+Android:
+
+- Tasks will not run while the app is in the foreground, and scheduling can be
+  made even more imprecise when the app goes in/out of the foreground (as tasks
+  are rescheduled as soon as the app goes into the background).
+  
+iOS:
+
+- iOS Background Fetch does not work in the simulator.  It must be tested on a
+  real device.
+- The user can disable Background App Refresh for your app from their Settings
+  (use `statusAsync()` to check for this).
 
-Must be called at the end of your task to indicate to the OS that it's
-finished.  (Only required on iOS, no-op on Android).
 
-## Example
+## Examples
 
 ### Simple
 
@@ -66,12 +153,16 @@ import React from 'react'
 import { Text } from 'react-native'
 import BackgroundTask from 'react-native-background-task'
 
-BackgroundTask.register(() => {
+BackgroundTask.define(() => {
   console.log('Hello from a background task')
   BackgroundTask.finish()
 })
 
 class MyApp extends React.Component {
+  componentDidMount() {
+    BackgroundTask.schedule()
+  }
+  
   render() {
     return <Text>Hello world</Text>
   }
@@ -82,10 +173,10 @@ class MyApp extends React.Component {
 
 ```js
 import React from 'react'
-import { AsyncStorage, Button, Text } from 'react-native'
+import { Alert, AsyncStorage, Button } from 'react-native'
 import BackgroundTask from 'react-native-background-task'
 
-BackgroundTask.register(async () => {
+BackgroundTask.define(async () => {
   // Fetch some data over the network which we want the user to have an up-to-
   // date copy of, even if they have no network when using the app
   const response = await fetch('http://feeds.bbci.co.uk/news/rss.xml')
@@ -96,11 +187,34 @@ BackgroundTask.register(async () => {
 
   // Remember to call finish()
   BackgroundTask.finish()
-}, {
-  period: 1800, // Aim to run every 30 mins - more conservative on battery
 })
 
 class MyApp extends React.Component {
+  componentDidMount() {
+    BackgroundTask.schedule({
+      period: 1800, // Aim to run every 30 mins - more conservative on battery
+    })
+    
+    // Optional: Check if the device is blocking background tasks or not
+    this.checkStatus()
+  }
+  
+  async checkStatus() {
+    const status = await BackgroundTask.statusAsync()
+    
+    if (status.available) {
+      // Everything's fine
+      return
+    }
+    
+    const reason = status.unavailableReason
+    if (reason === BackgroundTask.UNAVAILABLE_DENIED) {
+      Alert.alert('Denied', 'Please enable background "Background App Refresh" for this app')
+    } else if (reason === BackgroundTask.UNAVAILABLE_RESTRICTED) {
+      Alert.alert('Restricted', 'Background tasks are restricted on your device')
+    }
+  }
+  
   render() {
     return (
       <View>

android/build.gradle

@@ -0,0 +1,35 @@
+buildscript {
+    repositories {
+        jcenter()
+    }
+
+    dependencies {
+        classpath 'com.android.tools.build:gradle:1.1.3'
+    }
+}
+
+apply plugin: 'com.android.library'
+
+android {
+    compileSdkVersion 23
+    buildToolsVersion "25.0.2"
+
+    defaultConfig {
+        minSdkVersion 16
+        targetSdkVersion 22
+        versionCode 1
+        versionName "1.0"
+    }
+    lintOptions {
+        abortOnError false
+    }
+}
+
+repositories {
+    mavenCentral()
+}
+
+dependencies {
+    compile 'com.facebook.react:react-native:+'
+    compile 'com.evernote:android-job:1.1.11'
+}

android/src/main/AndroidManifest.xml

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="utf-8"?>
+<manifest xmlns:android="http://schemas.android.com/apk/res/android"
+          package="com.jamesisaac.rnbackgroundtask">
+    <application>
+        <service android:name=".HeadlessTaskService"
+                 android:enabled="true" />
+    </application>
+</manifest>