Inngage Web SDK — Guia do Desenvolvedor

Guia técnico de instalação e uso do Inngage Web SDK v2.0. Público: desenvolvedores integrando o SDK a um site, e-commerce ou aplicação SPA.

1. Instalação

1.1 Script tag (recomendado)

Adicione no <head> de todas as páginas:

<script src="https://cdn.inngage.com.br/midia/js/inngage-sdk/inngage.js" defer></script>

Pronto. O SDK se auto-inicializa: identifica o site pelo domínio, busca a configuração do seu app na Inngage e ativa apenas os recursos habilitados no painel. Não há chave de API no código — a associação é feita pelo domínio cadastrado.

Notas:

Use defer (ou async) — o SDK não bloqueia o render e não depende de DOM pronto.
Não use type="module" — o bundle é um script clássico de propósito.
O SDK carrega módulos adicionais (inngage-*.js) do mesmo diretório do CDN, sob demanda, apenas quando o recurso está habilitado. Nenhuma configuração extra é necessária.

1.2 Google Tag Manager

Tag Custom HTML, disparo em All Pages:

<script>
  (function () {
    var s = document.createElement("script");
    s.src = "https://cdn.inngage.com.br/midia/js/inngage-sdk/inngage.js";
    s.defer = true;
    document.head.appendChild(s);
  })();
</script>

1.3 Service Worker (obrigatório para Web Push)

Hospede o arquivo de service worker da Inngage no seu próprio domínio, no caminho configurado no painel:

https://seusite.com.br/sw.js        ← padrão (custom_path "/" + custom_file "sw.js")
https://seusite.com.br/files/sw.js  ← exemplo com custom_path "/files/"

O arquivo precisa ser servido do seu domínio por exigência dos navegadores (escopo do service worker). Se você não pode hospedar arquivos, use o modo External SW no painel — a Inngage fornece um subdomínio suamarca.inng.me e nenhum arquivo é necessário.

1.4 Requisitos

Requisito	Detalhe
HTTPS	Obrigatório para web push (exigência dos navegadores)
Navegadores	Chrome, Firefox, Edge, Opera, Safari 16+, e derivados. Sem suporte a push, o SDK degrada graciosamente (registra o visitante, sem notificações)
SPA	Suportado. Formulários dinâmicos são detectados via MutationObserver. Para eventos de rota, dispare `newEvent` manualmente na troca de rota

2. Conceitos: identidade do visitante

O SDK gerencia três identificadores no localStorage:

Chave	O que é	Ciclo de vida
`innHash` (uuid)	ID único do dispositivo/navegador, gerado pela Inngage	Permanente, criado na 1ª visita
`identifier`	Identidade de negócio (e-mail, CPF, ID do cliente)	Começa = uuid (anônimo); atualizado quando o usuário se identifica
`registration`	Endpoint técnico de entrega do push	= uuid até existir inscrição de push

O visitante é registrado como subscriber na primeira visita, ainda anônimo. Quando identificado (por qualquer via da seção 4), todo o histórico é unificado sob o novo identifier.

3. API JavaScript

Todas as funções são globais (window.*) e resolvem app_token, identifier, registration e device_uuid automaticamente do storage — passe apenas os dados do negócio.

3.1 Aguardando o SDK (padrão obrigatório)

O SDK carrega assíncrono. Na primeira visita de um usuário, o app_token só existe após o bootstrap. Use este wrapper para qualquer chamada no page load:

function whenInngageReady(fn, tries) {
  tries = tries || 0;
  if (typeof window.newEvent === "function" && localStorage.getItem("app_token")) {
    fn();
  } else if (tries < 50) {
    setTimeout(function () { whenInngageReady(fn, tries + 1); }, 200); // até ~10s
  }
}

Chamadas disparadas por ação do usuário (clique, submit, login) normalmente não precisam do wrapper — o SDK já estará carregado.

3.2 `newEvent(evento, identifier?, appToken?, registration?, deviceUuid?)`

Registra um evento de comportamento (POST /v1/events/newEvent). Eventos alimentam segmentação e automações no painel.

// Forma mínima — contexto resolvido automaticamente:
newEvent({
  event_name: "compra",
  event_values: { total: 199.9, itens: 3, categoria: "eletronicos" }
});

// Com identifier explícito (sobrepõe o automático):
newEvent(
  { event_name: "compra", event_values: { total: 199.9 } },
  "cliente@email.com"
);

Parâmetro	Tipo	Obrigatório	Descrição
`evento.event_name`	string	sim	Nome do evento (ex: `compra`, `add_to_cart`)
`evento.event_values`	object	sim	Payload livre do evento
`identifier`	string	não	Default: localStorage
`appToken`	string	não	Default: localStorage

Se não houver identifier/app_token em lugar nenhum, o evento não é enviado (logado no console com enable_log ativo).

3.3 `newCustomField(fields, identifier, email?, phone?, appToken?, registration?, deviceUuid?)`

Identifica o visitante e grava custom fields (POST /v1/subscription/addCustomField).

