Un selector de contactos para la Web

La API de Contact Picker proporciona una forma sencilla para que los usuarios compartan contactos de su lista de contactos.

¿Qué es la API de Contact Picker?

El acceso a los contactos del usuario en un dispositivo móvil ha sido una función de las apps para iOS y Android desde (casi) al principio. Es una de las solicitudes de funciones más comunes que recibimos de los desarrolladores web y, a menudo, es el motivo clave por el que compilan una app para iOS/Android.

Disponible a partir de Chrome 80 en Android M o versiones posteriores, la especificación de la API de Contact Picker es una API a pedido que permite a los usuarios seleccionar entradas de su lista de contactos y compartir detalles limitados de las entradas seleccionadas con un sitio web. Permite que los usuarios compartan solo lo que quieran y cuando quieran, además de que les permite comunicarse con sus amigos y familiares y comunicarse con ellos fácilmente.

Por ejemplo, un cliente de correo electrónico basado en la Web podría usar la API de Contact Picker para seleccionar los destinatarios de un correo electrónico. Una app de voz en off puede buscar a qué número de teléfono llamar. O bien, una red social podría ayudar a un usuario a descubrir qué amigos ya se unieron.

Usa la API de Contact Picker

La API de Contact Picker requiere una llamada de método con un parámetro de opciones que especifique los tipos de información de contacto que deseas. Un segundo método te indica qué información proporcionará el sistema subyacente.

Detección de atributos

Para verificar si la API de Contact Picker es compatible, usa lo siguiente:

const supported = ('contacts' in navigator && 'ContactsManager' in window);

Además, en Android, el selector de contactos requiere Android M o una versión posterior.

Cómo abrir el Selector de contactos

El punto de entrada a la API de Contact Picker es navigator.contacts.select(). Cuando se llama, muestra una promesa y el selector de contactos, lo que permite que el usuario elija los contactos que desea compartir con el sitio. Después de seleccionar qué compartir y hacer clic en Listo, la promesa se resuelve con un arreglo de contactos seleccionados por el usuario.

Cuando llames a select(), debes proporcionar un array de propiedades que quieres que se muestren como primer parámetro (los valores permitidos son 'name', 'email', 'tel', 'address' o 'icon') y, opcionalmente, si se pueden seleccionar varios contactos como segundo parámetro.

const props = ['name', 'email', 'tel', 'address', 'icon'];
const opts = {multiple: true};

try {
  const contacts = await navigator.contacts.select(props, opts);
  handleResults(contacts);
} catch (ex) {
  // Handle any errors here.
}

Solo se puede llamar a la API del selector de contactos desde un contexto de navegación seguro y de nivel superior y, al igual que otras API potentes, requiere un gesto del usuario.

Detecta las propiedades disponibles

Para detectar qué propiedades están disponibles, llama a navigator.contacts.getProperties(). Muestra una promesa que se resuelve con un arreglo de strings que indica qué propiedades están disponibles. Por ejemplo: ['name', 'email', 'tel', 'address']. Puedes pasar estos valores a select().

Recuerda que las propiedades no siempre están disponibles y que se pueden agregar propiedades nuevas. En el futuro, es posible que otras plataformas y fuentes de contacto restrinjan las propiedades que se comparten.

Controla los resultados

La API de Contact Picker muestra un arreglo de contactos, y cada contacto incluye un arreglo de las propiedades solicitadas. Si un contacto no tiene datos para la propiedad solicitada, o el usuario decide inhabilitar el uso compartido de una propiedad en particular, la API muestra un arreglo vacío. (Describo cómo el usuario elige propiedades en la sección Control de usuario).

Por ejemplo, si un sitio solicita name, email y tel, y un usuario selecciona un solo contacto que tiene datos en el campo de nombre, proporciona dos números de teléfono, pero no tiene dirección de correo electrónico, la respuesta que se muestra será la siguiente:

[{
  "email": [],
  "name": ["Queen O'Hearts"],
  "tel": ["+1-206-555-1000", "+1-206-555-1111"]
}]

Seguridad y permisos

El equipo de Chrome diseñó e implementó la API de Contact Picker según los principios básicos definidos en Cómo controlar el acceso a funciones potentes de la plataforma web, incluidos el control de usuario, la transparencia y la ergonomía. Vamos a explicar cada una de ellas.

Control de usuarios

El acceso a los contactos de los usuarios se realiza mediante el selector y solo se puede llamar con un gesto del usuario en un contexto de navegación seguro de nivel superior. Esto garantiza que un sitio no pueda mostrar el selector cuando se cargue la página, ni mostrarlo de forma aleatoria sin ningún contexto.

Captura de pantalla en la que los usuarios pueden elegir qué propiedades compartir.
Los usuarios pueden optar por no compartir algunas propiedades. En esta captura de pantalla, el usuario desmarcó el botón “Números de teléfono”. Si bien el sitio solicitó números de teléfono, no se compartirán con él.

No hay opción para seleccionar todos los contactos de forma masiva, de modo que se anime a los usuarios a seleccionar solo los contactos que deben compartir en ese sitio web en particular. Los usuarios también pueden controlar qué propiedades se comparten con el sitio activando o desactivando el botón de propiedad que se encuentra en la parte superior del selector.

Transparencia

Para aclarar qué detalles de contacto se comparten, el selector siempre muestra el nombre y el ícono del contacto, además de cualquier propiedad que el sitio haya solicitado. Por ejemplo, si un sitio solicita name, email y tel, las tres propiedades se mostrarán en el selector. De manera alternativa, si un sitio solo solicita tel, el selector solo mostrará el nombre y los números de teléfono.

Captura de pantalla del selector del sitio que solicita todas las propiedades.
Selector, sitio que solicita name, email y tel, un contacto seleccionado.
Captura de pantalla del selector para un sitio que solicita solo números de teléfono.
Selector, sitio que solicita solo tel, un contacto seleccionado.
Captura de pantalla del selector cuando se mantiene presionado un contacto.
Resultado de mantener presionado un contacto

Si mantienes presionado un contacto, se mostrará toda la información que se compartirá si se lo selecciona. (Consulta la imagen de contacto del gato de Cheshire).

Sin persistencia de permisos

El acceso a los contactos es a pedido y no persistente. Cada vez que un sitio quiera acceder, deberá llamar a navigator.contacts.select() con un gesto del usuario, y este deberá elegir individualmente los contactos que quiera compartir con el sitio.

Comentarios

El equipo de Chrome quiere conocer tu experiencia con la API de Contact Picker.

¿Tienes problemas con la implementación?

¿Encontraste un error en la implementación de Chrome? ¿La implementación es diferente de las especificaciones?

  • Informa el error en https://new.crbug.com. Asegúrate de incluir todos los detalles que puedas, proporciona instrucciones simples para reproducir el error y configura los componentes como Blink>Contacts. Glitch funciona muy bien para compartir reproducciones de problemas rápidas y fáciles.

¿Piensas usar la API?

¿Planeas usar la API de Contact Picker? Tu asistencia pública ayuda al equipo de Chrome a priorizar funciones y muestra a otros proveedores de navegadores la importancia de admitirlas.

Vínculos útiles

Gracias

Gracias a Finnur Thorarinsson y Rayan Kanso, que están implementando la función, y a Peter Beverloo, cuyo código robé y refactoriza sin desvergadura para la demostración.

P. D.: Los nombres que aparecen en el selector de contactos son caracteres de Alicia en el país de las maravillas.