Um seletor de contatos para a web

# O que é a API Contact Picker?

O acesso aos contatos do usuário em um dispositivo móvel é um recurso dos aplicativos iOS/Android desde (quase) o início dos tempos. É uma das solicitações de recursos mais comuns que ouço de desenvolvedores web e geralmente é o principal motivo para eles criarem um aplicativo iOS/Android.

Disponível no Chrome 80 no Android, a API Contact Picker é uma API sob demanda que permite aos usuários selecionar entradas de sua lista de contatos e compartilhar detalhes limitados das entradas selecionadas com um site. Ela permite que os usuários compartilhem apenas o que desejam, quando desejam, e torna mais fácil para os usuários entrarem em contato e se conectarem com seus amigos e familiares.

Por exemplo, um cliente de email baseado na web pode usar a API Contact Picker para selecionar o(s) destinatário(s) de um email. Um aplicativo de voz sobre IP pode pesquisar para qual número de telefone ligar. Ou uma rede social pode ajudar um usuário a descobrir quais amigos já aderiram.

# Status atual

# Usando a API Contact Picker

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

# Detecção de recursos

Para verificar se a API Contact Picker é suportada, use:

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

Além disso, no Android, o Contact Picker requer Android M ou posterior.

# Abrindo o Contact Picker

O ponto de entrada para a API Contact Picker é o método navigator.contacts.select(). Quando chamado, ele retorna uma promessa e mostra o seletor de contato, permitindo ao usuário selecionar o(s) contato(s) que deseja compartilhar com o site. Depois de selecionar o que compartilhar e clicar em Concluído, a promessa é resolvida com uma série de contatos selecionados pelo usuário.

Ao chamar select() você precisa fornecer uma matriz de propriedades que gostaria de retornar como primeiro parâmetro (com os valores permitidos sendo qualquer um dentre 'name', 'email' , 'tel', 'address' ou 'icon') e, opcionalmente, se múltiplos 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 a partir de um contexto de navegação de nível superior seguro e, como outras APIs poderosas, requer um gesto do usuário.

# Detectando propriedades disponíveis

Para detectar quais propriedades estão disponíveis, chame navigator.contacts.getProperties(). Ele retorna uma promessa que é resolvida com um array de strings que indica quais propriedades estão disponíveis. Por exemplo: ['name', 'email', 'tel', 'address']. Você pode passar 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 fontes de contato podem restringir quais propriedades serão compartilhadas.

# Lidando com os resultados

A API Contact Picker retorna um array de contatos e cada contato inclui um array 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 retornará um array vazio. (Eu descreverei 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 name, 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 Controle de acesso a recursos poderosos da plataforma da Web, incluindo controle do usuário, transparência e ergonomia. Vou explicar cada um a seguir.

# Controle do usuário

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

Não há opção de selecionar em massa todos os contatos, de modo que 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, alternando o botão de propriedade na parte superior 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 quaisquer propriedades que o site tenha solicitado. Por exemplo, se um site solicitar name, email e tel, todas as três propriedades serão mostradas no seletor. Alternativamente, se um site solicitar apenas tel, o selecionador mostrará apenas o nome e os números de telefone.

Um toque demorado sobre um contato mostrará todas as informações que serão compartilhadas se o contato for selecionado. (Veja a imagem de contato do gato Cheshire.)

# Sem persistência de permissões

O acesso aos contatos é sob demanda e não é persistente. Cada vez que um site quiser acesso, ele precisa chamar navigator.contacts.select() com um gesto do usuário, e o usuário deve escolher individualmente o(s) contato(s) que deseja 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. Não deixe de incluir o máximo de detalhes que puder, fornecer instruções simples para reproduzir o bug e definir Components como Blink>Contacts. O Glitch funciona muito bem para compartilhar reproduções rápidas e fáceis.

# Planejando usar a API?

Você está planejando usar a API Contact Picker? Seu apoio público ajuda a equipe do Chrome a priorizar os recursos e mostra a outros fornecedores de navegadores como o apoio é fundamental.

• Compartilhe como você planeja usá-la no tópico WICG Discourse.
• Envie um tweet para @ChromiumDev usando a hashtag #ContactPicker e diga-nos onde e como você está usando a API.

# Links úteis

• Explicador público
• Especificação do Contact Picker
• Demonstração da API Contact Picker e Código-fonte da demonstração da API Contact Picker
• Rastreamento de bug
• Entrada em ChromeStatus.com
• Blink Component: Blink>Contacts

# Agradecimentos

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

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