Web Push SDK 3.0

Note

Предварительные требования

Для интеграции Web Push SDK с вашим HTTPS-сайтом необходимо выполнить следующие действия:

1. Найдите ваш Application Code Wavesend.
2. Chrome и Firefox: найдите ваш API-ключ Firebase и Sender ID. Для этого выполните шаги 1-3 из руководства Конфигурация Chrome и Firefox.
3. Safari: найдите ваш Website Push ID.
4. Загрузите Wavesend Web Push SDK.

Caution

• Push-уведомления Chrome не будут работать с самоподписанными сертификатами (https/ssl). Вам понадобится SSL-сертификат, подписанный доверенным центром сертификации.
• Push-уведомления не работают в режиме инкогнито и гостевом режиме.
• Автоматическая подписка недоступна для Safari.

Интеграция

Используете npm?

Если вы предпочитаете использовать npm для управления пакетами, вы также можете установить и интегрировать Wavesend Web SDK через npm. Подробные инструкции вы найдете в нашем руководстве по использованию с npm.

Пример интеграции на GitHub

Загрузите Wavesend Web Push SDK и распакуйте его. У вас должны быть следующие файлы:

• wavesend-service-worker.js

Поместите все эти файлы в корневой каталог вашего сайта.

Note

Убедитесь, что следующие URL-адреса общедоступны:

• https://yoursite.com/wavesend-service-worker.js

Инициализируйте SDK:

1. Подключите SDK из нашего CDN асинхронно.

Note

Поддерживается Google Tag Manager!

Нажмите здесь, если вы используете Google Tag Manager.

<script type="text/javascript" src="/docs//cdn.wavesend.ru/webpush/v3/wavesend-web-notifications.js" async></script>

3. Инициализируйте Web Push SDK и поставьте инициализацию в очередь до полной загрузки SDK.

Note

Для инициализации Web Push SDK необходимо передать Device API token в параметре apiToken.

Важно: Убедитесь, что токен имеет доступ к правильному приложению в вашей Wavesend Control Panel. Узнать больше

<script type="text/javascript">
var Wavesend = Wavesend || [];
Wavesend.push(['init', {
    logLevel: 'info', // возможные значения: error, info, debug
    applicationCode: 'XXXXX-XXXXX', // ваш application code из Wavesend Control Panel
    apiToken: 'XXXXXXX', //  Device API Token
    safariWebsitePushID: 'web.com.example.domain', //  уникальная строка в формате reverse-domain, полученная на вашем портале разработчика Apple. Требуется только если вы отправляете push-уведомления в браузер Safari
    defaultNotificationTitle: 'Wavesend', // устанавливает заголовок по умолчанию для push-уведомлений
    defaultNotificationImage: 'https://yoursite.com/img/logo-medium.png', // URL кастомного изображения для уведомлений
    autoSubscribe: false, // или true. Если true, предлагает пользователю подписаться на push-уведомления при инициализации SDK
    subscribeWidget: {
      enable: true
    },
    userId: 'user_id', // необязательно, установите кастомный ID пользователя
    tags: {
        'Name': 'John Smith'     // необязательно, установите кастомные Tags
    }
}]);
</script>

Note

Кнопка подписки на push-уведомления

Чтобы предложить пользователям подписаться на push-уведомления, мы рекомендуем внедрить на ваш сайт кнопку подписки на push-уведомления. Улучшите пользовательский опыт и получите больше подписчиков!

Конфигурация

Чтобы завершить внедрение push-уведомлений на ваш сайт, необходимо настроить веб-платформы в вашей Wavesend Control Panel, следуя нашему пошаговому руководству:

• Конфигурация Web Push

Note

Чтобы получить FCM sender ID и API-ключ, выполните шаги 1-3 из руководства по настройке Android.

Регистрация service worker в другой области

Иногда service worker нельзя разместить в корневом каталоге сайта, а только в подкаталоге.

В этом случае измените конфигурацию (шаг 3), добавив параметр

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

где /push-notifications/wavesend-service-worker.js — это путь к файлу wavesend-service-worker.js.

Обработчики событий

В Wavesend Web SDK 3.0 вы можете подписываться на определенные события для их отслеживания или отписываться от событий, если отслеживание больше не требуется.

