Referência do Browser SDK
Uma referência do Browser SDK, window.sdk: como oferecer a instalação de um PWA a partir da
página, inscrever o visitante em push, enviar eventos e quais configurações são necessárias para
isso. Para uma introdução geral, veja Browser SDK; para conectá-lo ao seu próprio
prelanding, veja SDK no seu prelanding.
As configurações window.pwaConfig
O SDK lê suas configurações do objeto window.pwaConfig, que você define na página antes da
tag de script. Nas páginas servidas pelo Qubix, o objeto é preenchido automaticamente; no seu
próprio prelanding, você mesmo o define.
| Campo | Finalidade |
|---|---|
pwaId | O identificador do PWA. Obrigatório para a instalação e para o push |
domain | O domínio da página. Obrigatório para o manifest e para o push |
vapidKey | A chave para o push. Normalmente inserida automaticamente quando /sdk.js carrega — não é necessário definí-la manualmente |
offerId | A oferta (se precisar passá-la explicitamente) |
campaignId | A campanha (se precisar passá-la explicitamente) |
params | Tags de rastreamento adicionais |
previewMode | Modo de pré-visualização: os eventos não são enviados |
O identificador do PWA (pwaId) é obtido no card do aplicativo na seção PWA Apps.
Inscrever em push
sdk.subscribePush() solicita permissão de notificação ao navegador e cria uma inscrição. Você
deve chamá-lo explicitamente — por exemplo, ao clicar em um botão. Ele não dispara por conta
própria.
const subscription = await sdk.subscribePush()
if (subscription) {
// o visitante permitiu as notificações e está inscrito
}
O que acontece internamente:
- O prompt de permissão do navegador é exibido.
- Se o visitante permitir, uma inscrição é criada e enviada ao Qubix.
- Chamadas repetidas são seguras: se o visitante já estiver inscrito, o prompt não é exibido novamente.
A instalação do aplicativo não é obrigatória para o push — um visitante pode se inscrever em uma página comum.
O push funciona apenas por uma conexão segura (HTTPS) e em um domínio configurado no Qubix. Mais sobre isso em SDK no seu prelanding.
Instalar o PWA
Se window.pwaConfig tiver um pwaId, o SDK expõe os métodos sdk.pwa:
| Método | O que faz |
|---|---|
sdk.pwa.init() | Preparação: registra o service worker e anexa o manifest do aplicativo |
sdk.pwa.install() | Exibe o prompt de instalação do aplicativo do sistema |
sdk.pwa.canInstall() | Se a instalação está disponível no momento |
sdk.pwa.isInstalled() | Se o aplicativo já está instalado |
sdk.pwa.open() | Abre o aplicativo instalado |
init, install e isInstalled são assíncronos — chame-os com await. canInstall e open
retornam um valor imediatamente.
if (sdk.pwa && sdk.pwa.canInstall()) {
await sdk.pwa.install()
}
O prompt de instalação é exibido pelo próprio navegador, portanto as regras dele se aplicam: HTTPS, um manifest anexado (o SDK o anexa para você) e, normalmente, uma ação do visitante na página (um clique, um scroll). Por isso o botão de instalação é normalmente associado a um toque explícito.
Eventos
O SDK reporta os momentos-chave ao analytics por conta própria — eles são visíveis nos relatórios e no fluxo de eventos:
| Evento | Quando |
|---|---|
campaign_visit | Uma visita à página (enviado automaticamente) |
push_prompt_shown | O prompt de permissão de push foi exibido |
push_allow | O visitante permitiu o push |
push_deny | O visitante negou o push |
push_ignored | O visitante fechou o prompt sem escolher |
install_accepted | O visitante concordou em instalar o aplicativo |
install_rejected | O visitante recusou a instalação |
Você pode enviar seu próprio evento manualmente:
sdk.sendEvent('my_button_click', { place: 'hero' })
Dados de tráfego
Métodos auxiliares para ler o contexto do clique:
| Método | Retorna |
|---|---|
sdk.getOffer() | A oferta atual (id e URL) |
sdk.getPwa() | O PWA atual |
sdk.getPiuid() | O id do visitante |
sdk.getTrackingParams() | As tags do tracker que vieram com o clique |
sdk.buildOfferUrl(url) | Constrói uma URL de oferta com as tags preservadas |
sdk.showStore() | Vai ao card da loja PWA |
O que o SDK faz por conta própria
Sem nenhuma chamada do seu lado, ao carregar a página o SDK coleta dados do dispositivo, analisa
as tags de rastreamento da URL, anexa o manifest do aplicativo (se pwaId estiver definido) e
envia o evento campaign_visit. A instalação e a inscrição em push não se iniciam por conta
própria — você as aciona a partir do código.