Skip to content

Latest commit

 

History

History
345 lines (264 loc) · 7.86 KB

README.md

File metadata and controls

345 lines (264 loc) · 7.86 KB

☝🏼 React Native Permissions

npm version npm Platform - Android and iOS MIT styled with prettier

Check and request user permissions in React Native

⚠️  Branch "master" is a WIP of version 2.0.0

Support

version react-native version
2.0.0+ 0.59.5+
1.1.1 0.40.0 - 0.52.2

Setup

$ npm install --save react-native-permissions
# --- or ---
$ yarn add react-native-permissions

iOS

To allow installation of the needed permission handlers for your project (and only them), react-native-permissions uses CocoaPods. Update the following line with your path to node_modules/ and add it to your podfile:

target 'YourAwesomeProject' do

  # …

  pod 'RNPermissions', :path => '../node_modules/react-native-permissions', :subspecs => [
    'Core',
    ## Uncomment wanted permissions
    # 'BluetoothPeripheral',
    # 'Calendars',
    # 'Camera',
    # 'Contacts',
    # 'FaceID',
    # 'LocationAlways',
    # 'LocationWhenInUse',
    # 'MediaLibrary',
    # 'Microphone',
    # 'Motion',
    # 'Notifications',
    # 'PhotoLibrary',
    # 'Reminders',
    # 'Siri',
    # 'SpeechRecognition',
    # 'StoreKit',
  ]

end

Android

  1. Add the following lines to android/settings.gradle:
include ':react-native-permissions'
project(':react-native-permissions').projectDir = new File(rootProject.projectDir, '../node_modules/react-native-permissions/android')
  1. Add the compile line to the dependencies in android/app/build.gradle:
dependencies {
  // ...
  implementation project(':react-native-permissions')
}
  1. Add the import and link the package in MainApplication.java:
import com.reactnativecommunity.rnpermissions.RNPermissionsPackage; // <-- Add the import

public class MainApplication extends Application implements ReactApplication {

  // …

  @Override
  protected List<ReactPackage> getPackages() {
    return Arrays.<ReactPackage>asList(
      new MainReactPackage(),
      // …
      new RNPermissionsPackage() // <-- Add it to the packages list
    );
  }

  // …
}

📌 Don't forget to add permissions to AndroidManifest.xml for android and Info.plist for iOS.

API

Permissions statuses

Promises resolve into one of these statuses:

Return value Notes
RESULTS.UNAVAILABLE This feature is not available (on this device / in this context)
RESULTS.GRANTED The permission is granted
RESULTS.DENIED The permission has not been requested / is denied but requestable
RESULTS.NEVER_ASK_AGAIN The permission is denied and not requestable anymore

Supported permissions

import { PERMISSIONS } from 'react-native-permissions';

// Android permissions

// similar to PermissionsAndroid
PERMISSIONS.ANDROID.READ_CALENDAR;
PERMISSIONS.ANDROID.WRITE_CALENDAR;
PERMISSIONS.ANDROID.CAMERA;
PERMISSIONS.ANDROID.READ_CONTACTS;
PERMISSIONS.ANDROID.WRITE_CONTACTS;
PERMISSIONS.ANDROID.GET_ACCOUNTS;
PERMISSIONS.ANDROID.ACCESS_FINE_LOCATION;
PERMISSIONS.ANDROID.ACCESS_COARSE_LOCATION;
PERMISSIONS.ANDROID.RECORD_AUDIO;
PERMISSIONS.ANDROID.READ_PHONE_STATE;
PERMISSIONS.ANDROID.CALL_PHONE;
PERMISSIONS.ANDROID.READ_CALL_LOG;
PERMISSIONS.ANDROID.WRITE_CALL_LOG;
PERMISSIONS.ANDROID.ADD_VOICEMAIL;
PERMISSIONS.ANDROID.USE_SIP;
PERMISSIONS.ANDROID.PROCESS_OUTGOING_CALLS;
PERMISSIONS.ANDROID.BODY_SENSORS;
PERMISSIONS.ANDROID.SEND_SMS;
PERMISSIONS.ANDROID.RECEIVE_SMS;
PERMISSIONS.ANDROID.READ_SMS;
PERMISSIONS.ANDROID.RECEIVE_WAP_PUSH;
PERMISSIONS.ANDROID.RECEIVE_MMS;
PERMISSIONS.ANDROID.READ_EXTERNAL_STORAGE;
PERMISSIONS.ANDROID.WRITE_EXTERNAL_STORAGE;
// exclusives ones
PERMISSIONS.ANDROID.ANSWER_PHONE_CALLS;
PERMISSIONS.ANDROID.ACCEPT_HANDOVER;
PERMISSIONS.ANDROID.READ_PHONE_NUMBERS;

