Skip to content

Latest commit

 

History

History
 
 

expo-contacts-nativescript-plugin

README.md

@nativescript-community/expo-contacts-nativescript-plugin

About

This is the NativeScript implementation of the Expo SDK's Contacts APIs.

  • For iOS, it installs the native iOS expo-contacts source as-is.
  • For Android, there is no support, as we're blocked on getting its dependency, expo-permissions, to work for Android.

It exposes the very same cross-platform TypeScript APIs as expo-contacts does – this was achieved largely by copy-pasting the TypeScript source files from expo-contacts.

Installation

This depends upon expo-permissions, so these instructions are effectively a union of all the dependencies for this and expo-permissions.

npm install --save @unimodules/core @nativescript-community/expo-nativescript-react-native-shim expo-permissions @nativescript-community/expo-permissions unimodules-permissions-interface unimodules-file-system-interface expo-contacts
ns plugin add @nativescript-community/expo-nativescript-adapter
ns plugin add @nativescript-community/expo-permissions-nativescript-plugin
ns plugin add @nativescript-community/expo-contacts-nativescript-plugin

## Once our plugin for the file system is released, you may install these, too:
# npm install --save expo-file-system
# ns plugin add @nativescript-community/expo-file-system-nativescript-plugin

Structure

expo-contacts-nativescript-plugin has the following peer dependencies:

Package

Native Module

Optional?

Purpose

iOS

Android

@unimodules/core

 UMCore org.unimodules.core Mandatory Implements the platform-agnostic API for consuming Expo Unimodules.

@nativescript-community/expo-nativescript-adapter

 UMNativeModulesProxy org.unimodules.adapters.nativescript Mandatory Adapts Expo Unimodules to NativeScript (and auto-installs the native modules for the above node module).

expo-contacts

 EXContacts expo.modules.contacts Mandatory Provides the Expo Contacts APIs.

unimodules-permissions-interface

 UMPermissionsInterface org.unimodules.interfaces.permissions Mandatory It's an interface that expo-contacts implements. Required for the app to build, even if you're not planning to use any permissions-related APIs.

unimodules-file-system-interface

 UMFileSystemInterface org.unimodules.interfaces.filesystem Mandatory It's an interface that expo-contacts implements. Required for the app to build, even if you're not planning to use any filesystem-related APIs.

expo-permissions

 EXPermissions expo.modules.permissions Optional If you don't have this installed, you'll get an error "Error: Permissions module not found. Are you sure that Expo modules are properly linked" at runtime when trying to use the APIs getPermissionsAsync() and requestPermissionsAsync().

@nativescript-community/expo-permissions-nativescript-plugin

 Same as above (this auto-installs the native modules for the above node module).

expo-file-system

 EXFileSystem expo.modules.filesystem Optional If you don't have this installed, you'll get an error "Error: FileSystem module not found. Are you sure that Expo modules are properly linked" at runtime when trying to use the API writeContactToFileAsync().

@nativescript-community/expo-file-system-nativescript-plugin

 Same as above (this auto-installs the native modules for the above node module).

Status

See Contacts in the Expo SDK API docs for full documentation.

API

Support

Comments

iOS

Android

createGroupAsync()

 🥈 🥈 Unlike the corresponding Expo method, in this implementation, the name param is not optional; this is because the uuidv4 library doesn't work out-of-the-box in NativeScript. I've left it up to the consumer to provide their own unique name.

writeContactToFileAsync()

 🚫 🚫 The method is implemented, but we haven't ported expo-file-system to NativeScript yet, so this will fail at runtime in practice.

shareContactAsync()

 🚫 ✅ On iOS, this requires writing to the file system. The method is implemented, but we haven't ported expo-file-system to NativeScript yet, so this will fail at runtime on iOS in practice.

Everything else

 ✅ ✅ Implemented exactly as in Expo! Note that Android support is pending implementation of expo-nativescript-adapter.

Usage

Again, see Contacts in the Expo SDK API docs for full documentation.

In practice, you'll probably need to request permissions to access contacts before using just about any of the Contacts APIs; so you should probably start off by calling getPermissionsAsync() or requestPermissionsAsync(); these APIs, as noted above, require both expo-permissions and @nativescript-community/expo-permissions-nativescript-plugin to be installed.

License

MIT