Перейти к содержанию
Руководства пользователяПоддержка Запросить демо Войти
Pushwoosh.com

Web push SDK 3.0

Интеграция

Anchor link to

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

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

Anchor link to
  • pushwoosh-service-worker.js

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

Anchor link to

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

Anchor link to
  1. Подключите SDK из нашего CDN асинхронно.
<script type="text/javascript" src="//cdn.pushwoosh.com/webpush/v3/pushwoosh-web-notifications.js" async></script>
  1. Инициализируйте Web Push SDK и убедитесь, что инициализация поставлена в очередь до полной загрузки SDK.
<script type="text/javascript">
var Pushwoosh = Pushwoosh || [];
Pushwoosh.push(['init', {
    logLevel: 'info', // возможные значения: error, info, debug
    applicationCode: 'XXXXX-XXXXX', // код вашего приложения из Pushwoosh Control Panel
    apiToken: 'XXXXXXX', //  Device API Token
    safariWebsitePushID: 'web.com.example.domain', //  уникальная строка в формате обратного домена, полученная на вашем Apple Developer Portal. Требуется только если вы отправляете 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', // необязательно, установите пользовательский User ID
    tags: {
        'Name': 'John Smith'     // необязательно, установите пользовательские теги
    }
}]);
</script>

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

Anchor link to

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

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

Anchor link to

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

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

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

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

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

Anchor link to

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

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

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

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

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

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

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


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


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

События SDK

Anchor link to

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

Anchor link to

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

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

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

Anchor link to

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

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

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

Anchor link to

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

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


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

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

Anchor link to

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

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


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

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

Anchor link to

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

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


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


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

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

Anchor link to

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

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

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

Anchor link to

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

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


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

События Inbox

Anchor link to

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

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


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

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

Anchor link to

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

API

Anchor link to

После инициализации 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('user123');


    // Зарегистрировать email пользователя
  api.registerEmail('user@example.com');


  // Зарегистрировать номер SMS
  api.registerSmsNumber('+15551234567');


  // Зарегистрировать номер WhatsApp
  api.registerWhatsappNumber('+1234567890');


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


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


  // Альтернативно: мультирегистрация пользователя с устройствами и каналами
  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

Усовершенствованный метод регистрации, который позволяет регистрировать профиль пользователя с несколькими устройствами и каналами обмена сообщениями в одном вызове API. Этот метод особенно полезен для кросс-платформенных приложений или при реализации омниканальных стратегий обмена сообщениями.

Pushwoosh.push((api) => {
  api.multiRegisterDevice({
    user_id: 'user123',              // Необязательно: идентификатор пользователя
    email: 'user@example.com',       // Необязательно: Email для сообщений по электронной почте
    sms_phone_number: '+1234567890', // Необязательно: номер телефона для SMS (формат E.164)
    whatsapp_phone_number: '+1234567890', // Необязательно: номер WhatsApp (формат E.164)
    kakao_phone_number: '+1234567890',    // Необязательно: номер KakaoTalk (формат E.164)
    language: 'en',                  // Необязательно: код языка (ISO 639-1)
    timezone: 'America/New_York',    // Необязательно: идентификатор часового пояса
    city: 'New York',               // Необязательно: город для таргетинга
    country: 'US',                  // Необязательно: страна для таргетинга
    state: 'NY',                    // Необязательно: штат для таргетинга
    tags: {                         // Необязательно: значения тегов с операциями
      'UserType': {
        operation: TTagOperationSet,     // Установить значение тега (0)
        value: 'Premium'
      },
      'Interests': {
        operation: TTagOperationAppend,  // Добавить к значению тега (1)
        values: ['sports', 'technology']
      },
      'LoginCount': {
        operation: TTagOperationIncrement, // Увеличить значение тега (3)
        value: '1'
      }
    },
    push_devices: [                 // Необязательно: массив push-устройств
      {
        hwid: 'web-device-456',
        platform: TPlatformChrome, // Платформа 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-registration successful:', response);
  })
  .catch((error) => {
    console.error('Multi-registration failed:', error);
  });
});

Типы платформ:

  • TPlatformSafari (10): платформа Safari
  • TPlatformChrome (11): платформа Chrome
  • TPlatformFirefox (12): платформа Firefox

Типы операций с тегами:

  • TTagOperationSet (0): установить значение тега (заменить существующее значение)
  • TTagOperationAppend (1): добавить к значению тега (добавить в список)
  • TTagOperationRemove (2): удалить значение тега (удалить из списка)
  • TTagOperationIncrement (3): увеличить значение тега (числовое увеличение)

Преимущества:

  • Один вызов API: регистрация нескольких устройств и каналов одновременно
  • Атомарная операция: все регистрации либо проходят успешно, либо не проходят вовсе
  • Ориентация на пользователя: связывает все устройства с одним профилем пользователя
  • Расширенная работа с тегами: поддержка сложных операций с тегами
  • Кросс-платформенность: одновременная обработка нескольких платформ

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

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

Anchor link to

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

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

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

Anchor link to

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

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

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

Anchor link to

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

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

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

Anchor link to

Pushwoosh.subscribe()

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

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

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

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

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

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

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

Pushwoosh.unsubscribe()

  1. Выполняется метод /unregisterDevice.
  2. Срабатывает событие 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

Anchor link to

messagesWithNoActionPerformedCount(): Promise<number>

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

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

unreadMessagesCount()

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

Pushwoosh.pwinbox.unreadMessagesCount()
  .then((count) => {
    console.log(`${count} messages unread`);
  });

messagesCount(): Promise<number>

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

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

loadMessages(): Promise<Array>

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

Pushwoosh.pwinbox.loadMessages()
  .then(() => {
    console.log('Messages have been loaded');
  });

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

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

Pushwoosh.pwinbox.readMessagesWithCodes(codes)
  .then(() => {
    console.log('Messages have been read');
  });

performActionForMessageWithCode(code: string): Promise<void>

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

Pushwoosh.pwinbox.performActionForMessageWithCode(code)
  .then(() => {
    console.log('Action has been performed');
  });

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

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

Pushwoosh.pwinbox.deleteMessagesWithCodes([code])
  .then(() => {
    console.log('Messages have been deleted');
  });

syncMessages(): Promise<void>

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

Pushwoosh.pwinbox.syncMessages()
  .then(() => {
    console.log('Messages have been synchronized');
  });

Поддержка Progressive Web App

Anchor link to

Чтобы интегрировать 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

Anchor link to

Используйте следующий код в вашем 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>