@capacitor-community/contacts
    TypeScript icon, indicating that this package has built-in type declarations

    1.1.3 • Public • Published


    Contacts

    @capacitor-community/contacts

    Capacitor community plugin for fetching contacts.


    Maintainers

    Maintainer GitHub Social Sponsoring Company
    Jonathan Gerber / Byrds & Bytes GmbH idrimi / Byrds & Bytes GmbH byrds.ch Byrds & Bytes GmbH

    Maintenance Status: Actively Maintained

    Demo

    You can find a working Ionic App using the Byrds' Capacitor Contacts plugin here: https://github.com/byrdsandbytes/capContactsDemo/tree/capacitor-community

    Prerequisites

    Setup your project with Capacitor. For details check here: https://capacitorjs.com

    cd my-app
    npm install --save @capacitor/core @capacitor/cli
    

    Initialize Capacitor

    npx cap init
    

    Add the platforms you want to use.

    npx cap add android
    npx cap add ios
    npx cap add electron
    

    Installation

    Install:

    npm i --save @capacitor-community/contacts
    

    Sync:

    npx cap sync
    

    iOS

    For iOS you need to set a usage description in your info.plist file. (Privacy Setting) Open xCode search for your info.plist file and press the tiny "+". Add the following entry:

    Privacy - Contacts Usage Description
    

    Give it a value like:

    "We need access to your contacts in order to do something."
    

    Android Notes

    For Android you have to add the permissions in your AndroidManifest.xml. Add the following permissions before the closing of the "manifest" tag.

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

    Next import the capContacts class to your MainActivity

    // Initializes the Bridge
        this.init(savedInstanceState, new ArrayList<Class<? extends Plugin>>() {{
          // Additional plugins you've installed go here
          // Ex: add(TotallyAwesomePlugin.class);
          add(Contacts.class);
        }});
    

    Make sure to import it properly as well.

    import ch.byrds.capacitor.contacts.Contacts;
    

    NOTE: On Android you have to ask for permission first, before you can fetch the contacts. Use the getPermissions() method before you try to fetch contacts using getContacts().

    Usage / Examples

    You have the following Methods available:

    export interface ContactsPlugin {
      getPermissions(): Promise<PermissionStatus>;
      getContacts(): Promise<{contacts: Contact[]}>;
    }
    

    If you're considering to use this plugin you most likely want to retrieve contacts a users contacts:

    Import the Plugin in your TS file:

    import { Contacts } from '@capacitor-community/contacts'
    

    Next use it and console log the result:

    Contacts.getContacts().then(result => {
        console.log(result);
        for (const contact of result.contacts) {
            console.log(contact);
        }
    });
    
    

    That's it. Do Whatever you want with the retrieved contacts.

    If you're trying to build something like "contacts matching" based on phone numbers i recommend using google libphonenumber: https://www.npmjs.com/package/google-libphonenumber

    In order to match them properly you need to format them before you can match or store them properly.

    Interfaces

    export interface PermissionStatus {
      granted: boolean;
    }
    
    export interface Contact {
      contactId: string;
      displayName?: string;
      phoneNumbers: PhoneNumber[];
      emails: EmailAddress[];
      photoThumbnail?: string;
      organizationName?: string;
      organizationRole?: string;
      birthday?: string;
    }
    
    export interface PhoneNumber {
      label?: string;
      number?: string;
    }
    
    export interface EmailAddress {
      label?: string;
      address?: string;
    }
    

    Built With

    • Swift 5
    • Java
    • Angular
    • Capacitor

    Authors

    License

    MIT

    Contributors


    idrimi

    💻

    Tafel

    💻

    Max Lynch

    📖 📋

    David Javier Garzon Carrillo

    💻

    Vladimir Hinić

    💻

    reslear

    📖

    Marvin Heilemann

    💻 📖

    API

    getPermissions()

    getPermissions() => any

    Returns: any


    getContacts()

    getContacts() => any

    Returns: any


    saveContact(...)

    saveContact(contact: NewContact) => any
    Param Type
    contact NewContact

    Returns: any


    Interfaces

    PermissionStatus

    Prop Type
    granted boolean

    Contact

    Prop Type
    contactId string
    displayName string
    phoneNumbers {}
    emails {}
    photoThumbnail string
    organizationName string
    organizationRole string
    birthday string

    PhoneNumber

    Prop Type
    label string
    number string

    EmailAddress

    Prop Type
    label string
    address string

    NewContact

    New contact schema.

    Prop Type Description
    contactType ContactType
    namePrefix string
    givenName string
    middleName string
    familyName string
    nameSuffix string
    nickname string
    jobTitle string
    departmentName string
    organizationName string
    postalAddresses {}
    emailAddresses {}
    urlAddresses {}
    phoneNumbers {}
    birthday string
    note string
    socialProfiles {}
    image string Base64 image

    PostalAddress

    Prop Type
    label string
    address { street?: string; city?: string; state?: string; postalCode?: string; country?: string; }

    UrlAddress

    Prop Type
    label string
    url string

    SocialProfile

    Prop Type
    label string
    profile { username?: string; service?: string; urlString?: string; }

    Enums

    ContactType

    Members
    Person
    Organization

    Install

    npm i @capacitor-community/contacts

    DownloadsWeekly Downloads

    2,132

    Version

    1.1.3

    License

    MIT

    Unpacked Size

    74.5 kB

    Total Files

    27

    Last publish

    Collaborators

    • tafelnl
    • thegnuu
    • pbowyer
    • capcombot
    • jcesarmobile
    • maxlynch
    • mhartington
    • dotnetkow
    • it_mike_s
    • byrds
    • rdlabo
    • priyankpatel
    • dwieeb
    • stewan
    • arielhernandezmusa
    • jeepq
    • start9keagan
    • boosten
    • nklayman
    • ihadeed
    • danielprr
    • ckgaparajita
    • jpender
    • nhyatt
    • pwespi
    • epicshaggy
    • thomasvidas
    • robingenz
    • diachedelic
    • johnborges
    • tobyas
    • elylucas
    • larsmikkelsen
    • giodimiliaionic
    • brownoxford
    • mrbatista
    • bazuka5801
    • hemang