Pular para o conteúdo
Guias do usuárioSuporte Solicitar demonstração Entrar
Pushwoosh.com

SDK de Web Push 3.0

Integração

Anchor link to

Exemplo de integração no GitHub

Obtenha o SDK de Web Push da Pushwoosh e descompacte-o. Você deve ter os seguintes arquivos:

Anchor link to
  • pushwoosh-service-worker.js

Coloque todos esses arquivos no diretório raiz de nível superior do seu site.

Anchor link to

Inicialize o SDK:

Anchor link to
  1. Inclua o SDK do nosso CDN de forma assíncrona.
<script type="text/javascript" src="//cdn.pushwoosh.com/webpush/v3/pushwoosh-web-notifications.js" async></script>
  1. Inicialize o SDK de Web Push e certifique-se de enfileirar a inicialização até o momento em que o SDK esteja totalmente carregado.
<script type="text/javascript">
var Pushwoosh = Pushwoosh || [];
Pushwoosh.push(['init', {
    logLevel: 'info', // valores possíveis: error, info, debug
    applicationCode: 'XXXXX-XXXXX', // o código da sua aplicação do Painel de Controle da Pushwoosh
    apiToken: 'XXXXXXX', // Token de API do Dispositivo
    safariWebsitePushID: 'web.com.example.domain', // string de domínio reverso única, obtida no seu Portal de Desenvolvedor da Apple. Necessário apenas se você enviar notificações push para o navegador Safari
    defaultNotificationTitle: 'Pushwoosh', // define um título padrão para notificações push
    defaultNotificationImage: 'https://seusite.com/img/logo-medium.png', // URL para uma imagem de notificação personalizada
    autoSubscribe: false, // ou true. Se for true, solicita que o usuário se inscreva para pushes na inicialização do SDK
    subscribeWidget: {
      enable: true
    },
    userId: 'user_id', // opcional, defina um ID de usuário personalizado
    tags: {
        'Name': 'John Smith'     // opcional, defina Tags personalizadas
    }
}]);
</script>

Pop-ups da Web

Anchor link to

Adicione webPopups ao seu objeto init para habilitar campanhas de pop-up da Web em seu site.

webPopups: {
  enable: true,
},

As campanhas de pop-up da Web exibem sobreposições que você configura no Painel de Controle, como promoções, anúncios ou formulários de captura de leads. Diferente do pop-up de inscrição personalizado (subscribePopup), que lida apenas com a adesão a pushes da web, as campanhas de pop-up da Web podem exibir qualquer conteúdo que você configurar. Para configuração no Painel de Controle, veja Entendendo os pop-ups da Web.

Botão de inscrição para push

Anchor link to

Para solicitar que seus usuários se inscrevam para notificações push, recomendamos implementar um botão de inscrição para push em seu site. Melhore a experiência do usuário e obtenha mais inscritos!

Configuração

Anchor link to

Para finalizar a implementação de notificações push em seu site, você precisa configurar as plataformas web em seu Painel de Controle Pushwoosh seguindo nossos guias passo a passo:

Registrando o service worker em um escopo diferente

Anchor link to

Às vezes, você não pode colocar o arquivo do service worker em um diretório raiz de um site, mas em um subdiretório.

Neste caso, modifique a configuração (passo 4.3) adicionando um parâmetro

serviceWorkerUrl: “/push-notifications/pushwoosh-service-worker.js”

onde /push-notifications/pushwoosh-service-worker.js é o caminho para o arquivo pushwoosh-service-worker.js.

Manipuladores de eventos

Anchor link to

No SDK Web da Pushwoosh 3.0, você pode se inscrever em certos eventos para rastreá-los**,** ou cancelar a inscrição de eventos se não precisar mais rastreá-los.

Para rastrear o carregamento do SDK Web 3.0, dispare o evento onLoad da seguinte forma:

// Evento de Carregamento
Pushwoosh.push(['onLoad', (api) => {
  console.log('Pushwoosh carregado!');
}]);

Para rastrear a inicialização correta do SDK Web, dispare o evento onReady:

// Evento de Pronto
Pushwoosh.push((api) => {
  console.log('Pushwoosh pronto!');
});

Para se inscrever ou cancelar a inscrição de qualquer um dos eventos do SDK, use os manipuladores após o carregamento do SDK:

Pushwoosh.push(['onLoad', (api) => {
  function onEventNameHandler() {
    console.log('Evento acionado: event-name!');
  }


  // Para se inscrever em um evento:
  Pushwoosh.addEventHandler('event-name', onEventNameHandler)


  // Para cancelar a inscrição de um evento:
  Pushwoosh.removeEventHandler('event-name', onEventNameHandler)
}]);

Eventos do SDK

Anchor link to

Evento de inscrição

Anchor link to

Executado depois que um usuário concorda em receber notificações push.

Pushwoosh.push(['onLoad', (api) => {
  Pushwoosh.addEventHandler('subscribe', (payload) => {
    console.log('Evento acionado: subscribe');
  });
}]);

Evento de cancelamento de inscrição

Anchor link to

Executado depois que um dispositivo é desregistrado das notificações.

Pushwoosh.push(['onLoad', (api) => {
  Pushwoosh.addEventHandler('unsubscribe', (payload) => {
    console.log('Evento acionado: unsubscribe');
  });
}]);

Eventos do widget de inscrição

Anchor link to

Rastreia a exibição de um widget de Solicitação de Inscrição.

Pushwoosh.push(['onLoad', (api) => {
  // Executado na exibição do widget de Solicitação de Inscrição
  Pushwoosh.addEventHandler('show-subscription-widget', (payload) => {
    console.log('Evento acionado: show-subscription-widget');
  });


  // Executado ao ocultar o widget de Solicitação de Inscrição
  Pushwoosh.addEventHandler('hide-subscription-widget', (payload) => {
    console.log('Evento acionado: hide-subscription-widget');
  });
}]);

Eventos do diálogo de permissão de notificação

Anchor link to

Rastreia a exibição do diálogo de inscrição nativo.

Pushwoosh.push(['onLoad', function (api) {
  // Executado na exibição do diálogo de permissão
  Pushwoosh.addEventHandler('show-notification-permission-dialog', (payload) => {
    console.log('Evento acionado: show-notification-permission-dialog');
  });


  // Executado ao ocultar o diálogo de permissão com um dos três status possíveis:
  // 1. default - o diálogo é fechado
  // 2. granted - a permissão é concedida
  // 3. denied - a permissão é negada
  Pushwoosh.addEventHandler('hide-notification-permission-dialog', (payload) => {
    console.log('Evento acionado: hide-notification-permission-dialog', payload.permission);
  });
}]);

Eventos de permissão

Anchor link to

Verifica o status da permissão de notificações push na inicialização do SDK; rastreia a atualização deste status sempre que ocorrer.

Pushwoosh.push(['onLoad', (api) => {
  // Executado durante a inicialização do SDK se 'autoSubscribe: false' ou/e se um usuário ignorar uma solicitação de notificação push.
  Pushwoosh.addEventHandler('permission-default', (payload) => {
    console.log('Evento acionado: permission-default');
  });


  // Executado durante a inicialização do SDK se as notificações estiverem bloqueadas ou uma vez que um usuário bloqueie as notificações push.
  Pushwoosh.addEventHandler('permission-denied', (payload) => {
    console.log('Evento acionado: permission-denied');
  });


  // Executado durante a inicialização do SDK se as notificações forem permitidas ou uma vez que um usuário permita as notificações push.
  Pushwoosh.addEventHandler('permission-granted', (payload) => {
    console.log('Evento acionado: permission-granted');
  });
}]);

Evento de recebimento de push