Чтобы отследить загрузку Web SDK 3.0, вызовите событие onLoad следующим образом:

// Событие загрузки
Wavesend.push(['onLoad', (api) => {
  console.log('Wavesend load!');
}]);

Чтобы отследить корректную инициализацию Web SDK, вызовите событие onReady:

// Событие готовности
Wavesend.push((api) => {
  console.log('Wavesend ready!');
});

Чтобы подписаться на события SDK или отписаться от них, используйте обработчики после загрузки SDK:

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

  // Для подписки на событие:
  Wavesend.addEventHandler('event-name', onEventNameHandler)

  // Для отписки от события:
  Wavesend.removeEventHandler('event-name', onEventNameHandler)
}]);

События SDK

Событие подписки

Выполняется после того, как пользователь соглашается получать push-уведомления.

Wavesend.push(['onLoad', (api) => {
  Wavesend.addEventHandler('subscribe', (payload) => {
    console.log('Triggered event: subscribe');
  });
}]);

Событие отписки

Выполняется после отмены регистрации устройства для получения уведомлений.

Wavesend.push(['onLoad', (api) => {
  Wavesend.addEventHandler('unsubscribe', (payload) => {
    console.log('Triggered event: unsubscribe');
  });
}]);

События виджета подписки

Отслеживайте отображение виджета запроса на подписку.

Wavesend.push(['onLoad', (api) => {
  // Выполняется при отображении виджета запроса на подписку
  Wavesend.addEventHandler('show-subscription-widget', (payload) => {
    console.log('Triggered event: show-subscription-widget');
  });

  // Выполняется при скрытии виджета запроса на подписку
  Wavesend.addEventHandler('hide-subscription-widget', (payload) => {
    console.log('Triggered event: hide-subscription-widget');
  });
}]);

События диалогового окна запроса разрешений на уведомления

Отслеживайте отображение нативного диалогового окна подписки.

Wavesend.push(['onLoad', function (api) {
  // Выполняется при отображении диалогового окна разрешений
  Wavesend.addEventHandler('show-notification-permission-dialog', (payload) => {
    console.log('Triggered event: show-notification-permission-dialog');
  });

  // Выполняется при скрытии диалогового окна разрешений с одним из трех возможных статусов:
  // 1. default - диалоговое окно закрыто
  // 2. granted - разрешение предоставлено
  // 3. denied - в разрешении отказано
  Wavesend.addEventHandler('hide-notification-permission-dialog', (payload) => {
    console.log('Triggered event: hide-notification-permission-dialog', payload.permission);
  });
}]);

События разрешений

Проверяйте статус разрешения на push-уведомления при инициализации SDK; отслеживайте обновление этого статуса всякий раз, когда оно происходит.

Wavesend.push(['onLoad', (api) => {
  // Выполняется во время инициализации SDK, если 'autoSubscribe: false' и/или если пользователь игнорирует запрос на push-уведомления.
  Wavesend.addEventHandler('permission-default', (payload) => {
    console.log('Triggered event: permission-default');
  });

  // Выполняется во время инициализации SDK, если уведомления заблокированы, или как только пользователь блокирует push-уведомления.
  Wavesend.addEventHandler('permission-denied', (payload) => {
    console.log('Triggered event: permission-denied');
  });

  // Выполняется во время инициализации SDK, если уведомления разрешены, или как только пользователь разрешает push-уведомления.
  Wavesend.addEventHandler('permission-granted', (payload) => {
    console.log('Triggered event: permission-granted');
  });
}]);

Событие получения push-уведомления

Отслеживайте доставку push-уведомлений на устройство.

Wavesend.push(['onLoad', (api) => {
  // Выполняется при отображении push-уведомления.
  Wavesend.addEventHandler('receive-push', (payload) => {
    console.log('Triggered event: receive-push', payload.notification);
  });
}]);

События уведомлений

Отслеживайте, открыто или закрыто push-уведомление пользователем.

Wavesend.push(['onLoad', (api) => {
  // Выполняется, когда пользователь нажимает на уведомление.
  Wavesend.addEventHandler('open-notification', (payload) => {
    console.log('Triggered event: open-notification', payload.notification);
  });

  // Выполняется, когда пользователь закрывает push-уведомление.
  Wavesend.addEventHandler('hide-notification', (payload) => {
    console.log('Triggered event: hide-notification', payload.notification);
  });
}]);

