Documentação | ArautoFlow

Antes de começar

No painel do ArautoFlow, conecte o projeto Firebase da sua empresa e cadastre cada site ou app como uma propriedade. Cada propriedade tem duas chaves:

Chave pública (pk_…): vai no código do site ou do app. Só permite inscrever e identificar assinantes.
Chave secreta (sk_…): fica só no seu servidor. Permite criar campanhas pela API. Nunca a coloque no navegador nem no app.

1. Instalação no site

Inclua o script em todas as páginas em que o convite de inscrição pode aparecer. O atributo data-key recebe a chave pública da propriedade.

index.html

<!-- Em todas as páginas, antes de </body> -->
<script src="https://api.arautoflow.com.br/sdk/v1/arautoflow.js" data-key="pk_SUA_CHAVE_PUBLICA" async></script>

Arquivo do service worker

Crie o arquivo /arautoflow-sw.js na raiz do domínio (ex.: https://seusite.com.br/arautoflow-sw.js) com uma única linha:

arautoflow-sw.js

importScripts('https://api.arautoflow.com.br/sdk/v1/sw.js?key=pk_SUA_CHAVE_PUBLICA');

O convite vem antes do pedido do navegador

Com o convite ativado no painel, o SDK mostra primeiro a sua mensagem e só chama o pedido nativo de quem clicar em aceitar. Isso protege a base: quem nega o pedido do navegador não pode ser convidado de novo. Texto, botões, posição, atraso, número mínimo de páginas vistas e intervalo depois de um “agora não” são configurados no painel.

Requisitos

O site precisa estar em HTTPS.
O arquivo do service worker tem de ser servido pelo seu próprio domínio, na raiz — não dá para apontar para outro domínio.

2. Botão próprio de inscrição

Prefere controlar quando pedir? Use data-auto-prompt="false" para desligar o convite automático e chame ArautoFlow.subscribe() no clique de um botão seu. A função devolve uma Promise com o ID do assinante.

pagina.html

<script src="https://api.arautoflow.com.br/sdk/v1/arautoflow.js"
        data-key="pk_SUA_CHAVE_PUBLICA" data-auto-prompt="false" async></script>

<button id="ativar-avisos">Ativar notificações</button>

<script>
  window.ArautoFlowQueue = window.ArautoFlowQueue || [];
  ArautoFlowQueue.push(function (af) {
    document.getElementById('ativar-avisos').addEventListener('click', function () {
      af.subscribe()
        .then(function (id) { console.log('Inscrito:', id); })
        .catch(function (erro) { console.warn(erro.message); });
    });
  });
</script>

3. Identificar o assinante

O SDK já registra a origem da inscrição (página de entrada, referenciador e UTMs). Para ligar o assinante a uma pessoa do seu sistema — depois de um login ou de um formulário, por exemplo — use ArautoFlow.identify().

Como o script carrega de forma assíncrona, use ArautoFlowQueue.push(fn): a função roda assim que o SDK estiver pronto (ou na hora, se ele já estiver). Se a pessoa ainda não for assinante, os dados ficam guardados e são enviados junto com a inscrição.

app.js

// Pode ser chamado antes do script terminar de carregar
window.ArautoFlowQueue = window.ArautoFlowQueue || [];

ArautoFlowQueue.push(function (af) {
  af.identify({
    email: 'ana@exemplo.com',
    name: 'Ana Souza',
    external_id: '1234',            // ID do cliente no seu sistema
    tags: { plano: 'pro', interesse: 'esportes' }
  });
});

Campos aceitos: email, name, external_id, phone, attributes (objeto livre) e tags (objeto chave: valor, usado na segmentação). Para mudar só as tags, há o atalho ArautoFlow.setTags({ ... }).

4. Eventos

Registre funções com ArautoFlow.on(evento, callback):

Evento	Quando acontece
`subscribed`	A inscrição foi registrada. Recebe `{ subscriberId, created }`.
`denied`	A pessoa recusou o pedido de permissão do navegador.
`message`	Chegou uma notificação com o site ou o app aberto. Recebe os dados da mensagem.
`click`	No app Capacitor, a pessoa tocou na notificação. No site, o clique é tratado pelo service worker, que abre o link da campanha.
`unsubscribed`	Depois de `ArautoFlow.unsubscribe()`.
`prompt:shown` `prompt:accepted` `prompt:dismissed`	O convite do ArautoFlow foi exibido, aceito ou dispensado.

eventos.js

ArautoFlowQueue.push(function (af) {
  af.on('subscribed', function (e) {
    console.log('Assinante', e.subscriberId, e.created ? '(novo)' : '(já existia)');
  });

  af.on('denied', function () {
    // A pessoa recusou o pedido do navegador
  });

  af.on('message', function (data) {
    // Notificação chegou com o site/app aberto
  });

  af.on('click', function (data) {
    // App Capacitor: clique na notificação. data.af_url traz o link da campanha.
    // Com um ouvinte de 'click', o SDK não abre o link sozinho.
  });
});

5. App Capacitor (Android e iOS)

Em apps Capacitor, o mesmo SDK detecta que está rodando no aparelho e usa o plugin de mensagens do Firebase para obter o token. Cadastre o app como uma propriedade própria no painel e use a chave pública dele.

terminal

npm install @capacitor-firebase/messaging firebase
npx cap sync

Siga a configuração nativa do plugin (arquivo google-services.json no Android e GoogleService-Info.plist no iOS, do mesmo projeto Firebase conectado ao ArautoFlow) e carregue o script no app:

index.html

<!-- index.html do app: arautoflow.js copiado para a pasta de assets.
     Baixe em https://api.arautoflow.com.br/sdk/v1/arautoflow.js -->
<script src="assets/arautoflow.js" data-key="pk_CHAVE_DO_APP"></script>

Atenção no iOS

Use @capacitor-firebase/messaging. Com o plugin @capacitor/push-notifications, o token entregue no iOS é do APNs, não do FCM — e o FCM recusa esse token.
No projeto Firebase, envie a chave APNs (arquivo .p8) da sua conta Apple Developer.
O iOS só entrega notificações se a pessoa tocar em “Permitir” no pedido do sistema.

6. API de servidor

Para disparos transacionais (pedido enviado, lembrete, alerta), chame a API a partir do seu servidor com a chave secreta no cabeçalho Authorization: Bearer sk_…. A campanha vale para os assinantes da propriedade dona da chave.

`POST /api/v1/campaigns`

Campo	Descrição
`title`	Obrigatório. Título da notificação (até 120 caracteres).
`body`	Obrigatório. Texto da notificação (até 500 caracteres).
`click_url`	Opcional. Link aberto no clique.
`image_url`	Opcional. Imagem grande da notificação.
`data`	Opcional. Objeto com dados extras entregues ao site ou app.
`platforms`	Opcional. Lista com `"web"`, `"android"` e/ou `"ios"`. Vazio = todas.
`tags`	Opcional. Objeto `{ "chave": "valor" }`. O assinante precisa ter todas as tags informadas.
`send_at`	Opcional. Data e hora futura em ISO 8601 para agendar. Sem ele, o envio começa na hora.

terminal

curl -X POST https://api.arautoflow.com.br/api/v1/campaigns \
  -H "Authorization: Bearer sk_SUA_CHAVE_SECRETA" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "title": "Seu pedido saiu para entrega",
    "body": "Toque para acompanhar a entrega.",
    "click_url": "https://sualoja.com.br/pedidos/1234",
    "platforms": ["android", "ios"],
    "tags": { "cliente": "1234" }
  }'

