Contactos Plugin for Flutter

pub package codecov style: flutter lints

Description

A Flutter plugin to access and manage the device's contacts.

Installation

To use this plugin, add contactos as a dependency in your pubspec.yaml file. For example:

dependencies:
    contactos: ^1.0.0

Permissions

Android

Add the following permissions to your AndroidManifest.xml:

<uses-permission android:name="android.permission.READ_CONTACTS" />
<uses-permission android:name="android.permission.WRITE_CONTACTS" />

iOS

Set the NSContactsUsageDescription in your Info.plist file.

<key>NSContactsUsageDescription</key>
<string>This app requires contacts access to function properly.</string>

And add PermissionGroup.contacts in your Podfile

target.build_configurations.each do |config|
    config.build_settings
    ['GCC_PREPROCESSOR_DEFINITIONS'] ||= [
        '$(inherited)',

        ## dart: PermissionGroup.contacts
        'PERMISSION_CONTACTS=1',
    ]
end

Note contactos does not handle the process of asking and checking for permissions. To check and request user permission to access contacts, try using the following plugins: permission_handler.

If you do not request user permission or have it granted, the application will fail. For testing purposes, you can manually set the permissions for your test app in Settings for your app on the device that you are using. For Android, go to "Settings" - "Apps" - select your test app - "Permissions" - then turn "on" the slider for contacts.

Example

// Import package
import 'package:contactos/contactos.dart';

// Get all contacts on device.
List<Contact> contacts = await Contactos.instance.getContacts();

// Get all contacts without thumbnail (faster).
List<Contact> contacts = await Contactos.instance.getContacts(withThumbnails: false);

// Android only: Get thumbnail for an avatar afterwards (only necessary if `withThumbnails: false` is used).
Uint8List avatar = await Contactos.instance.getAvatar(contact);

// Get contacts matching a string.
List<Contact> johns = await Contactos.instance.getContacts(query : "john");

// Add a contact.
// The contact must have a firstName / lastName to be successfully added.
await Contactos.instance.addContact(newContact);

// Delete a contact.
// The contact must have a valid identifier.
await Contactos.instance.deleteContact(contact);

// Update a contact.
// The contact must have a valid identifier.
await Contactos.instance.updateContact(contact);

// Usage of the native device form for creating a Contact.
// Throws a error if the Form could not be open or the Operation is canceled by the User.
await Contactos.instance.openContactForm();

// Usage of the native device form for editing a Contact.
// The contact must have a valid identifier.
// Throws a error if the Form could not be open or the Operation is canceled by the User.
await Contactos.instance.openExistingContact(contact);

Contact Model

// Name
String displayName, givenName, middleName, prefix, suffix, familyName;

// Company
String company, jobTitle;

// Email addresses
List<Contact$Field> emails = [];

// Phone numbers
List<Contact$Field> phones = [];

// Post addresses
List<Contact$PostalAddress> postalAddresses = [];

// Contact avatar/thumbnail
Uint8List avatar;

Example

Changelog

Refer to the Changelog to get all release notes.

Maintainers

Anton Ustinoff (ziqq)

License

MIT

Contributions

Contributions are welcome! If you find a bug or want a feature, please fill an issue.

If you want to contribute code please create a pull request under the master branch.

Funding

If you want to support the development of our library, there are several ways you can do it:

Coverage

Libraries

contactos