Pular para o conteúdo principal
Esta página faz parte de Aplicativo de exemplo: uma integração completa do OneSignal, que acompanha um aplicativo real do início ao fim. O aplicativo é o Clean Beans, uma escala de limpeza para casas compartilhadas, construído com Expo (React Native) e um backend Supabase. O Clean Beans usa SMS para duas tarefas que push e email não fazem bem: comprovar que um número de telefone pertence a quem o digitou e alcançar alguém que ainda não tem o aplicativo. Ambas são enviadas para um contato bruto, um número de telefone ou endereço de email, e não para um External ID. Essa é a principal diferença em relação a todos os outros envios deste guia.

Verificar um número de telefone com um código de uso único \

Em User Profile, um usuário pode adicionar um número de celular. O aplicativo pede ao backend que envie um código de 6 dígitos por SMS, o usuário o digita e o backend o verifica. Só então o número é considerado verificado.
O card do número de telefone em três estados: inserindo o número, inserindo o código e verificado

Adicionando um número de telefone: inserir o número, inserir o código, verificado.

O OneSignal entrega a mensagem de texto. Ele não cria nem verifica o código. Todo o resto é trabalho do seu backend.
1

Gerar um código e armazená-lo com hash

O código vem de uma fonte aleatória criptográfica. Apenas um hash com chave é armazenado, vinculado ao usuário e ao número de telefone, de modo que a tabela sozinha não permite recuperar os códigos. A chave é um segredo dedicado, OTP_HASH_SECRET, que não é usado para mais nada. As duas funções se recusam a rodar se ele não estiver definido.
supabase/functions/_shared/otp.ts
supabase/functions/send-otp/index.ts
2

Enviá-lo por SMS pelo OneSignal

include_phone_numbers direciona diretamente para o número. Se o OneSignal nunca o viu, ele cria uma Subscription de SMS para esse número.
supabase/functions/send-otp/index.ts
3

Verificar o código

O backend calcula o hash do que o usuário digitou e o compara com o hash armazenado. Cada tentativa errada é contada. Depois de cinco, o código deixa de valer e é preciso solicitar um novo.
supabase/functions/verify-otp/index.ts
4

Registrar o número como Subscription de SMS

Depois que o backend confirma o código, o aplicativo adiciona o número ao usuário conectado.
src/lib/phone.ts
O aplicativo repete isso a cada login, para que um número verificado acompanhe o usuário em um novo dispositivo.
src/lib/phone.ts
Chame addSms() depois de login(), como no email. Um envio para um número de telefone bruto cria uma Subscription que não pertence a ninguém. addSms() a partir de um aplicativo com usuário conectado vincula essa Subscription ao usuário. Até lá, ela aparece no painel como um registro de usuário separado.

Proteger o endpoint \

Uma função que envia uma mensagem de texto sob demanda custa dinheiro a cada execução e é alvo de abuso. O Clean Beans aplica estes limites.
supabase/functions/send-otp/index.ts
O número verificado fica em uma tabela própria. Somente o backend pode gravar nela, então o aplicativo não pode marcar um número como verificado, e os outros membros de uma casa não podem lê-lo.
supabase/migrations/028_phone_verification_and_invites.sql
Um número de telefone, por si só, não é permissão para enviar mensagens. Para códigos de verificação, basta um aviso ao lado do campo de telefone, que deve dizer quem está enviando, o que será enviado, que tarifas podem ser cobradas e como cancelar.
src/components/PhoneVerificationCard.tsx

Convidar alguém que ainda não é usuário \

Na tela Household, um membro pode convidar alguém por SMS ou por email. A pessoa convidada não tem conta, nem dispositivo registrado, nem External ID. O backend envia para o contato bruto, com um link que abre a tela de entrada do aplicativo.
O diálogo de convite e a mensagem de texto de convite que ele envia

Convidando um colega de casa por SMS ou email, e a mensagem que ele recebe.

O mesmo endpoint trata os dois canais. O SMS usa include_phone_numbers. O email usa email_to, com o assunto e o corpo HTML passados diretamente na solicitação.
supabase/functions/send-invite/index.ts
O link é um Universal Link, configurado em Abrir o aplicativo a partir de links web comuns. Dois detalhes o mantêm funcionando:
  • O rastreamento de cliques do email está desativado. O rastreamento reescreve os links para passarem por um domínio de rastreamento, e um link reescrito não abre mais o aplicativo.
  • O SMS não usa um link curto rastreado, pelo mesmo motivo.
Quando a pessoa convidada instala o aplicativo e faz login, as chamadas login() e addEmail() ou addSms() do aplicativo vinculam ao novo usuário a Subscription que o convite criou.
A pessoa convidada não concordou em receber mensagens do seu aplicativo. As regras para SMS e emails não solicitados variam de país para país e podem ser rígidas. O Clean Beans inclui esse fluxo para mostrar como funciona o envio para um contato bruto, e limita cada membro a dez convites por dia. Antes de usar esse padrão em produção, verifique as regras dos lugares para onde você envia e considere fazer com que quem convida envie a mensagem do próprio telefone.

O que é bom saber \

  • É necessário um remetente. Escolha um remetente padrão em Settings > SMS ou passe sms_from em cada solicitação. Sem nenhum dos dois, a solicitação é rejeitada com “A valid number is required for ‘From’ field”.
  • Uma resposta 200 nem sempre significa que uma mensagem foi enviada. Verifique se há um id de mensagem na resposta, e não apenas o código de status.
  • Armazene os números no formato E.164, um sinal de mais seguido do código do país e do número, e rejeite qualquer outro formato antes de chamar a API.
  • O OneSignal Verify é a alternativa gerenciada. Ele gera e verifica os códigos para você. O Clean Beans cria os próprios para mostrar o fluxo completo.
Configuração do painel. Conclua a configuração de SMS e escolha um remetente padrão que alcance os países onde estão seus usuários.

Senhas de uso único

OneSignal Verify e como criar sua própria solução.

Opt-in e coleta de SMS

Requisitos de consentimento e avisos.

Referência da API de SMS

Todos os parâmetros de SMS.