События Inbox

Отслеживайте уведомления, отправленные в Inbox.

Wavesend.push(['onLoad', (api) => {
  // Выполняется ServiceWorker'ом после того, как сообщение для Inbox получено и сохранено в indexedDB.
  Wavesend.addEventHandler('receive-inbox-message', (payload) => {
    console.log('Triggered event: receive-inbox-message', payload.message);
  });

  // Выполняется после автоматического обновления Inbox во время загрузки страницы.
  Wavesend.addEventHandler('update-inbox-messages', (payload) => {
    console.log('Triggered event: receive-inbox-message', payload.messages);
  });
}]);

События кастомного всплывающего окна подписки

Подробнее об обработке событий кастомного всплывающего окна подписки читайте в руководстве по событиям кастомного всплывающего окна подписки.

API

После инициализации Web Push SDK вы можете выполнять следующие вызовы к Wavesend API. Все методы возвращают объекты Promise.

Wavesend.push((api) => {
  // Установка Tags для пользователя
  api.setTags({
    'Tag Name 1': 'value1',
    'Tag Name 2': 'value2'
  });

  // Получение Tags пользователя с сервера
  api.getTags();

  // Регистрация ID пользователя
  api.registerUser('myUserID');

  // Регистрация email пользователя
  api.registerEmail('<user_email>');

  // Отправка Event
  api.postEvent('myEventName', {attributeName: 'attributeValue'});

   // Отписаться от уведомлений
  api.unregisterDevice();
});

Пример отправки Tags в Wavesend:

Wavesend.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('успешно');
      }
      else {
        console.warn('пропущенные теги:', skipped);
      }
    })
    .catch((err) => {
      console.error('ошибка setTags:', err);
    });
});

Инкремент значения Tag

Чтобы инкрементировать значение числового Tag, используйте параметр operation со значением ‘increment’ следующим образом:

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

Добавление значений в Tag

Чтобы добавить новые значения в существующий списочный Tag, используйте параметр operation со значением ‘append’ следующим образом:

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

Удаление значения из Tag

Чтобы удалить значение из списочного Tag, используйте параметр operation со значением ‘remove’ следующим образом:

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

Публичные методы

Caution

Обратите внимание, что автоматическая подписка недоступна для пользователей Safari. Рассмотрите возможность подписки пользователей Safari на push-уведомления путем вызова метода Wavesend.subscribe().

Wavesend.subscribe()

Этот метод используется для запроса у пользователя разрешения на push-уведомления. Если пользователь уже подписан, выполнение метода прекращается.

Если пользователь еще не подписан на push-уведомления:

1. Запрашивается разрешение на push-уведомления.

2. Если пользователь разрешает уведомления, срабатывает событие onSubscribe.

Wavesend.subscribe() выполняется автоматически, если при инициализации SDK установлено autoSubscribe: true.

Вызовите этот метод, если вы решили вручную запрашивать у пользователя подписку на push-уведомления, используя параметр autoSubscribe: false при инициализации:

<button onclick="Wavesend.subscribe()">Subscribe</button>
<script>
  Wavesend.push(['onSubscribe', (api) => {
    console.log('Пользователь успешно подписан');
  }]);
</script>

Wavesend.unsubscribe()

1. Выполняется метод /unregisterDevice.
2. Срабатывает событие onUnsubscribe.

<button onclick="Wavesend.unsubscribe()">Unsubscribe</button>
<script type="text/javascript">
  Wavesend.push(['onUnsubscribe', (api) => {
    console.log('Пользователь успешно отписан');
  }]);
</script>

Wavesend.isSubscribed()

Проверяет, подписан ли пользователь, и возвращает флаг true/false.

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

Wavesend.getHWID()

Возвращает HWID Wavesend.

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

Wavesend.getPushToken()

Возвращает push token, если он доступен.

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

Wavesend.getUserId()

Возвращает User ID, если он доступен.

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

Wavesend.getParams()

Возвращает список следующих параметров:

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

Wavesend.isAvailableNotifications()

Проверяет, поддерживает ли браузер Wavesend WebSDK 3.0, возвращает ‘true’ или ‘false’.

Wavesend.isAvailableNotifications() // true/false

