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 assincronamente.
<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 Pushwoosh
    apiToken: 'XXXXXXX', //  Token de API de Dispositivo
    safariWebsitePushID: 'web.com.example.domain', //  string de domínio reverso única, obtida no seu Portal de Desenvolvedor Apple. Apenas necessário se você enviar notificações push para o navegador Safari
    defaultNotificationTitle: 'Pushwoosh', // define um título padrão para notificações push
    defaultNotificationImage: 'https://yoursite.com/img/logo-medium.png', // URL para imagem de notificação personalizada
    autoSubscribe: false, // ou true. Se true, solicita que um 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>

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 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 da caixa de diálogo de permissão de notificação

Anchor link to

Rastreia a exibição da caixa de diálogo de inscrição nativa.

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


  // Executado ao ocultar a caixa de diálogo de permissão com um dos três status possíveis:
  // 1. default - a caixa de diálogo é fechada
  // 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 a 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) => {
  // Define tags para um usuário
  api.setTags({
    'Tag Name 1': 'value1',
    'Tag Name 2': 'value2'
  });


  // Obtém tags para um usuário do servidor
  api.getTags();


  // Registra o ID do usuário
  api.registerUser('user123');


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


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


  // Registra o número do WhatsApp
  api.registerWhatsappNumber('+1234567890');


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


  //Desregistra das notificações
  api.unregisterDevice();


  // 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 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 (substitui o valor existente)
  • TTagOperationAppend (1): Anexar ao valor da tag (adiciona à lista)
  • TTagOperationRemove (2): Remover valor da tag (remove 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ê escolheu 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 sinalizador verdadeiro/falso.

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 do 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 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 mensagens como excluídas.

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

syncMessages(): Promise<void>

Sincroniza 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 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://yoursite.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 reinscriçã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 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 da sua Aplicação Pushwoosh, o ID do Site Safari e a URL da imagem de notificação padrão.
Também defina uma alta prioridade de Disparo da 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>