Anchor link to

Rastreia a entrega de push para um dispositivo.

Pushwoosh.push(['onLoad', (api) => {
  // Executado quando uma notificação push é exibida.
  Pushwoosh.addEventHandler('receive-push', (payload) => {
    console.log('Evento acionado: receive-push', payload.notification);
  });
}]);

Eventos de notificação

Anchor link to

Rastreia se uma notificação push é aberta ou fechada por um usuário.

Pushwoosh.push(['onLoad', (api) => {
  // Executado quando um usuário clica na notificação.
  Pushwoosh.addEventHandler('open-notification', (payload) => {
    console.log('Evento acionado: open-notification', payload.notification);
  });


  // Executado quando um usuário fecha uma notificação push.
  Pushwoosh.addEventHandler('hide-notification', (payload) => {
    console.log('Evento acionado: hide-notification', payload.notification);
  });
}]);

Eventos da Caixa de Entrada

Anchor link to

Rastreia notificações enviadas para a Caixa de Entrada.

Pushwoosh.push(['onLoad', (api) => {
  // Executado pelo ServiceWorker após a Mensagem da Caixa de Entrada ser recebida e salva no indexedDB.
  Pushwoosh.addEventHandler('receive-inbox-message', (payload) => {
    console.log('Evento acionado: receive-inbox-message', payload.message);
  });


  // Executado após a Caixa de Entrada ser atualizada automaticamente enquanto a página está carregando.
  Pushwoosh.addEventHandler('update-inbox-messages', (payload) => {
    console.log('Evento acionado: receive-inbox-message', payload.messages);
  });
}]);

Eventos de pop-up de inscrição personalizada

Anchor link to

Para detalhes sobre como lidar com eventos de pop-up de inscrição personalizada, consulte o Guia de Eventos de Pop-up de Inscrição Personalizada.

API

Anchor link to

Após a inicialização do SDK de Web Push, você pode fazer as seguintes chamadas para a API da Pushwoosh. Todos os métodos retornam objetos Promise.

Pushwoosh.push((api) => {
  // Definir tags para um usuário
  api.setTags({
    'Tag Name 1': 'value1',
    'Tag Name 2': 'value2'
  });


  // Obter tags para um usuário do servidor
  api.getTags();


  // Registrar ID de usuário
  api.registerUser('user123');


    // Registrar e-mail do usuário
  api.registerEmail('user@example.com');


  // Registrar número de SMS
  api.registerSmsNumber('+15551234567');


  // Registrar número de WhatsApp
  api.registerWhatsappNumber('+1234567890');


  // Postar um Evento
  api.postEvent('myEventName', {attributeName: 'attributeValue'});


  //Cancelar o registro de notificações
  api.unregisterDevice();


  // Definir o idioma do dispositivo (substitui o valor na Tag "Language")
  api.setLanguage('es');


  // Alternativamente, multi-registro de usuário com dispositivos e canais
  api.multiRegisterDevice({
    user_id: 'user123',
    email: 'user@example.com',
    sms_phone_number: '+1234567890',
    tags: {
      'UserType': { operation: TTagOperationSet, value: 'Premium' },
      'Interests': { operation: TTagOperationAppend, values: ['sports', 'technology'] }
    }
  });
});

multiRegisterDevice

Anchor link to

Método de registro aprimorado que permite registrar um perfil de usuário com múltiplos dispositivos e canais de mensagens em uma única chamada de API. Este método é particularmente útil para aplicações multiplataforma ou ao implementar estratégias de mensagens omnichannel.

