react-native-app-utils ​

A simple React-Native utils library with random useful functions.
Mostly for use with background service tasks like notification onReceive events.
Currently supporting Android 5+, iOS will eventually be supported.

Quick Start ​

Choose your preferred package manager and let's get started.

npm: npm install react-native-app-utils
yarn: yarn add react-native-app-utils

Extra Installation Steps ​

First open android/app/src/main/AndroidManifest.xml and add these permissions if you intend to use wake locks and also allow your app to be woken up to appear over lock screens. Depending on device and Android version, doesn't always work.

<uses-permission android:name="android.permission.WAKE_LOCK" />
<uses-permission android:name="android.permission.DISABLE_KEYGUARD" />

<uses-permission android:name="android.permission.WAKE_LOCK" />
<uses-permission android:name="android.permission.DISABLE_KEYGUARD" />

also add this attribute to your main activity if you intend to use picture in picture mode.

android:supportsPictureInPicture="true"

android:supportsPictureInPicture="true"

You will experience errors if trying to use any of the wake lock or picture in picture functions without the above changes. Some devices might also need extra permissions.

React Native 0.60+ ​

You won't usually need to do any of the manual linking steps past this point.
Everything should just link up using the new autolinking feature.

Older React Native Versions ​

You should be able to run the following command to get everything linked up.
npx react-native link react-native-app-utils

If for some reason that doesn't work then you can follow the manual linking steps below.

Inside android/app/build.gradle add the following line in the existing dependencies section.

implementation project(':react-native-app-utils')

implementation project(':react-native-app-utils')

Inside android/settings.gradle add these lines to the bottom of the file.

include ':react-native-app-utils'
project(':react-native-app-utils').projectDir = new File(rootProject.projectDir, '../node_modules/react-native-app-utils/android')

include ':react-native-app-utils'
project(':react-native-app-utils').projectDir = new File(rootProject.projectDir, '../node_modules/react-native-app-utils/android')

Inside MainApplication.java import and add our package to the existing package list.

import app.stumble.utils.UtilsPackage;

private static List<ReactPackage> getPackages() {
    return Arrays.<ReactPackage>asList(
        new MainReactPackage(),
        new UtilsPackage()
    );
}

import app.stumble.utils.UtilsPackage;

private static List<ReactPackage> getPackages() {
    return Arrays.<ReactPackage>asList(
        new MainReactPackage(),
        new UtilsPackage()
    );
}

Usage ​

Here is a general rundown of the included functions and examples of their use.
Let's get everything from the module imported so we can actually use everything.

import {
    Activity,
    WakeLock,
    PartialWakeLock,
    WifiLock,
    ScreenLock,
    PictureInPicture
} from 'react-native-app-utils';

import {
    Activity,
    WakeLock,
    PartialWakeLock,
    WifiLock,
    ScreenLock,
    PictureInPicture
} from 'react-native-app-utils';

This will get your app to start or move to the front if it's already running. Might not work on some devices as restrictions starting apps from background services can be applied.

Activity.start();

Activity.start();

This will make your app goto the background and then eventually sleep. Very useful if you use the previous function to start your app but then want to put the app back to sleep. Our use case for this was when a call came in we wanted the app to start and show a call screen but if the call went unanswered for a while then we'd leave a notification and hide the app.

Activity.moveToBack();

Activity.moveToBack();

If for any reason you want to be able to prevent your app from being screenshotted or recorded then you can toggle security flags on the main activity. Useful for apps which protect privacy.

Activity.isSecure();
Activity.toggleSecure();

Activity.isSecure();
Activity.toggleSecure();

Wake locks have many uses, our implementation will turn the device screen on briefly to get the users attention. Screen locks will allow you to outright extend that time indefinitely but make sure to release them if having the screen on by force isn't a requirement of using your app. Don't forget about the battery usage, be nice!

WakeLock.acquire();
WakeLock.release();

WakeLock.acquire();
WakeLock.release();

Partial wake locks are more for if you want the device to be slightly awake to process background service tasks. Some modules might handle that themselvs. Very useful for handling notifications either way.

PartialWakeLock.acquire();
PartialWakeLock.release();

PartialWakeLock.acquire();
PartialWakeLock.release();

