Перейти к содержанию
Руководства пользователяПоддержка Запросить демо Войти
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
    apiToken: 'XXXXXXX', //  Device API Token
    safariWebsitePushID: 'web.com.example.domain', //  уникальная строка в формате reverse-domain, полученная на вашем портале Apple Developer. Требуется только если вы отправляете push-уведомления в браузер Safari
    defaultNotificationTitle: 'Pushwoosh', // устанавливает заголовок по умолчанию для push-уведомлений
    defaultNotificationImage: 'https://yoursite.com/img/logo-medium.png', // URL к пользовательскому изображению уведомления
    autoSubscribe: false, // или true. Если true, предлагает пользователю подписаться на пуши при инициализации SDK
    subscribeWidget: {
      enable: true
    },
    userId: 'user_id', // опционально, установите пользовательский ID
    tags: {
        'Name': 'John Smith'     // опционально, установите пользовательские теги
    }
}]);
</script>

Web popups

Anchor link to

Добавьте webPopups в ваш объект init, чтобы включить кампании Web popup на вашем сайте.

webPopups: {
  enable: true,
},

Кампании Web popup отображают оверлеи, которые вы настраиваете в панели управления, такие как промо-акции, объявления или формы для сбора лидов. В отличие от пользовательского всплывающего окна подписки (subscribePopup), которое обрабатывает только подписку на веб-пуши, кампании Web popup могут отображать любой настроенный вами контент. Для настройки в панели управления см. Обзор Web popups.

Кнопка подписки на пуши

Anchor link to

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

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

Anchor link to

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

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

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 загружен!');
}]);

Чтобы отследить корректную инициализацию 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

Anchor link to

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

Anchor link to

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

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

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

Anchor link to

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

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

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

Anchor link to

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

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');
  });
}]);

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

Anchor link to

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

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);
  });
}]);

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

Anchor link to

Проверка статуса разрешения на 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');
  });
}]);

Событие получения пуша (receive push)

Anchor link to

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

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

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

Anchor link to

Отслеживание, открыто или закрыто 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

Anchor link to

Отслеживание уведомлений, отправленных в 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);
  });
}]);

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

Anchor link to

Для получения подробной информации об обработке событий кастомного всплывающего окна подписки, пожалуйста, обратитесь к Руководству по событиям кастомного всплывающего окна подписки.

API

Anchor link to

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

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


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


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


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


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


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


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


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


  // Установить язык устройства (переопределяет значение в теге "Language")
  api.setLanguage('es');


  // Альтернативно, мульти-регистрация пользователя с устройствами и каналами
  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 для 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('Мульти-регистрация успешна:', response);
  })
  .catch((error) => {
    console.error('Ошибка мульти-регистрации:', 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('успешно');
      }
      else {
        console.warn('пропущенные теги:', skipped);
      }
    })
    .catch((err) => {
      console.error('ошибка setTags:', err);
    });
});

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

Anchor link to

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

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

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

Anchor link to

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

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

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

Anchor link to

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

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

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

Anchor link to

Pushwoosh.subscribe()

Этот метод используется для запроса разрешения пользователя на 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()

  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} сообщений открыто`);
  });

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

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

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. Создайте тег Custom HTML и вставьте код ниже. Убедитесь, что вы изменили ваш код приложения Pushwoosh, 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>