Relatórios por email

O Runlight envia resumos semanais ou mensais pelo seu próprio serviço de e-mail, no idioma de cada leitor.

O Runlight pode enviar por e-mail um resumo de um site toda semana ou todo mês. Cada resumo traz a frase principal, os seis números comparados ao período anterior, as páginas, origens e países principais, e as conversões com a receita delas. Ele sai do seu próprio endereço, por um serviço de e-mail que você já usa.

1. Configure o serviço de e-mail

Em Configurações, Serviço de e-mail, escolha um serviço e informe as chaves dele, junto com o endereço de onde saem os relatórios. Enviar teste verifica se funciona. Um só serviço de e-mail atende todos os sites da instalação.

O endereço de envio precisa ser um que o seu serviço permita usar, normalmente num domínio que você verificou nele.

As chaves são guardadas criptografadas com uma chave derivada de RUNLIGHT_SECRET (ou, sem ela, de RUNLIGHT_TOKEN) e nunca são devolvidas ao navegador, então deixe um campo em branco para manter a chave salva. Se nenhuma das duas variáveis estiver definida, as chaves ficam guardadas como foram digitadas e as Configurações avisam.

Você também pode definir o serviço no código passando mail, e as Configurações então o mostram sem poder alterá-lo.

runlight({
  store,
  mail: { service: "resend", apiKey: process.env.RESEND_API_KEY!, from: "reports@example.com", fromName: "Runlight" },
});

Envio pelo seu app

Um app que já envia e-mail, como um CMS, pode passar o próprio mailer como mail. Ele é uma função send que recebe cada mensagem (to, from, fromName, subject, html, text e headers), junto com o endereço e o nome de onde ela sai e via, o nome que as Configurações mostram para ele. Relatórios, e-mails de teste, convites e links de login passam então por ele, e as Configurações mostram o nome e o endereço de envio dele.

O mailer do app é um padrão. O proprietário ainda pode escolher outro serviço nas Configurações, que toma o lugar dele, e remover esse serviço volta para o mailer do app. Os plugins de WordPress, Drupal e Craft passam o deles quando o site tem um mailer de verdade configurado.

runlight({
  store,
  mail: { from: "hello@example.com", fromName: "Example", via: "My app", send: (message) => mailer.send(message) },
});

No Go o mailer é uma opção própria, AppMailer, com Send, From, FromName e Via, e no Rust ele é app_mailer. Ruby e Elixir chamam o remetente de from_name, e o PHP recebe um callable como send.

Passe mailServices com os ids dos serviços que as Configurações podem oferecer para deixar os outros de fora, como o plugin de WordPress faz com o SMTP. Um serviço salvo antes que não está na lista conta como nenhum, então o mailer do próprio app volta a enviar.

O webhook

O webhook recebe um POST cujo corpo JSON tem to, from, fromName, subject, html, text e headers. Com um segredo de assinatura definido, o cabeçalho x-runlight-signature traz sha256= seguido do HMAC-SHA256 do corpo bruto em hexadecimal. A URL precisa usar https (ou ser localhost).

2. Adicione quem recebe relatórios

Em Configurações, Relatórios por email, adicione um endereço com a frequência (semanal ou mensal) e o idioma em que o e-mail deve vir. Enviar um exemplo agora envia o relatório mais recente na hora, uma vez por minuto para cada endereço. A partir de um servidor independente conectado, os exemplos saem uma vez a cada dez minutos para o site inteiro.

• Os relatórios semanais cobrem de segunda a domingo e saem a partir das 8h de segunda-feira.
• Os relatórios mensais cobrem o mês do calendário e saem a partir das 8h do dia 1º.

Os dois usam o fuso horário do site, e cada período é enviado uma vez. Se o envio falhar, a próxima verificação tenta de novo.

3. Agende a verificação

Os relatórios são enviados pela verificação de hora em hora, então nada sai até ela estar agendada.

Cancelamento da inscrição

Todo e-mail tem um link para cancelar a inscrição e os cabeçalhos List-Unsubscribe que os apps de e-mail usam no próprio botão de cancelar inscrição. O link abre uma página com um botão, para que um scanner de e-mail que abre links não consiga cancelar a inscrição de ninguém por acidente.