Criando um widget de assinatura com Node.js

Recentemente, desenvolvi um widget de assinatura de código aberto construído usando a biblioteca de API Node.js do SendGrid. Você pode encontrar mais informações sobre as motivações e capacidades do projeto na página README do repositório. Embora esta não seja uma biblioteca SendGrid com suporte oficial, o objetivo era criar um widget flexível e facilmente implementável que qualquer cliente SendGrid pudesse incorporar em uma página HTML que coletasse endereços de e-mail de clientes existentes e potenciais e outras informações úteis para armazenar em seus contatos de campanhas de marketing . Depois que os clientes inserem as informações no formulário, eles recebem um e-mail com um link para confirmar seu endereço de e-mail e, ao clicar no link, o destinatário será adicionado à lista de contatos do cliente do SendGrid.

Além dessa funcionalidade básica, o widget também pode:

• Adicionar um usuário a um segmento de lista específico, se especificado
• Inclua campos personalizados no formulário, cujas entradas serão armazenadas com um determinado contato
• Envie o e-mail de confirmação com um modelo de e-mail existente, se especificado

Este foi um projeto interessante porque utilizou uma variedade de recursos e endpoints de API do SendGrid, incluindo:

• API de envio de e-mail
• API de contatos
• Webhook do evento
• Modelos transacionais

Este post discutirá o processo de criação do widget e alguns dos processos de pensamento que entraram em sua implementação e design.

Visão geral do design do widget

O widget de assinatura funciona permitindo que os clientes do SendGrid implantem um aplicativo no Heroku usando o botão de implantação do Heroku. Para criar o widget usando o botão de implantação, os clientes do SendGrid precisarão de uma conta Heroku (você pode criar uma conta gratuita aqui). No entanto, o widget teoricamente pode ser implantado em qualquer provedor de hospedagem. O cliente do SendGrid pode alterar o endpoint para o qual o formulário personalizado faz sua solicitação POST para a URL do aplicativo Heroku recém-implantado. Quando um usuário envia o formulário, a solicitação será processada pelo aplicativo hospedado no Heroku.

O aplicativo em si é um aplicativo Node/Express básico com duas rotas que tratam do processo de inscrição. A rota confirmEmail envia aos usuários um e-mail com um link para confirmar seu endereço de e-mail e usa um modelo transacional personalizado (se um for especificado). A rota de inscrição adiciona um usuário à lista de contatos do cliente SendGrid e, se especificado, também adiciona o usuário a um segmento de lista personalizado. A rota de inscrição também lida com quaisquer campos personalizados que um cliente do SendGrid opte por incluir em seu formulário personalizado.

Confirmar rota de e-mail

A rota confirmEmail é simplesmente uma solicitação de postagem para o endpoint POST v3/mail/send usando a biblioteca auxiliar Node.js do SendGrid. Em uma resposta bem-sucedida, o usuário será redirecionado para uma página solicitando que verifique sua caixa de entrada para o e-mail de confirmação. Se a resposta não for bem-sucedida, o usuário será redirecionado para uma página solicitando a reinserção do endereço de e-mail. Por exemplo, isso pode acontecer se um usuário inserir um endereço de e-mail inválido.

A função prepareEmail retorna um objeto JSON que servirá como o corpo da solicitação da API.

O processo básico de criação de objetos é bastante simples. Nele, o endereço de e-mail do destinatário é inserido a partir do envio do formulário. No entanto, existem algumas coisas interessantes acontecendo no processo de criação de objetos.

Argumentos personalizados básicos

Dois argumentos personalizados estão incluídos nas personalizações: 1) type, que é definido como 'opt-in' e 2) time_sent, que é definido como a hora atual. Esses argumentos personalizados são passados ​​no cabeçalho do email e serão usados ​​para determinar se um usuário deve ser adicionado a uma lista no processo de confirmação.

ID do modelo

Após a criação inicial do objeto, verificamos se o cliente SendGrid optou por utilizar um template customizado no arquivo de configurações e o adicionamos ao objeto se for o caso (null é o valor padrão). Um modelo personalizado terá prioridade sobre o texto de e-mail incluído no corpo, portanto, se o ID do modelo for deixado como um valor nulo, a mensagem padrão será o texto de e-mail fornecido.

Inserir substituição de link