Методы InboxMessages

messagesWithNoActionPerformedCount(): Promise<number>

Возвращает количество открытых сообщений.

Wavesend.pwinbox.messagesWithNoActionPerformedCount()
  .then((count) => {
    console.log(`Открыто ${count} сообщений`);
  });

unreadMessagesCount()

Возвращает количество непрочитанных сообщений.

Wavesend.pwinbox.unreadMessagesCount()
  .then((count) => {
    console.log(`Непрочитано ${count} сообщений`);
  });

messagesCount(): Promise<number>

Возвращает общее количество сообщений.

Wavesend.pwinbox.messagesCount()
  .then((count) => {
    console.log(`${count} сообщений`);
  });

loadMessages(): Promise<Array>

Загружает список неудаленных сообщений.

Wavesend.pwinbox.loadMessages()
  .then(() => {
    console.log('Сообщения были загружены');
  });

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

Помечает сообщения как прочитанные по Inbox_Ids.

Wavesend.pwinbox.readMessagesWithCodes(codes)
  .then(() => {
    console.log('Сообщения были прочитаны');
  });

performActionForMessageWithCode(code: string): Promise<void>

Выполняет действие, назначенное сообщению, и помечает сообщение как прочитанное.

Wavesend.pwinbox.performActionForMessageWithCode(code)
  .then(() => {
    console.log('Действие было выполнено');
  });

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

Помечает сообщения как удаленные.

Wavesend.pwinbox.deleteMessagesWithCodes([code])
  .then(() => {
    console.log('Сообщения были удалены');
  });

syncMessages(): Promise<void>

Синхронизирует сообщения с сервером.

Wavesend.pwinbox.syncMessages()
  .then(() => {
    console.log('Сообщения были синхронизированы');
  });

Поддержка Progressive Web App (PWA)

Чтобы интегрировать Wavesend в ваше Progressive Web Application (PWA), выполните следующие шаги.

1. Скопируйте путь к вашему файлу Service Worker:

if ('serviceWorker' in navigator) {
  window.addEventListener('load', () => {
    navigator.serviceWorker.register('/service-worker.js') // <- URL вашего service worker
  });
}

Затем используйте параметр serviceWorkerUrl при инициализации WebSDK следующим образом:

var Wavesend = Wavesend || [];
Wavesend.push(['init', {
  logLevel: 'error',
  applicationCode: 'XXXXX-XXXXX',
  safariWebsitePushID: 'web.com.example.domain',
  defaultNotificationTitle: 'Wavesend',
  defaultNotificationImage: 'https://yoursite.com/img/logo-medium.png',
  serviceWorkerUrl: '/service-worker.js', // <- URL вашего service worker
}]);

WebSDK не регистрирует новый Service Worker немедленно; Service Worker регистрируется по необходимости:

• когда устройство получает push token (при регистрации устройства или повторной подписке),
• когда push token удаляется (при удалении устройства из базы пользователей).

Это ускоряет загрузку ваших страниц за счет сокращения количества запросов к серверу.

Браузеры не позволяют регистрировать два разных Service Worker одновременно (подробнее: https://github.com/w3c/ServiceWorker/issues/921), поэтому для корректной работы вашего PWA необходимо зарегистрировать общий Service Worker для вашей кодовой базы и кодовой базы Wavesend.

2. Добавьте следующую строку в ваш Service Worker (в начало или в конец, это не имеет значения):

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

Таким образом вы включаете получение и обработку push-уведомлений, отправляемых через сервисы Wavesend, для вашего Service Worker.

Note

Wavesend не повлияет на вашу кодовую базу. Вы всегда можете ознакомиться с нашим Service Worker по адресу https://github.com/Pushwoosh/web-push-notifications.

Установка через Google Tag Manager

Note

Прежде чем добавлять скрипт в Google Tag Manager, убедитесь, что вы выполнили шаги 1-4 этого руководства!

Используйте следующий код в вашем Google Tag Manager для инициализации Wavesend SDK. Создайте кастомный HTML-тег и вставьте код ниже. Обязательно измените ваш Wavesend Application Code, Safari Website ID и URL изображения для уведомлений по умолчанию. Также установите высокий приоритет срабатывания тега (например, 100) и активируйте его на всех страницах. См. скриншот ниже.

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