// No login ou em qualquer ponto em que o site conheça o cliente:
newCustomField(
  { plano: "premium", cidade: "São Paulo", opt_in_email: true },  // custom fields
  "cliente@email.com",   // identifier — passa a identificar este dispositivo
  "cliente@email.com",   // email (opcional)
  "11999999999"          // telefone (opcional)
);

Efeito colateral importante: o identifier é persistido — a partir daí, newEvent sem argumentos e todo o SDK atribuem atividade a esse usuário.

3.4 `sendPush(campaignId, appToken, identifier)`

Dispara uma campanha de push instantânea para um identifier (POST /v3/message). Uso avançado; é o mecanismo interno do welcome push.

sendPush(11155, "SEU_APP_TOKEN", "cliente@email.com");

3.5 Variáveis globais opcionais

Definidas antes do script do SDK, são anexadas ao registro inicial do subscriber:

<script>
  window.custom_field_values = { origem: "landing-black-friday" };
  window.phone_number = "11999999999";
</script>
<script src="https://cdn.inngage.com.br/midia/js/inngage-sdk/inngage.js" defer></script>

3.6 Utilitários expostos

innStorage, matchRule, isMobileDevice, loadImage, hashCode, innLog — usados internamente e mantidos públicos por compatibilidade. Não dependa deles para lógica própria.

4. Funcionalidades (o que o SDK faz sozinho)

Nenhuma das funcionalidades abaixo exige código no site — são configuradas no painel Inngage.

4.1 Web Push

Registro do subscriber: 1x por sessão (POST /v1/subscription) com navegador, SO, idioma e opt-in — detectados automaticamente.
Pre-permission (soft prompt): banner customizável exibido antes da permissão nativa. Textos, cores, ícone e delay configuráveis. Recusa ativa o silent period (N dias sem perguntar de novo).
Permissão nativa direta: alternativa sem soft prompt.
External SW: sites sem hospedagem própria usam popup no subdomínio *.inng.me para concluir a inscrição.
Welcome push: campanha disparada automaticamente no momento da primeira inscrição (se configurada).

4.2 On-site Notifications

Popups dentro do site, com dois formatos de payload:

v1 (legado): card com ícone/título/corpo, carrossel de imagens, countdown, botões, lead capture.
v2 (type no payload): JSON estruturado com modelos discriminados — Message (carrossel de conteúdo), e roadmap Countdown, LeadCapture, Scratch (raspadinha), Wheel (roleta) e Feed (central de notificações).

O SDK detecta o formato automaticamente e carrega o renderer correto. Regras client-side: segmentação por página (whitelist/blacklist), dispositivo, nº mínimo de páginas na sessão, triggers (imediato, exit intent, scroll) e frequency cap de 60 min.

4.3 Widget de WhatsApp

Botão flutuante com posição, imagem e link configuráveis; triggers de scroll, tempo de tela, exit intent e inatividade; regras de página; e personalização automática da mensagem em páginas de produto VTEX (URLs /p).

4.4 Form Integration

Captura automática de todos os <form> com name, id ou data-id:

Envio em background (POST /v3/formWebhook, com keepalive — funciona mesmo se a página navegar).
Não interfere no submit original do formulário.
Formulários com e-mail identificam o visitante automaticamente.
SPAs: formulários injetados dinamicamente são detectados.

Para excluir um formulário da captura, não lhe dê name/id/data-id, ou solicite regra no painel.

4.5 Integração VTEX

Em lojas VTEX (source configurado no painel), o SDK lê o OrderForm a cada página e identifica automaticamente clientes logados via GET /v4/etl — sem código na loja.

5. Receitas prontas

5.1 PAGE_VIEW via GTM

<script>
(function () {
  var tries = 0;
  (function waitSdk() {
    if (typeof window.newEvent === "function" && localStorage.getItem("app_token")) {
      window.newEvent({
        event_name: "PAGE_VIEW",
        event_values: { url: {{Page URL}}, page_name: {{Page Title}} }
      });
    } else if (tries++ < 50) { setTimeout(waitSdk, 200); }
  })();
})();
</script>

5.2 Identificar no login

// callback de sucesso do seu login:
function onLoginSuccess(user) {
  newCustomField(
    { nome: user.name, plano: user.plan },
    user.email,
    user.email,
    user.phone
  );
}

5.3 Evento de compra no checkout

function onPurchase(order) {
  newEvent({
    event_name: "compra",
    event_values: {
      order_id: order.id,
      total: order.total,
      itens: order.items.length
    }
  });
}

5.4 SPA — evento por troca de rota (React exemplo)

useEffect(() => {
  newEvent({ event_name: "PAGE_VIEW", event_values: { url: location.pathname } });
}, [location.pathname]);

6. Debug e troubleshooting

6.1 Logs

Ative enable_log no painel. O console (F12) passa a mostrar cada decisão do SDK. Os logs são desligados por padrão em produção.

6.2 Checklist no DevTools

