Um seletor de contatos para a Web

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

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 dados de contato desejados. 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.

Abrir a seleção 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 quer compartilhar com o site. Depois de selecionar o que compartilhar e clicar em Concluído, a promessa é resolvida com uma matriz de contatos selecionados pelo usuário.

Ao chamar select(), você precisa fornecer uma matriz de propriedades que 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 Contacts Picker só pode ser chamada de um contexto de navegação de nível superior seguro e, como outras APIs avançadas, exige um gesto do usuário.

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().

As propriedades nem sempre estão disponíveis, e novas propriedades podem ser adicionadas. No futuro, outras plataformas e fontes 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 desativar o compartilhamento de uma propriedade específica, a API vai retornar uma matriz vazia. Descrevo 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, 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 Controlling Access to Powerful Web Platform Features, 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, que 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 possa mostrar o seletor no carregamento da página ou aleatoriamente sem contexto.

Não há opção de selecionar todos os contatos de uma vez. Assim, os usuários são incentivados a selecionar apenas os contatos que precisam compartilhar para aquele site específico. Os usuários também podem controlar quais propriedades são compartilhadas com o site ao ativar 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 solicitou. 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.

Ao pressionar um contato por muito tempo, todas as informações que serão compartilhadas se ele for selecionado vão aparecer. (Consulte a imagem do contato do Gato de Cheshire.)

Sem persistência de permissão

O acesso aos contatos é sob demanda e não é permanente. Cada vez 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 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.

Você 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 a importância de oferecer suporte a eles.

• Compartilhe como você planeja usar esse recurso na thread do WICG Discourse (em inglês).
• Envie um tweet para @ChromiumDev usando a hashtag #ContactPicker e conte para nós 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
• Bug de rastreamento
• Entrada do ChromeStatus.com
• Componente Blink: Blink>Contacts

Obrigado

Um grande agradecimento a Finnur Thorarinsson e Rayan Kanso, que estão implementando o recurso, e a Peter Beverloo, cujo código eu roubei sem vergonha e refatorei para a demonstração.

PS: Os nomes no seletor de contatos são personagens de Alice no País das Maravilhas.