resposta

HTTP/1.1 201 Created

{
  "id": 87,
  "status": "sending",
  "scheduled_at": null,
  "started_at": "2026-09-27T14:03:11-03:00",
  "finished_at": null,
  "recipients": 2,
  "sent": 0,
  "failed": 0,
  "received": 0,
  "clicked": 0,
  "error": null,
  "estimated_recipients": 2
}

`GET /api/v1/campaigns/{id}`

Consulta o andamento de uma campanha criada pela mesma propriedade.

terminal

curl https://api.arautoflow.com.br/api/v1/campaigns/87 \
  -H "Authorization: Bearer sk_SUA_CHAVE_SECRETA" \
  -H "Accept: application/json"

resposta

{
  "id": 87,
  "status": "sent",
  "recipients": 2,
  "sent": 2,
  "failed": 0,
  "received": 2,
  "clicked": 1,
  "error": null
}

Campo	Significado
`status`	`scheduled`, `sending`, `sent`, `cancelled` ou `failed`.
`recipients`	Assinantes no público da campanha.
`sent`	Mensagens aceitas pelo FCM.
`failed`	Mensagens recusadas.
`received`	Entregas confirmadas pelo aparelho.
`clicked`	Cliques na notificação.
`error`	Último erro da campanha, quando houver.

Dica: mensagem para uma pessoa só

Marque o assinante com uma tag única no identify() — por exemplo tags: { cliente: '1234' } — e use essa mesma tag no disparo pela API.

Referência rápida do SDK

Função	O que faz
`subscribe()`	Pede a permissão e inscreve agora. Devolve uma Promise com o ID do assinante.
`identify(perfil)`	Liga o assinante a uma pessoa (`email`, `name`, `external_id`, `phone`, `attributes`, `tags`).
`setTags(tags)`	Atalho para `identify({ tags })`.
`unsubscribe()`	Cancela a inscrição deste aparelho.
`isSubscribed()`	`true` se este aparelho já está inscrito.
`subscriberId()`	ID do assinante neste aparelho, ou `null`.
`on(evento, fn)`	Registra um ouvinte de evento.
`debug()`	Liga o log no console do navegador (`debug(false)` desliga).

Atributos do script: data-key (chave pública, obrigatório) e data-auto-prompt="false" (desliga o convite e a inscrição automática).

SDK e API
Documentação.

Antes de começar

1. Instalação no site

Arquivo do service worker

O convite vem antes do pedido do navegador

Requisitos

2. Botão próprio de inscrição

3. Identificar o assinante

4. Eventos

5. App Capacitor (Android e iOS)

Atenção no iOS

6. API de servidor

`POST /api/v1/campaigns`

`GET /api/v1/campaigns/{id}`

Dica: mensagem para uma pessoa só

Referência rápida do SDK

Ficou alguma dúvida técnica?