Um seletor de contatos para a Web

A API Contact Picker oferece uma maneira fácil para os usuários compartilharem contatos da sua lista de contatos.

O que é a API Contact Picker?

O acesso aos contatos do usuário em um dispositivo móvel é um recurso dos apps iOS/Android desde (quase) o surgimento dos tempos. É uma das solicitações de recurso mais comuns que recebo de desenvolvedores da Web e costuma ser o principal motivo para eles criarem um app iOS/Android.

Disponível no Chrome 80 no Android M ou em versões mais recentes, a especificação da API Contact Picker é uma API sob demanda que permite que os usuários selecionem entradas da lista de contatos e compartilhem detalhes limitados das entradas selecionadas com um site. Ele permite que os usuários compartilhem apenas o que querem, quando querem, e facilita o contato e a conexão com amigos e familiares.

Por exemplo, um cliente de e-mail baseado na Web pode usar a API Contact Picker para selecionar os destinatários de um e-mail. Um app de narração sobre IP pode procurar para qual número de telefone ligar. Ou uma rede social pode ajudar um usuário a descobrir quais amigos já estão participando.

Como usar a API Contact Picker

A API Contact Picker requer uma chamada de método com um parâmetro de opções que especifica os tipos de dados de contato que você quer. Um segundo método informa quais informações o sistema subjacente vai fornecer.

Detecção de recursos

Para verificar se a API Contact Picker é compatível, use:

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

Além disso, no Android, é necessário ter o Android M ou versões mais recentes para usar o seletor de contatos.

Como abrir o seletor de contatos

O ponto de entrada para a API Contact Picker é navigator.contacts.select(). Quando chamado, ele retorna uma promessa e mostra o seletor de contatos, permitindo que o usuário escolha os contatos que quer compartilhar com o site. Depois de selecionar o que você quer compartilhar e clicar em Done, a promessa é resolvida com uma matriz de contatos selecionados pelo usuário.

Ao chamar select(), é necessário fornecer uma matriz de propriedades que você quer retornar como o primeiro parâmetro (com os valores permitidos sendo qualquer um de 'name', 'email', 'tel', 'address' ou 'icon') e, opcionalmente, se vários contatos podem ser selecionados como um 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.
}

A API Contact Picker só pode ser chamada de um contexto de navegação seguro de nível superior e, como outras APIs avançadas, ela exige um gesto do usuário.

Como detectar propriedades disponíveis

Para detectar quais propriedades estão disponíveis, chame navigator.contacts.getProperties(). Ela retorna uma promessa que é resolvida com uma matriz de strings indicando quais propriedades estão disponíveis. Por exemplo, ['name', 'email', 'tel', 'address']. É possível transmitir esses valores para select().

Lembre-se de que as propriedades nem sempre estão disponíveis e podem ser adicionadas novas propriedades. No futuro, outras plataformas e origens de contato poderão restringir quais propriedades são compartilhadas.

Como processar os resultados

A API Contact Picker retorna uma matriz de contatos, e cada contato inclui uma matriz das propriedades solicitadas. Se um contato não tiver dados da propriedade solicitada ou se o usuário desativar o compartilhamento de uma propriedade específica, a API vai retornar uma matriz vazia. Descreva como o usuário escolhe as propriedades na seção Controle do usuário.

Por exemplo, se um site solicitar name, email e tel, e um usuário selecionar um único contato que tenha dados no campo de nome, fornecer dois números de telefone, mas não tiver um endereço de e-mail, a resposta retornada será:

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

Segurança e permissões

A equipe do Chrome projetou e implementou a API Contact Picker usando os princípios básicos definidos em Como controlar o acesso a recursos avançados da plataforma da Web, incluindo controle do usuário, transparência e ergonomia. Vou explicar cada uma.

Controle do usuário

O acesso aos contatos dos usuários é feito pelo seletor e ele só pode ser chamado com um gesto do usuário, em um contexto de navegação seguro de nível superior. Isso garante que um site não possa mostrar o seletor no carregamento de página ou mostrá-lo aleatoriamente sem contexto.

Captura de tela, os usuários podem escolher quais propriedades querem compartilhar.
Os usuários podem optar por não compartilhar algumas propriedades. Nesta captura de tela, o usuário desmarcou o botão "Números de telefone". Mesmo que o site tenha solicitado números de telefone, eles não serão compartilhados com o site.

Não há a opção de selecionar todos os contatos em massa para que os usuários sejam incentivados a selecionar apenas os contatos que precisam compartilhar para esse site específico. Os usuários também podem controlar quais propriedades são compartilhadas com o site alternando o botão de propriedade na parte de cima do seletor.

Transparência

Para esclarecer quais detalhes de contato estão sendo compartilhados, o seletor sempre mostra o nome e o ícone do contato, além das propriedades solicitadas pelo site. Por exemplo, se um site solicitar name, email e tel, todas as três propriedades serão mostradas no seletor. Como alternativa, se um site solicitar apenas tel, o seletor vai mostrar apenas o nome e os números de telefone.

Captura de tela do seletor de um site que solicita todas as propriedades.
Seletor, site que solicita name, email e tel, um contato selecionado.
Captura de tela do seletor de um site que solicita apenas números de telefone.
Seletor, site que solicita apenas tel, um contato selecionado.
Captura de tela do seletor quando um contato é pressionado.
Resultado de tocar em um contato e mantê-lo pressionado.

Tocar e manter pressionado um contato mostrará todas as informações que serão compartilhadas se o contato for selecionado. Veja a imagem do contato "Gato de Cheshire".

Sem persistência de permissão

O acesso aos contatos é feito sob demanda e não é permanente. Sempre que um site quiser acessar, ele precisará chamar navigator.contacts.select() com um gesto do usuário, e o usuário precisará escolher individualmente os contatos que quer compartilhar com o site.

Feedback

A equipe do Chrome quer saber mais sobre suas experiências com a API Contact Picker.

Problemas com a implementação?

Você encontrou um bug na implementação do Chrome? Ou a implementação é diferente da especificação?

  • Registre um bug em https://new.crbug.com. Inclua o máximo de detalhes possível, forneça instruções simples para reproduzir o bug e defina Componentes como Blink>Contacts. O Glitch funciona muito bem para compartilhar reproduções de problemas rápidas e fáceis.

Pretende usar a API?

Você planeja usar a API Contact Picker? Seu suporte público ajuda a equipe do Chrome a priorizar recursos e mostra a outros fornecedores de navegador como é importante oferecer suporte a eles.

Links úteis

Até logo!

Agradecemos a Finnur Thorarinsson e Rayan Kanso, que estão implementando o recurso, e a Peter Beverloo, cujo código roubou e refatorou para a demonstração.

Observação: os nomes no meu seletor de contatos são caracteres da Alice no País das Maravilhas.