Incluímos uma substituição para o termo insert_link . Isso só será relevante se o cliente do SendGrid optar por usar um modelo transacional. Se for esse o caso, o termo insert_link será substituído pelo link real usado para confirmar o e-mail de um usuário e redirecioná-lo para a página de sucesso apropriada.

Enviando as entradas de formulário como argumentos personalizados

Por fim, adicionamos os valores que o usuário final enviou ao corpo do email como argumentos personalizados. O envio do usuário final é passado para a rota inicial confirmEmail como o corpo da solicitação, que então passamos para a função prepareEmail como um parâmetro. O corpo da solicitação contém um objeto com um conjunto de chaves, pares de valores que representam o nome da entrada e o valor que o usuário enviou. Em seguida, percorremos as chaves do objeto adicionando um argumento personalizado ao email para cada par de chave e valor. Esses valores serão adicionados às informações de contato do usuário final no processo de criação do contato.

Rota de inscrição

A rota de inscrição é acionada por um webhook de evento que faz uma solicitação POST sempre que um usuário clica no link fornecido no e-mail de confirmação recebido. Essa rota precisa cuidar de alguns itens no processo de criação do contato. Devemos fazer o seguinte:

• Verifique se o formulário continha algum campo personalizado
• Verifique se os campos personalizados existem na conta do cliente SendGrid e crie-os se os campos não existirem
• Certifique-se de que este é um e- mail opcional conforme especificado pelo tipo no processo de criação de e-mail
• Verifique se o link foi clicado em 24 horas
• Crie o contato na conta do cliente SendGrid
• Adicione o novo contato a um segmento de lista específico, se um tiver sido fornecido

Manipulando campos personalizados

A rota de inscrição chama a função addUserToList . Essa função é chamada dentro da rota para que possamos enviar o status após a conclusão do processo dentro de um retorno de chamada. A primeira coisa que fazemos dentro desta função é criar um objeto contendo todos os campos personalizados que o formulário contém e um array contendo os campos personalizados que não são fornecidos por padrão para todos os contatos (email, first_name, last_name).

Uma solicitação POST acionada por webhooks de evento contém todas as informações relacionadas ao email, incluindo os cabeçalhos, assunto, texto etc. do corpo do pedido. No entanto, o objeto também contém uma variedade de campos que não precisamos para o processo de manipulação de campos personalizados, que colocamos em uma matriz chamada ignoreFields .

Em seguida, percorremos os argumentos personalizados para criar o objeto e o array com os campos personalizados mencionados anteriormente. Passaremos o objeto de campos personalizados completo para o corpo no processo de criação do contato, mas não até adicionarmos campos personalizados, conforme necessário, em uma etapa anterior.

Em seguida, chamamos a função checkAndAddCustomFields com dois parâmetros, o array de campo personalizado e um callback, que é onde cuidaremos da criação do contato. É importante primeiro verificar e adicionar quaisquer campos personalizados, pois o endpoint gerará um erro se você tentar criar um contato com um campo personalizado que não existe.

A função checkAndAddCustomFields primeiro faz uma solicitação GET para o ponto de extremidade /v3/contactdb/custom_fields para recuperar os campos existentes do banco de dados de contatos. Em seguida, ele compara a lista de campos personalizados existentes com a lista de campos enviados que foram passados ​​como parâmetro e, se houver algum campo enviado que não esteja incluído na lista de campos personalizados existentes, esses novos campos serão adicionados à matriz fieldsToCreate . Se não houver nenhum campo para criar, a função de retorno de chamada será chamada. No entanto, se houver algum campo a ser criado, fazemos uma solicitação POST para o endpoint /v3/contactdb/custom_fields para cada novo campo personalizado que será criado.

Criando o novo contato

Depois que os campos personalizados forem criados, criamos um novo contato fazendo uma solicitação POST para o endpoint /v3/contactdb/recipients , passando os campos personalizados como o corpo da solicitação. Em seguida, verificamos se o cliente do SendGrid optou por adicionar usuários a um determinado segmento de lista e adicioná-los ao segmento determinado, se for o caso. A resposta à solicitação da API de criação de contato inclui os IDs de contato dos contatos recém-criados como uma matriz chamada persisted_recipients . Usando o ID do contato fornecido na resposta e o ID da lista fornecidos pelo cliente SendGrid, fazemos uma solicitação POST para o endpoint /v3/contactdb/lists/{listId}/recipients/{contactID} .