Contact Blob Writer

The Contact Blob Writer provides an interface for developers to create contact objects from Javascript.

Contact objects can then be saved to the user's current device via the APIs and mechanisms defined in [[!FILE-API]] and shown in this specification.

This specification is built on top of an accompanying specification [[CONTACTS-API]] that enables read access to a user's unified address book.

This document represents the early consensus of the group on the scope and features of the proposed Contact Blob Writer specification. Issues and editors note in the document highlight some of the points on which the group is still working and would particularly like to get feedback.

This specification defines conformance criteria that apply to a single product: the user agent that implements the interfaces that it contains.

Implementations that use ECMAScript to implement the APIs defined in this specification must implement them in a manner consistent with the ECMAScript Bindings defined in the Web IDL specification [[!WEBIDL]], as this specification uses that specification and terminology.

Introduction

This specification provides a method for creating objects consisting of standard contact card information such as names, addresses and phone numbers so that these objects may be efficiently stored and saved on a user's device.

The interfaces and API defined in this specification have been built on top of [[!FILE-API]]. Contact Blobs can be presented, downloaded and stored on the user's device by creating a Blob URI [[!FILE-API]] from a created Contact Blob object. This Blob URI may be presented to the user or invoked wherever URLs can be used within the web platform.

The API is designed so that implementors of this specification are not required to implement a handler for valid Contact Blob Types. The valid Contact Blob Types contained herein have been chosen for their ability to integrate with existing and legacy address book systems while still allowing user agents to handle the given media types as required.

Security and Privacy Considerations

This specification builds upon the security and privacy protections provided by the [[HTML5]] and [[!FILE-API]] specifications; in particular, it is expected that any action to download the Contact information that has been created would require a specific user interaction on an HTML element that is entirely controlled by the user agent.

Contact Blob API

Example

The following example illustrates how to create a Contact Blob, create a Blob URI and then a mechanism for saving the Contact object on the host device:

<a id="contactcard">Save our business card</a>

<script type="text/javascript"> 
  // Define/Get some contact properties:
  var contact = {
    displayName: 'Robert',
    emails: [
      {
        value: 'bob@foo.com'
      }
    ]
    // ...
  };

  // Create a new Contact Blob:
  var contactBlob = navigator.service.contacts.createContactBlob(contact);
  
  // Create a Blob URI object:
  // @see http://www.w3.org/TR/file-upload/#dfn-createObjectURL
  var contactURL = createObjectURL(contactBlob);
  
  // e.g. Assign contact URI to anchor element for user-initiated download: 
  document.getElementById('contactcard').href = contactURL;
</script>