// iOS permissions

PERMISSIONS.IOS.BLUETOOTH_PERIPHERAL;
PERMISSIONS.IOS.CALENDARS;
PERMISSIONS.IOS.CAMERA;
PERMISSIONS.IOS.CONTACTS;
PERMISSIONS.IOS.FACE_ID;
PERMISSIONS.IOS.LOCATION_ALWAYS;
PERMISSIONS.IOS.LOCATION_WHEN_IN_USE;
PERMISSIONS.IOS.MEDIA_LIBRARY;
PERMISSIONS.IOS.MICROPHONE;
PERMISSIONS.IOS.MOTION;
PERMISSIONS.IOS.NOTIFICATIONS;
PERMISSIONS.IOS.PHOTO_LIBRARY;
PERMISSIONS.IOS.REMINDERS;
PERMISSIONS.IOS.SIRI;
PERMISSIONS.IOS.SPEECH_RECOGNITION;
PERMISSIONS.IOS.STOREKIT;

Methods

types used in usage examples

type PermissionStatus =
  | 'granted'
  | 'denied'
  | 'never_ask_again'
  | 'unavailable';

check()

Check one permission status.

Method type

function check(permission: string): Promise<PermissionStatus>;

Usage example

import { check, PERMISSIONS, RESULTS } from 'react-native-permissions';

check(PERMISSIONS.IOS.LOCATION_ALWAYS)
  .then(result => {
    switch (result) {
      case RESULTS.UNAVAILABLE:
        console.log('the feature is not available');
        break;
      case RESULTS.GRANTED:
        console.log('permission is granted');
        break;
      case RESULTS.DENIED:
        console.log('permission is denied and / or requestable');
        break;
      case RESULTS.NEVER_ASK_AGAIN:
        console.log('permission is denied and not requestable');
        break;
    }
  })
  .catch(error => {
    // …
  });

checkMultiple()

Check multiples permissions.

Method type

function checkMultiple(
  permissions: string[],
): Promise<{ [permission: string]: PermissionStatus }>;

Usage example

import { checkMultiple, PERMISSIONS } from 'react-native-permissions';

checkMultiple([
  PERMISSIONS.IOS.LOCATION_ALWAYS,
  PERMISSIONS.IOS.MEDIA_LIBRARY,
]).then(results => {
  // results[PERMISSIONS.IOS.LOCATION_ALWAYS]
  // results[PERMISSIONS.IOS.MEDIA_LIBRARY]
});

request()

Request one permission.

Method type

type NotificationOption =
  | 'badge'
  | 'sound'
  | 'alert'
  | 'carPlay'
  | 'criticalAlert'
  | 'provisional';

type Rationale = {
  title: string;
  message: string;
  buttonPositive?: string;
  buttonNegative?: string;
  buttonNeutral?: string;
};

function request(
  permission: string,
  config: {
    notificationOptions?: NotificationOption[];
    rationale?: Rationale;
  } = {},
): Promise<PermissionStatus>;

Usage example

import { request, PERMISSIONS } from 'react-native-permissions';

request(PERMISSIONS.IOS.LOCATION_ALWAYS).then(result => {
  // …
});

requestMultiple()

Request multiples permissions.

Method type

function requestMultiple(
  permissions: string[],
): Promise<{ [permission: string]: PermissionStatus }>;

Usage example

import { requestMultiple, PERMISSIONS } from 'react-native-permissions';

requestMultiple([
  PERMISSIONS.IOS.LOCATION_ALWAYS,
  PERMISSIONS.IOS.MEDIA_LIBRARY,
]).then(results => {
  // results[PERMISSIONS.IOS.LOCATION_ALWAYS]
  // results[PERMISSIONS.IOS.MEDIA_LIBRARY]
});

openSettings()

Open application settings.

Method type

function openSettings(): Promise<void>;

Usage example

import { openSettings } from 'react-native-permissions';

openSettings().catch(() => console.warn('cannot open settings'));

🍎  iOS Notes

  • If notificationOptions config array is omitted on NOTIFICATIONS request, it will request alert, badge and sound.