expo-contacts-nativescript-plugin

@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