Contacts

  • Revision slug: WebAPI/Contacts
  • Revision title: Contacts
  • Revision id: 378989
  • Created:
  • Creator: Jeremie
  • Is current revision? No
  • Comment

Revision Content

{{ draft }}

{{ SeeCompatTable }}

{{ B2GOnlyHeader2('privileged') }}

Summary

The Contacts API provides a simple interface to manage user's contacts stored in the system's address book. A typical use case of the Contacts API is the implementation of an application to manage said address book.

Note: Because personnal information regarding a user's contact are pieces of sensitive data, only privileged and certified apps are allow to directly access that API. Other applications are encouraged to use Web Activities to delegate operations on contacts.

Managing contacts

Contacts stored in the system's address book are accessible through the {{domxref("window.navigator.mozContacts","navigator.mozContacts")}} property, which is itself an instance of the {{domxref("ContactManager")}} interface.

Adding a contact

Creating a new entry in the system's adress book is made in two steps:

  1. Instentiate a new {{domxref("Contact")}} object and field all its necessary properties. The {{domxref("Contact")}} interface extend the {{domxref("ContactProperties")}} interface that defines all the possible properties for a given contact. Those properties are mostly the same as the ones define in the vCard 4.0 specification, with the following exception :
    • The vCard's N attribute is splite in 5 properties: {{domxref("ContactProperties.familyName","familyName")}}, {{domxref("ContactProperties.givenName","givenName")}}, {{domxref("ContactProperties.additionalName","additionalName")}}, {{domxref("ContactProperties.honorificPrefix","honorificPrefix")}}, {{domxref("ContactProperties.honorificSuffix","honorificSuffix")}}
    • The vCard's FN attribute is actully renamed {{domxref("ContactProperties.name","name")}}
    • The vCard's GENDER attribute issplit in 2 properties: {{domxref("ContactProperties.sex","sex")}}, {{domxref("ContactProperties.genderIdentity","genderIdentity")}}
  2. Use the {{domxref("ContactManager.save()")}} method with the contact object as its first parameter.
var person = new Contact();
person.name = "John Doe"
person.nickName = "No kiding"

navigator.mozContacts.save(person);

Finding a contact

Removing a contact

Specifications

Specification Status Comment
{{ SpecName('Contacts', '', 'Contacts Manager API') }} {{ Spec2('Contacts') }} Initial specification
vCard Format Specification RFC RFC6350

Browser compatibility

{{ CompatibilityTable() }}

Feature Chrome Firefox (Gecko) Internet Explorer Opera Safari
basic support {{CompatNo()}} {{CompatNo()}} {{CompatNo()}} {{CompatNo()}} {{CompatNo()}}
Feature Android Chrome for Android Firefox Mobile (Gecko) IE Mobile Opera Mobile Safari Mobile
basic support {{CompatNo()}} {{CompatNo()}} {{CompatVersionUnknown()}} {{CompatNo()}} {{CompatNo()}} {{CompatNo()}}

See also

  • {{domxref("window.navigator.mozContacts","navigator.mozContacts")}}
  • {{domxref("Contact")}}
  • {{domxref("ContactAddress")}}
  • {{domxref("ContactField")}}
  • {{domxref("ContactFindOption")}}
  • {{domxref("ContactFindSortOption")}}
  • {{domxref("ContactManager")}}
  • {{domxref("ContactProperties")}}
  • {{domxref("ContactTelField")}}

 

Revision Source

<p>{{ draft }}</p>
<p>{{ SeeCompatTable }}</p>
<p>{{ B2GOnlyHeader2('privileged') }}</p>
<h2 id="Summary">Summary</h2>
<p>The Contacts API provides a simple interface to manage user's contacts stored in the system's address book. A typical use case of the Contacts API is the implementation of an application to manage said address book.</p>
<div class="note">
  <p><strong>Note:</strong> Because personnal information regarding a user's contact are pieces of sensitive data, only privileged and certified apps are allow to directly access that API. Other applications are encouraged to use <a href="/en-US/docs/WebAPI/Web_Activities" title="/en-US/docs/WebAPI/Web_Activities">Web Activities</a> to delegate operations on contacts.</p>