Pushwoosh.push((api) => {
  api.multiRegisterDevice({
    user_id: 'user123',              // Opcional: Identificador do usuário
    email: 'user@example.com',       // Opcional: E-mail para mensagens de e-mail
    sms_phone_number: '+1234567890', // Opcional: Número de telefone SMS (formato E.164)
    whatsapp_phone_number: '+1234567890', // Opcional: Número do WhatsApp (formato E.164)
    kakao_phone_number: '+1234567890',    // Opcional: Número do KakaoTalk (formato E.164)
    language: 'en',                  // Opcional: Código do idioma (ISO 639-1)
    timezone: 'America/New_York',    // Opcional: Identificador de fuso horário
    city: 'New York',               // Opcional: Cidade para segmentação
    country: 'US',                  // Opcional: País para segmentação
    state: 'NY',                    // Opcional: Estado para segmentação
    tags: {                         // Opcional: Valores de tag com operações
      'UserType': {
        operation: TTagOperationSet,     // Definir valor da tag (0)
        value: 'Premium'
      },
      'Interests': {
        operation: TTagOperationAppend,  // Anexar ao valor da tag (1)
        values: ['sports', 'technology']
      },
      'LoginCount': {
        operation: TTagOperationIncrement, // Incrementar valor da tag (3)
        value: '1'
      }
    },
    push_devices: [                 // Opcional: Array de dispositivos de push
      {
        hwid: 'web-device-456',
        platform: TPlatformChrome, // Plataforma Chrome (11)
        push_token: 'fcm-token-here',
        app_version: '2.1.0',
        platformData: {
          public_key: 'web-push-public-key',
          auth_token: 'web-push-auth-token',
          browser: 'chrome'
        }
      }
    ]
  })
  .then((response) => {
    console.log('Multi-registro bem-sucedido:', response);
  })
  .catch((error) => {
    console.error('Falha no multi-registro:', error);
  });
});

Tipos de Plataforma:

  • TPlatformSafari (10): Plataforma Safari
  • TPlatformChrome (11): Plataforma Chrome
  • TPlatformFirefox (12): Plataforma Firefox

Tipos de Operação de Tag:

  • TTagOperationSet (0): Definir valor da tag (substituir valor existente)
  • TTagOperationAppend (1): Anexar ao valor da tag (adicionar à lista)
  • TTagOperationRemove (2): Remover valor da tag (remover da lista)
  • TTagOperationIncrement (3): Incrementar valor da tag (incremento numérico)

Benefícios:

  • Chamada de API única: Registre múltiplos dispositivos e canais de uma vez
  • Operação atômica: Todos os registros são bem-sucedidos ou falham juntos
  • Centrado no usuário: Associa todos os dispositivos a um único perfil de usuário
  • Marcação avançada: Suporta operações complexas de tags
  • Multiplataforma: Lida com múltiplas plataformas simultaneamente

Exemplo de envio de Tags para a Pushwoosh:

Pushwoosh.push((api) => {
  var myCustomTags = {
    'Tag 1': 123,
    'Tag 2': 'some string'
  };
  api.setTags(myCustomTags)
    .then((res) => {
      var skipped = res && res.skipped || [];
      if (!skipped.length) {
        console.log('sucesso');
      }
      else {
        console.warn('tags ignoradas:', skipped);
      }
    })
    .catch((err) => {
      console.error('erro em setTags:', err);
    });
});

Incrementar valor da Tag

Anchor link to

Para incrementar um valor de uma Tag Numérica, use o parâmetro operation com o valor ‘increment’ da seguinte forma:

Pushwoosh.push((api) => {
  api.setTags({
    'Tag 1': {
      operation: 'increment',
      value: 1
    }
  })
});

Anexar valores de Tag

Anchor link to

Para anexar novos valores à Tag de Lista existente, use o parâmetro operation com o valor ‘append’ da seguinte forma:

Pushwoosh.push((api) => {
  api.setTags({
    'Tag 3': {
      operation: 'append',
      value: ['Value3']
    }
  })
});

Remover valor da Tag

Anchor link to

Para remover um valor de uma Tag de Lista, use o parâmetro operation com o valor ‘remove’ da seguinte forma:

Pushwoosh.push((api) =>{
  api.setTags({
    'Tag 3': {
      operation: 'remove',
      value: ['Value2']
    }
  })
});

Métodos públicos

Anchor link to

Pushwoosh.subscribe()

Este método é usado para solicitar a permissão de um usuário para notificações push. Se um usuário já estiver inscrito, o método interromperá a execução.

Se um usuário ainda não se inscreveu para pushes:

1. A permissão para notificações push é solicitada.

2. Se um usuário permitir notificações, o evento onSubscribe é acionado.

Pushwoosh.subscribe() é executado automaticamente se autoSubscribe: true. for definido durante a inicialização do SDK.

Chame este método se você optou por solicitar manualmente a um usuário que se inscreva para pushes usando o parâmetro autoSubscribe: false durante a inicialização:

<button onclick="Pushwoosh.subscribe()">Inscrever-se</button>
<script>
  Pushwoosh.push(['onSubscribe', (api) => {
    console.log('Usuário inscrito com sucesso');
  }]);
</script>

Pushwoosh.unsubscribe()

  1. O método /unregisterDevice é executado.
  2. O evento onUnsubscribe é acionado.
<button onclick="Pushwoosh.unsubscribe()">Cancelar inscrição</button>
<script type="text/javascript">
  Pushwoosh.push(['onUnsubscribe', (api) => {
    console.log('Usuário cancelou a inscrição com sucesso');
  }]);
</script>

Pushwoosh.isSubscribed()

Verifica se um usuário está inscrito e retorna um flag true/false.

Pushwoosh.isSubscribed().then((isSubscribed) => {
  console.log('isSubscribed', isSubscribed);
});

Pushwoosh.getHWID()

Retorna o HWID da Pushwoosh.

Pushwoosh.getHWID().then((hwid) => {
  console.log('hwid:', hwid);
});

Pushwoosh.getPushToken()

Retorna o token de push se estiver disponível.

Pushwoosh.getPushToken().then((pushToken) => {
  console.log('pushToken:', pushToken);
});

Pushwoosh.getUserId()

Retorna o ID de Usuário se disponível.

Pushwoosh.getUserId().then((userId) => {
  console.log('userId:', userId);
});

Pushwoosh.getParams()

Retorna uma lista dos seguintes parâmetros:

Pushwoosh.getParams().then((params) => {
  params = params || {};
  var hwid = params.hwid;
  var pushToken = params.pushToken;
  var userId = params.userId;
});

Pushwoosh.isAvailableNotifications()

Verifica se um navegador suporta o WebSDK 3.0 da Pushwoosh, retorna ‘true’ ou ‘false’.

Pushwoosh.isAvailableNotifications() // true/false

Métodos InboxMessages

Anchor link to

messagesWithNoActionPerformedCount(): Promise<number>

Retorna o número de mensagens abertas.

Pushwoosh.pwinbox.messagesWithNoActionPerformedCount()
  .then((count) => {
    console.log(`${count} mensagens abertas`);
  });

unreadMessagesCount()

Retorna o número de mensagens não lidas.

Pushwoosh.pwinbox.unreadMessagesCount()
  .then((count) => {
    console.log(`${count} mensagens não lidas`);
  });

messagesCount(): Promise<number>

Retorna o número total de mensagens.

Pushwoosh.pwinbox.messagesCount()
  .then((count) => {
    console.log(`${count} mensagens`);
  });

loadMessages(): Promise<Array>

Carrega a lista de mensagens não excluídas.

Pushwoosh.pwinbox.loadMessages()
  .then(() => {
    console.log('As mensagens foram carregadas');
  });

readMessagesWithCodes(codes: Array<string>): Promise<void>

Marca as mensagens como lidas por Inbox_Ids.

Pushwoosh.pwinbox.readMessagesWithCodes(codes)
  .then(() => {
    console.log('As mensagens foram lidas');
  });

