Um seletor de contatos para a Web

A API Contact Picker oferece uma maneira fácil para os usuários compartilharem contatos a partir de suas listas de contatos.

Pete LePage

O que é a API Contact Picker?

Como usar a API Contact Picker

A API Contact Picker exige uma chamada de método com um parâmetro de opções que especifica os tipos de informações de contato que você quer. Um segundo método informa quais informações o sistema 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, o seletor de contatos exige o Android M ou mais recente.

Como abrir o seletor de contatos

O ponto de entrada da API Contact Picker é navigator.contacts.select(). Quando chamado, ele retorna uma promessa e mostra o seletor de contatos, permitindo que o usuário selecione os contatos que ele quer compartilhar com o site. Depois de selecionar o que 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 (os valores permitidos são 'name', 'email', 'tel', 'address' ou 'icon') e, opcionalmente, se vários contatos podem ser selecionados 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.
}

A API Contacts Picker só pode ser chamada de um contexto de navegação de nível superior seguro. 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(). Ele 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 novas propriedades podem ser adicionadas. No futuro, outras plataformas e origens de contato poderão restringir quais propriedades serã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 para a propriedade solicitada ou se o usuário optar por não compartilhar uma propriedade específica, a API vai retornar uma matriz vazia. Descrevemos como o usuário escolhe 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, forneça dois números de telefone, mas não tenha um endereço de e-mail, a resposta 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 principais definidos em Como controlar o acesso a recursos poderosos da plataforma da Web, incluindo controle do usuário, transparência e ergonomia. Vou explicar cada uma delas.

Controle do usuário

O acesso aos contatos dos usuários é feito pelo seletor e só pode ser chamado com um gesto do usuário, em um contexto de navegação de nível superior seguro. Isso garante que um site não mostre o seletor ao carregar a página ou mostre o seletor aleatoriamente sem nenhum contexto.

Não há uma opção para 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 de todas as propriedades que o site pediu. Por exemplo, se um site solicitar name, email e tel, 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.

Um toque longo em um contato mostra todas as informações que serão compartilhadas se o contato for selecionado. (Consulte a imagem do contato do Cheshire Cat.)

Sem persistência de permissão

O acesso aos contatos é sob demanda e não é mantido. Sempre que um site quiser acesso, 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.

Tem problemas com a implementação?

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

• 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 Components como Blink>Contacts. O Glitch é ótimo para compartilhar reproduções rápidas e fáceis de problemas.

Planeja usar a API?

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

• Compartilhe como você planeja usá-lo na discussão do Discourse do WICG.
• Envie um tweet para @ChromiumDev usando a hashtag #ContactPicker e nos informe onde e como você está usando.

Links úteis

• Explicação para o público
• Especificação do seletor de contatos
• Demonstração da API Contact Picker e Fonte da demonstração da API Contact Picker
• Rastreamento de bug
• Entrada de ChromeStatus.com
• Componente do Blink: Blink>Contacts

Obrigado

Agradecimentos especiais a Finnur Thorarinsson e Rayan Kanso, que estão implementando o recurso, e a Peter Beverloo, cujo código eu roubei e refatorei para a demonstração.

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