Referência do SDK
Todos os comandos de pushwi(), com parâmetros, retorno e exemplos.
Loading documentation…
Powered by heyo
Todo comando passa pela função global pushwi, com o nome do comando como primeiro argumento:
Os comandos assíncronos aceitam um callback no estilo Node, function (err, data), como último argumento, e também retornam uma Promise. As duas formas funcionam:
A Promise nunca é rejeitada. Em caso de erro ela resolve com undefined, e o erro só chega pelo callback. Se você precisa tratar a falha, use o callback.
Algumas falhas são esperadas e não aparecem no console: navegador sem suporte a push, site for fora da tela de início do iOS, permissão negada, soft-ask recusado e comando que exige inscrição chamado sem inscrição. Falhas de rede ou HTTP aparecem como [pushwi] no console quando não há callback.
Quando o SDK termina de carregar, ele define pushwi.ready = true e dispara o evento pushwi:ready em window. Código que roda antes disso pode usar a fila de comandos ou esperar o evento:
Define o ID público do site. Só é necessário quando a tag não tem data-site. Chamar init não dispara a inscrição automática; depois dele, chame subscribe.
Inscreve o navegador. Se o soft-ask estiver ligado e a permissão ainda não foi pedida, ele aparece antes. Depois vem o pedido de permissão do navegador e, por fim, a inscrição é enviada à API com as tags, os atributos e o login definidos até aqui.
Chame subscribe a partir de um clique do usuário. Vários navegadores bloqueiam pedidos de permissão sem interação. Quando isso acontece, o SDK espera o próximo clique ou tecla na página e pede de novo.
Pode chamar mais de uma vez: chamadas simultâneas compartilham o mesmo processo, e chamar com a permissão já dada só atualiza os dados da inscrição.
Adicionam ou removem uma tag da lista local do SDK. Nada é enviado na hora. Veja tags e atributos.
Define um atributo na lista local, também enviado só na próxima inscrição. Use valores simples: texto, número ou booleano.
Associa o navegador a um usuário do seu sistema. O segundo argumento é o token HMAC gerado no seu servidor. Sem um token válido, a API recusa a inscrição inteira. Veja identificação de usuários.
Como as tags, o login só vai para a API na próxima inscrição. Chame antes do subscribe, ou pela fila de comandos antes de o SDK carregar.
Registra um evento personalizado. O nome aceita até 64 caracteres entre letras, números e _ . : -. As propriedades são até 20 pares com valores simples; textos de até 255 caracteres.
Se o navegador estiver inscrito, o evento fica ligado ao assinante e pode ser usado em segmentos. Sem inscrição, o evento é aceito mas não tem dono.
| Campo | Valores |
|---|---|
subscribed | true se este navegador tem uma inscrição de push ativa |
permission | default, granted, denied ou unsupported |
Com permission: "denied", o site não pode pedir de novo; só o próprio usuário reativa nas configurações do navegador. Esconda o botão de inscrição nesse caso.
Avisa a API para descadastrar este dispositivo e cancela a inscrição no navegador. O assinante e os outros dispositivos dele continuam ativos. Para apagar a pessoa, use a rota de exclusão no seu servidor.
addTag, removeTag, setAttribute e login alteram só o estado local do SDK naquela página. Esse estado vai para a API na próxima inscrição, que acontece:
subscribe.Na API, o comportamento é este:
| Dado | O que acontece na inscrição |
|---|---|
| Tags | Só vão na inscrição se a página chamou addTag ou removeTag. A lista enviada substitui as tags do assinante, inclusive quando fica vazia. Página que não mexe em tags não altera as tags salvas. |
| Atributos | Cada chave enviada é criada ou atualizada. Chaves não enviadas continuam como estavam. Valor null apaga a chave. |
| Login | Liga o dispositivo ao assinante com aquele external_id, criando se não existir. |
Como a lista substitui as tags anteriores, uma página que chama addTag("vip") e outra que chama addTag("newsletter") vão alternar a tag do assinante conforme a última página visitada. Nas páginas que mexem em tags, monte a lista completa a partir do mesmo dado (o usuário logado, por exemplo). Páginas que não chamam addTag nem removeTag não enviam tags e não apagam nada.
Para zerar as tags, chame removeTag numa página que não adiciona nenhuma: a lista local fica vazia, vai assim para a API na próxima inscrição e limpa as tags do assinante.
Para mandar tags novas na hora, sem esperar a próxima página, chame subscribe de novo depois de definir:
Quando a informação nasce no seu sistema (uma compra, uma mudança de plano), não é preciso esperar a próxima visita da pessoa. Atualizar assinante muda tags e atributos na hora, com a chave secreta:
| Campo | Efeito |
|---|---|
tags | Substitui todas as tags. [] limpa. |
add_tags, remove_tags | Acrescenta ou tira só as tags listadas, sem mexer nas outras. Não podem vir junto com tags. |
attributes | Mescla chave a chave, como na inscrição. null apaga a chave. |
O assinante pode ter até 50 tags e 50 atributos. Uma alteração que passe disso é recusada inteira com 422.
Lembre que a próxima inscrição de uma página que mexe em tags substitui a lista. Se o servidor e o SDK cuidam das tags do mesmo assinante, a página precisa montar a lista completa, ou deixar as tags só com o servidor.