Telefone em fundo amarelo.

Um seletor de contatos para a web

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

Published on Updated on

Translated to: English, 한국어, 中文, Pусский, 日本語

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.

Caution

A equipe do Chrome pensou muito no design e na implementação da API Contact Picker para garantir que o navegador só compartilhe exatamente o que as pessoas escolhem. Consulte a seção Segurança e privacidade abaixo.

Status atual

PassoStatus
1. Criar um explicadorConcluído
2. Criar o rascunho inicial das especificaçõesConcluído
3. Obter feedback e repetir o designConcluído
4. Prova de origemConcluído
5. LançamentoChrome 80
Disponível apenas no Android.

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.
}
Caution

O suporte a 'address' e 'icon' requer Chrome 84 ou posterior.

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"]
}]
Caution

Descrições e outras informações semânticas nos campos de contato são eliminadas.

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.

Captura de tela, os usuários podem escolher quais propriedades 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 solicite números de telefone, eles não serão compartilhados com o site.

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.

Captura de tela do seletor solicitando todas as propriedades.
Seletor (Picker), solicitando ao site as propriedades name, email e tel, um contato selecionado.
Captura de tela do seletor para site requisitando apenas números de telefone.
Seletor (picker) solicitando ao site apenas a propriedade tel, um contato selecionado.
Captura de tela do seletor quando um contato é selecionado com um toque demorado.
Resultado de um toque demorado sobre um contato.

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.

Links úteis

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.

Updated on Improve article

We serve cookies on this site to analyze traffic, remember your preferences, and optimize your experience.