</div>
<h2>Managing contacts</h2>
<p>Contacts stored in the system's address book are accessible through the {{domxref("window.navigator.mozContacts","navigator.mozContacts")}} property, which is itself an instance of the {{domxref("ContactManager")}} interface.</p>
<h3>Adding a contact</h3>
<p>Creating a new entry in the system's adress book is made in two steps:</p>
<ol>
  <li>Instentiate a new {{domxref("Contact")}} object and field all its necessary properties. The {{domxref("Contact")}} interface extend the {{domxref("ContactProperties")}} interface that defines all the possible properties for a given contact. Those properties are mostly the same as the ones define in the vCard 4.0 specification, with the following exception :
    <ul>
      <li>The vCard's N attribute is splite in 5 properties: {{domxref("ContactProperties.familyName","familyName")}}, {{domxref("ContactProperties.givenName","givenName")}}, {{domxref("ContactProperties.additionalName","additionalName")}}, {{domxref("ContactProperties.honorificPrefix","honorificPrefix")}}, {{domxref("ContactProperties.honorificSuffix","honorificSuffix")}}</li>
      <li>The vCard's FN attribute is actully renamed {{domxref("ContactProperties.name","name")}}</li>
      <li>The vCard's GENDER attribute issplit in 2 properties: {{domxref("ContactProperties.sex","sex")}}, {{domxref("ContactProperties.genderIdentity","genderIdentity")}}</li>
    </ul>
  </li>
  <li>Use the {{domxref("ContactManager.save()")}} method with the contact object as its first parameter.</li>
</ol>
<pre class="brush: js">
var person = new Contact();
person.name = "John Doe"
person.nickName = "No kiding"

navigator.mozContacts.save(person);
</pre>
<h3>Finding a contact</h3>
<h3>Removing a contact</h3>
<h2 id="Specifications" name="Specifications">Specifications</h2>
<table class="standard-table" height="49" width="1000">
  <thead>
    <tr>
      <th scope="col">Specification</th>
      <th scope="col">Status</th>
      <th scope="col">Comment</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>{{ SpecName('Contacts', '', 'Contacts Manager API') }}</td>
      <td>{{ Spec2('Contacts') }}</td>
      <td>Initial specification</td>
    </tr>
    <tr>
      <td><a href="http://tools.ietf.org/html/rfc6350" title="http://tools.ietf.org/html/rfc6350">vCard Format Specification</a></td>
      <td>RFC</td>
      <td><code>RFC6350</code></td>
    </tr>
  </tbody>
</table>
<h2 id="Browser_compatibility">Browser compatibility</h2>
<p>{{ CompatibilityTable() }}</p>
<div id="compat-desktop">
  <table class="compat-table">
    <tbody>
      <tr>
        <th>Feature</th>
        <th>Chrome</th>
        <th>Firefox (Gecko)</th>
        <th>Internet Explorer</th>
        <th>Opera</th>
        <th>Safari</th>
      </tr>
      <tr>
        <td>basic support</td>
        <td>{{CompatNo()}}</td>
        <td>{{CompatNo()}}</td>
        <td>{{CompatNo()}}</td>
        <td>{{CompatNo()}}</td>
        <td>{{CompatNo()}}</td>
      </tr>
    </tbody>
  </table>
</div>
<div id="compat-mobile">
  <table class="compat-table">
    <tbody>
      <tr>
        <th>Feature</th>
        <th>Android</th>
        <th>Chrome for Android</th>
        <th>Firefox Mobile (Gecko)</th>
        <th>IE Mobile</th>
        <th>Opera Mobile</th>
        <th>Safari Mobile</th>
      </tr>
      <tr>
        <td>basic support</td>
        <td>{{CompatNo()}}</td>
        <td>{{CompatNo()}}</td>
        <td>{{CompatVersionUnknown()}}</td>
        <td>{{CompatNo()}}</td>
        <td>{{CompatNo()}}</td>
        <td>{{CompatNo()}}</td>
      </tr>
    </tbody>
  </table>
</div>
<h2 id="See_also">See also</h2>
<ul>
  <li>{{domxref("window.navigator.mozContacts","navigator.mozContacts")}}</li>
  <li>{{domxref("Contact")}}</li>
  <li>{{domxref("ContactAddress")}}</li>
  <li>{{domxref("ContactField")}}</li>
  <li>{{domxref("ContactFindOption")}}</li>
  <li>{{domxref("ContactFindSortOption")}}</li>
  <li>{{domxref("ContactManager")}}</li>
  <li>{{domxref("ContactProperties")}}</li>
  <li>{{domxref("ContactTelField")}}</li>
</ul>
<p>&nbsp;</p>
Revert to this revision