flutter_contacts 0.3.0

Flutter plugin to read, create, update, delete and observe native contacts on Android and iOS, with vCard support

flutter_contacts

Flutter plugin to read, create, update, delete and observe native contacts on Android and iOS, with vCard support.

For a minimalistic example, take a look at example/. You can write a full-fledged contacts app with it – see example_full/ to see how.

Quick start

// See installation notes below regarding AndroidManifest.xml and Info.plist
import 'package:flutter_contacts/flutter_contacts.dart';

// Request contact permission
if (await FlutterContacts.requestPermission()) {
    // Get all contacts (lightly fetched)
    List<Contact> contacts = await FlutterContacts.getContacts();

    // Get all contacts (fully fetched)
    List<Contact> contacts = await FlutterContacts.getContacts(withProperties: true, withPhoto: true);

    // Get contact with specific ID (fully fetched)
    Contact contact = await FlutterContacts.getContact(contacts.first.id)

    // Insert new contact
    await Contact()
        ..name.first = 'John'
        ..name.last = 'Smith'
        ..phones = [Phone('555-123-4567')]
        ..insert();

    // Update contact
    contact.name.first = 'Bob';
    await contact.update();

    // Delete contact
    await contact.delete();

    // Listen to contact database changes
    FlutterContacts.addListener(() => print('Contact DB changed'));

    // Export contact to vCard
    String vCard = contact.toVCard();

    // Import contact from vCard
    Contact contact = Contact.fromVCard('BEGIN:VCARD\n'
        'VERSION:3.0\n'
        'N:;Joe;;;\n'
        'TEL;TYPE=HOME:123456\n'
        'END:VCARD');
}

Simplified contact model

See code for complete data model.

class Contact {
    String id;
    String displayName;
    Uint8List photo;
    Uint8List thumbnail;
    Name name;
    List<Phone> phones;
    List<Email> emails;
    List<Address> addresses;
    List<Organization> organizations;
    List<Website> websites;
    List<SocialMedia> socialMedias;
    List<Event> events;
    List<Note> notes;
}
class Name { String first; String last; }
class Phone { String number; PhoneLabel label; }
class Email { String address; EmailLabel label; }
class Address { String address; AddressLabel label; }
class Organization { String company; String title; }
class Website { String url; WebsiteLabel label; }
class SocialMedia { String userName; SocialMediaLabel label; }
class Event { int year; int month; int day; EventLabel label; }
class Note { String note; }

Demo

Installation

1. Add the following key/value pair to your app's Info.plist (for iOS):

   <plist version="1.0">
   <dict>
       ...
       <key>NSContactsUsageDescription</key>
       <string>Reason we need access to the contact list</string>
   </dict>
   </plist>
   

2. Add the following <uses-permissions> tags to your app's AndroidManifest.xml (for Android):

   <manifest xmlns:android="http://schemas.android.com/apk/res/android" ...>
       <uses-permission android:name="android.permission.READ_CONTACTS"/>
       <uses-permission android:name="android.permission.WRITE_CONTACTS"/>
       <application ...>
       ...
   

Notes

• On iOS13+ you can only access notes if your app is entitled by Apple so notes are disabled by default. If you get entitlement, enable them via

  FlutterContacts.config.includeNotesOnIos13AndAbove = true;
  

• On both iOS and Android there is a concept of raw and unified contacts. A single person might have two raw contacts (for example from Gmail and from iCloud) but will be merged into a single view called a unified contact. In a contact app you typically want unified contacts, so this is what's returned by default. You can get raw contacts instead via

  FlutterContacts.config.returnUnifiedContacts = false;
  

  However, for now, raw contacts cannot be inserted, updated or deleted.