Web push SDK 3.0

Интеграция

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

pushwoosh-service-worker.js

Разместите все эти файлы в корневом каталоге вашего сайта верхнего уровня.

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

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

<script type="text/javascript" src="//cdn.pushwoosh.com/webpush/v3/pushwoosh-web-notifications.js" async></script>

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

<script type="text/javascript">
var Pushwoosh = Pushwoosh || [];
Pushwoosh.push(['init', {
    logLevel: 'info', // возможные значения: error, info, debug
    applicationCode: 'XXXXX-XXXXX', // код вашего приложения из панели управления Pushwoosh
    apiToken: 'XXXXXXX', //  Device API Token
    safariWebsitePushID: 'web.com.example.domain', // уникальная строка в формате reverse-domain, полученная на вашем портале разработчика Apple. Требуется только если вы отправляете push-уведомления в браузер Safari
    defaultNotificationTitle: 'Pushwoosh', // устанавливает заголовок по умолчанию для 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'     // необязательно, установите пользовательские теги
    }
}]);
</script>

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Pushwoosh.push(['onLoad', (api) => {
  function onEventNameHandler() {
    console.log('Сработало событие: event-name!');
  }

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

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

События SDK

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

Pushwoosh.push(['onLoad', (api) => {
  Pushwoosh.addEventHandler('subscribe', (payload) => {
    console.log('Сработало событие: subscribe');
  });
}]);

Событие отписки (unsubscribe)

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

Pushwoosh.push(['onLoad', (api) => {
  Pushwoosh.addEventHandler('unsubscribe', (payload) => {
    console.log('Сработало событие: unsubscribe');
  });
}]);

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

Отслеживание отображения виджета запроса на подписку (Subscription Prompt).

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

События папки «Входящие» (Inbox)

Отслеживание уведомлений, отправленных в папку «Входящие» (Inbox).

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

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

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

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

API

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

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

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

  // Зарегистрировать User ID
  api.registerUser('myUserID');

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

  // Отправить событие (Event)
  api.postEvent('myEventName', {attributeName: 'attributeValue'});

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

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

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

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

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

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

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

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

Удаление значения тега

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

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

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

Pushwoosh.subscribe()

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

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

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

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

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

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

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

Pushwoosh.unsubscribe()

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

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

Pushwoosh.isSubscribed()

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

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

Pushwoosh.getHWID()

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

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

Pushwoosh.getPushToken()

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

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

Pushwoosh.getUserId()

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

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

Pushwoosh.getParams()

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

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

Pushwoosh.isAvailableNotifications()

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

Pushwoosh.isAvailableNotifications() // true/false

Методы InboxMessages

messagesWithNoActionPerformedCount(): Promise<number>

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

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

unreadMessagesCount()

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

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

messagesCount(): Promise<number>

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

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

loadMessages(): Promise<Array>

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

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

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

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

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

performActionForMessageWithCode(code: string): Promise<void>

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

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

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

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

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

syncMessages(): Promise<void>

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

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

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

Чтобы интегрировать Pushwoosh в ваше 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 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 вашего service worker
}]);

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

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

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

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

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

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

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

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

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

<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>