performActionForMessageWithCode(code: string): Promise<void>

Executa a ação atribuída a uma mensagem e marca a mensagem como lida.

Pushwoosh.pwinbox.performActionForMessageWithCode(code)
  .then(() => {
    console.log('A ação foi executada');
  });

deleteMessagesWithCodes(codes: Array<string>): Promise<void>

Marca as mensagens como excluídas.

Pushwoosh.pwinbox.deleteMessagesWithCodes([code])
  .then(() => {
    console.log('As mensagens foram excluídas');
  });

syncMessages(): Promise<void>

Sincroniza as mensagens com o servidor.

Pushwoosh.pwinbox.syncMessages()
  .then(() => {
    console.log('As mensagens foram sincronizadas');
  });

Suporte a Progressive Web App

Anchor link to

Para integrar a Pushwoosh em sua Progressive Web Application (PWA), siga os passos descritos abaixo.

1. Copie o caminho para o seu arquivo de Service Worker:

if ('serviceWorker' in navigator) {
  window.addEventListener('load', () => {
    navigator.serviceWorker.register('/service-worker.js') // <- url do seu service worker
  });
}

Em seguida, use o parâmetro serviceWorkerUrl ao inicializar o WebSDK da seguinte forma:

var Pushwoosh = Pushwoosh || [];
Pushwoosh.push(['init', {
  logLevel: 'error',
  applicationCode: 'XXXXX-XXXXX',
  safariWebsitePushID: 'web.com.example.domain',
  defaultNotificationTitle: 'Pushwoosh',
  defaultNotificationImage: 'https://seusite.com/img/logo-medium.png',
  serviceWorkerUrl: '/service-worker.js', // <- url do seu service worker
}]);

O WebSDK não registra o novo Service Worker imediatamente; um Service Worker é registrado quando é necessário:

  • quando um dispositivo recebe um token de push (no registro do dispositivo ou re-inscrição),
  • quando um token de push é excluído (ao remover um dispositivo da base de usuários).

Isso acelera o carregamento de suas páginas, diminuindo o número de solicitações ao servidor.

Os navegadores não permitem que dois Service Workers diferentes sejam registrados ao mesmo tempo (leia mais: https://github.com/w3c/ServiceWorker/issues/921), então para que sua PWA funcione corretamente, um Service Worker comum deve ser registrado para sua base de código e a base de código da Pushwoosh.

2. Adicione a seguinte string ao seu Service Worker (no início ou no final, não importa):

importScripts('https://cdn.pushwoosh.com/webpush/v3/pushwoosh-service-worker.js' + self.location.search);

Assim, você habilita o recebimento e o processamento de notificações push enviadas através dos serviços da Pushwoosh para o seu Service Worker.

Instalando a partir do Google Tag Manager

Anchor link to

Use o seguinte código em seu Google Tag Manager para inicializar o SDK da Pushwoosh. Crie uma Tag HTML Personalizada e cole o código abaixo. Certifique-se de alterar o Código de Aplicação da Pushwoosh, o ID do Site Safari e a URL da imagem de notificação padrão.
Também defina uma prioridade alta de Disparo de Tag (ex: 100) e acione-a em Todas as Páginas. Veja abaixo uma captura de tela.Copiar

<script type="text/javascript" src="//cdn.pushwoosh.com/webpush/v3/pushwoosh-web-notifications.js" async></script>
<script type="text/javascript">
  var Pushwoosh = Pushwoosh || [];
  Pushwoosh.push(['init', {
    logLevel: 'error',
    applicationCode: 'XXXXX-XXXXX',
    safariWebsitePushID: 'web.com.example.domain',
    defaultNotificationTitle: 'Pushwoosh',
    defaultNotificationImage: 'https://yoursite.com/img/logo-medium.png',
    autoSubscribe: true,
    subscribeWidget: {
      enable: false
    },
    userId: 'user_id'
  }]);
</script>