Verificação	Onde	Esperado
Core carregou	Network → `inngage.js`	200, `application/javascript`
Módulos ativos	Console → `window.__inngageModules`	Objeto com os módulos carregados
API disponível	Console → `typeof newEvent`	`"function"`
Subscriber registrado	Network → `POST /v1/subscription`	200, payload com uuid
Identidade	Application → Local Storage	`innHash`, `identifier`, `app_token` preenchidos
Config da sessão	Application → Session Storage → `inn_preferences`	JSON com os recursos habilitados

6.3 Problemas comuns

Mudou config no painel e nada mudou — config é cacheada por sessão do navegador. Feche todas as abas do site ou rode sessionStorage.clear() e recarregue.

Push não inscreve — confira: HTTPS, sw.js acessível no caminho configurado (abra a URL direto), permissão do navegador não bloqueada (cadeado → Notificações), e status_webpush ativo no painel.

Welcome push não chegou — só dispara na criação da inscrição. Para retestar: Application → Clear site data + resetar permissão de notificações + aceitar de novo.

Evento não aparece no painel — verifique no Network se o POST /v1/events/newEvent saiu com 200 e se o identifier do payload é o esperado. Com log ativo, o SDK avisa quando aborta por falta de identifier/token.

Onsite não exibe — com log ativo, o console informa o motivo exato do bloqueio (frequency cap, regra de página, dispositivo, trigger pendente).

6.4 Reset completo do estado (ambiente de teste)

localStorage.clear();
sessionStorage.clear();
navigator.serviceWorker.getRegistrations().then(rs => rs.forEach(r => r.unregister()));
// + resetar permissão de notificações no cadeado do navegador, e recarregar

7. Segurança e privacidade

O SDK não coleta dados de pagamento nem lê campos type="password".
Todo conteúdo remoto (onsite) é renderizado como texto (textContent) — nunca HTML executável.
Comunicação exclusivamente com api.inngage.com.br via HTTPS.
O app_token presente no localStorage é um identificador de app, não uma credencial secreta — operações sensíveis são validadas server-side.
Recomenda-se citar a Inngage como suboperadora na política de privacidade do site (LGPD).

Como podemos ajudar?

Inngage Web SDK — Guia do Desenvolvedor

1. Instalação

1.1 Script tag (recomendado)

1.2 Google Tag Manager

1.3 Service Worker (obrigatório para Web Push)

1.4 Requisitos

2. Conceitos: identidade do visitante

3. API JavaScript

3.1 Aguardando o SDK (padrão obrigatório)

3.2 `newEvent(evento, identifier?, appToken?, registration?, deviceUuid?)`

3.3 `newCustomField(fields, identifier, email?, phone?, appToken?, registration?, deviceUuid?)`

3.4 `sendPush(campaignId, appToken, identifier)`

3.5 Variáveis globais opcionais

3.6 Utilitários expostos

4. Funcionalidades (o que o SDK faz sozinho)

4.1 Web Push

4.2 On-site Notifications

4.3 Widget de WhatsApp

4.4 Form Integration

4.5 Integração VTEX

5. Receitas prontas

5.1 PAGE_VIEW via GTM

5.2 Identificar no login

5.3 Evento de compra no checkout

5.4 SPA — evento por troca de rota (React exemplo)

6. Debug e troubleshooting

6.1 Logs

6.2 Checklist no DevTools

6.3 Problemas comuns

6.4 Reset completo do estado (ambiente de teste)

7. Segurança e privacidade

Não encontrou a resposta que precisava?

Menu

Recursos

Como podemos ajudar?

Inngage Web SDK — Guia do Desenvolvedor

1. Instalação

1.1 Script tag (recomendado)

1.2 Google Tag Manager

1.3 Service Worker (obrigatório para Web Push)

1.4 Requisitos

2. Conceitos: identidade do visitante

3. API JavaScript

3.1 Aguardando o SDK (padrão obrigatório)

3.2 newEvent(evento, identifier?, appToken?, registration?, deviceUuid?)

3.3 newCustomField(fields, identifier, email?, phone?, appToken?, registration?, deviceUuid?)

3.4 sendPush(campaignId, appToken, identifier)

3.5 Variáveis globais opcionais

3.6 Utilitários expostos

4. Funcionalidades (o que o SDK faz sozinho)

4.1 Web Push

4.2 On-site Notifications

4.3 Widget de WhatsApp

4.4 Form Integration

4.5 Integração VTEX

5. Receitas prontas

5.1 PAGE_VIEW via GTM

5.2 Identificar no login

5.3 Evento de compra no checkout

5.4 SPA — evento por troca de rota (React exemplo)

6. Debug e troubleshooting

6.1 Logs

6.2 Checklist no DevTools

6.3 Problemas comuns

6.4 Reset completo do estado (ambiente de teste)

7. Segurança e privacidade

Não encontrou a resposta que precisava?

Menu

Recursos

3.2 `newEvent(evento, identifier?, appToken?, registration?, deviceUuid?)`

3.3 `newCustomField(fields, identifier, email?, phone?, appToken?, registration?, deviceUuid?)`

3.4 `sendPush(campaignId, appToken, identifier)`