If for any reason you need to keep the wifi connection alive then you can use wifi locks. This does not prevent the user switching off their wifi connection. Best use case scenario would be if you need a connection for long periods due to background work or active interactions like a phone call.

WifiLock.acquire();
WifiLock.release();

WifiLock.acquire();
WifiLock.release();

Screen locks allow you to keep the device screen on indefinitely. Pretty useful for communication apps with ongoing tasks. You can use this after a non partial wake lock for good results.

ScreenLock.acquire();
ScreenLock.release();

ScreenLock.acquire();
ScreenLock.release();

Picture in Picture Mode ​

This is an experimental feature implementation that hasn't been fully tested and finalised yet. We will be looking to improve and/or add more functionality in the future.

For starters the following function will allow you to check if your app is currently in Picture in Picture mode. Very useful for component logic, maybe you want to hide some UI elements when entering Picture in Picture mode?

// Android API 24+
PictureInPicture.isActive();

// Android API 24+
PictureInPicture.isActive();

This will allow you to adjust the size of the Picture in Picture window.
Good for when the user changes between portrait and landscape orientations.
We will be looking to automate size adjustment in some way soon.

// Android API 26+
PictureInPicture.setAspectRatio( width: number, height: number );

// Android API 26+
PictureInPicture.setAspectRatio( width: number, height: number );

If toggled this will make your app go into Picture in Picture mode automatically instead of the app going to the background when closed. Very useful for different situations like if you have an ongoing call or video playing but still want basic app interactions.

// Android API 24+
PictureInPicture.toggleAutoEnter();

// Android API 24+
PictureInPicture.toggleAutoEnter();

We strongly recommend using vector based icons as they will scale nicely.https://github.com/oblador/react-native-vector-icons

Here are 3 different ways you can import icons ready for use with actions.
Make sure the icons are no larger than 24dp x 24dp or you will experience weird issues, all icons are also rendered white as default.

// Feathers Icon
import Icon from 'react-native-vector-icons/dist/Feather';
const camera = Icon.getImageSource( 'camera', 24 );

// Image
import { Image } from 'react-native';
const mic = Image.resolveAssetSource( require( './assets/images/mic.png' ) );

// Font URI
const phone = 'font://Feather/phone/24';

// Feathers Icon
import Icon from 'react-native-vector-icons/dist/Feather';
const camera = Icon.getImageSource( 'camera', 24 );

// Image
import { Image } from 'react-native';
const mic = Image.resolveAssetSource( require( './assets/images/mic.png' ) );

// Font URI
const phone = 'font://Feather/phone/24';

Here is a quick example of how to use Picture in Picture actions, usually limited to 3.

There are future plans to simplify and give more fine grained control over editing existing actions rather than replacing all of them each time the function is executed which would be ideal for a typical scenario like changing an action after an action has been pressed.

Make sure not to use spaces or weird characters for action ids.

// Android API 26+
PictureInPicture.setActions( [
    {
        id: 'toggle_camera',
        icon: camera,
        title: 'Toggle Camera',
        desc: 'Enables or disables the active camera.',
        callback: function() {

        }
    },
    {
        id: 'toggle_mic',
        icon: mic,
        title: 'Toggle Microphone',
        desc: 'Enables or disables the microphone.',
        callback: function() {

        }
    },
    {
        id: 'hangup_call',
        icon: phone,
        title: 'Hangup',
        desc: 'Hangs up the current active call.',
        callback: function() {

        }
    }
] );

// Android API 26+
PictureInPicture.setActions( [
    {
        id: 'toggle_camera',
        icon: camera,
        title: 'Toggle Camera',
        desc: 'Enables or disables the active camera.',
        callback: function() {

        }
    },
    {
        id: 'toggle_mic',
        icon: mic,
        title: 'Toggle Microphone',
        desc: 'Enables or disables the microphone.',
        callback: function() {

        }
    },
    {
        id: 'hangup_call',
        icon: phone,
        title: 'Hangup',
        desc: 'Hangs up the current active call.',
        callback: function() {

        }
    }
] );

Last but not least to actually enter and exit Picture in Picture mode you will need to use the following functions unless you have used the toggle function above.

// Android API 24+
PictureInPicture.enter();
PictureInPicture.exit();

// Android API 24+
PictureInPicture.enter();
PictureInPicture.exit();