PushPilot Web SDK

PushPilotподключает网络推动квашемусайту:запрашиваетразрешениепользователя, регистрируетподпискувPushPilot,позволяетотписатьсяиобрабатыватьнажатия науведомления。Работает через NPM или обычный <script>.

Установка

npm install @pushplatform/[email protected]

import { PushPilot } from '@pushplatform/web-sdk';

ПакетвключаетESM, CommonJS,打印稿声明исборкудля脚本标记。 运行时——зависимостейнет。

Настройкасайта

Для подключения нужны：

• HTTPS URL API PushPilot， без /v1 вконце。
• UUIDприложенияPushPilot——тогоже,чтодляiOS和Android。
• Общий бессрочный ключ приложения из консоли。ОннамеренноизвлекаемизJavaScriptиразрешаетрегистрациюустройствиотправкувэтомприложении。
• Разрешённый起源сайтавнастройкахWeb推,например https://shop.example.
• VAPID公钥этого приложения。私人索然乏味的关键иapn / FCM凭证остаютсянасервере。

Настройки находятся приложении→Web推送。Проект * окружение выбирать не нужно。Отдельный шлюз не требуется。

Разместите工人на своём сайте。Для проекта * публичной директорией public：

mkdir -p public
cp node_modules/@pushplatform/web-sdk/dist/service-worker.js public/pushpilot-sw.js

После публикации сайта файл должен открываться по /pushpilot-sw.js сJavaScript MIME类型，без HTML回退。Обновляйте копию worker при обновлении SDK。

Минимальныйпример

Добавьтекнопкинастраницуиподключитефайлприложениячерезваш打包机:

<button id="subscribe" disabled>Разрешить уведомления</button>
<button id="unsubscribe" disabled>Отписаться</button>
<p id="push-status" role="status"></p>

ВфайлеприложениязаменитеURL, UUIDипубличныеключисвоимизначениями:

import { PushPilot } from '@pushplatform/web-sdk';

const subscribe = document.getElementById('subscribe');
const unsubscribe = document.getElementById('unsubscribe');
const output = document.getElementById('push-status');
const showError = error => {
  output.textContent = `${error.code || 'error'}: ${error.message}`;
};

subscribe.onclick = async () => {
  subscribe.disabled = true;
  try {
    // Запрос разрешения вызывается только по нажатию пользователя.
    const permission = await PushPilot.requestPermission();
    if (permission !== 'granted') {
      output.textContent = permission === 'denied'
        ? 'Уведомления запрещены. Разрешите их в настройках сайта в браузере.'
        : 'Запрос закрыт. Нажмите кнопку, чтобы повторить.';
      return;
    }
    await PushPilot.subscribe();
    output.textContent = 'Подписка зарегистрирована в PushPilot';
  } catch (error) { showError(error); }
  finally { subscribe.disabled = false; }
};

unsubscribe.onclick = async () => {
  unsubscribe.disabled = true;
  try {
    await PushPilot.unsubscribe();
    output.textContent = 'Подписка удалена';
  } catch (error) { showError(error); }
  finally { unsubscribe.disabled = false; }
};

async function start() {
  if (!PushPilot.isSupported()) {
    output.textContent = 'Web Push недоступен в этом браузере или на этом origin.';
    return;
  }
  try {
    await PushPilot.initialize({
      apiBaseURL: 'https://api.example.com',
      applicationId: 'YOUR_APPLICATION_UUID',
      apiKey: 'APPLICATION_KEY',
      vapidPublicKey: 'YOUR_PUBLIC_VAPID_KEY',
      serviceWorkerPath: '/pushpilot-sw.js',
      serviceWorkerScope: '/',
    });
    PushPilot.onNotificationClicked(notification => {
      output.textContent = `Открыто уведомление: ${notification.title || notification.id}`;
    });
    subscribe.disabled = false;
    unsubscribe.disabled = false;
    output.textContent = 'PushPilot подключён';
  } catch (error) { showError(error); }
}

start();

initialize() не запрашивает разрешение。При denied повторный вызов кнопкой не изменит настройку браузера；пользовательдолженразрешитьуведомлениявручную。 Ошибки API доступны через error.code и error.context?.status． Неуспешную операцию можно повторить явно。При ошибке API во время отписки SDK сохраняет браузерную подписку для повтора。

Подключение обычным脚本标签

Скопируйте dist/sdk.global.js из установленного пакета， публичную директорию ,сайтанапример /assets/pushpilot/sdk.global.js． 工人разместите как описано выше。

<script src="/assets/pushpilot/sdk.global.js"></script>
<script src="/main.js"></script>

В main.js используйте код примера， заменив строку import на:

const { PushPilot } = window.PushPilot;

Подключайте скрипты после HTML кнопок。打包机и type="module" для этого способа ненужны。

Service worker * переход по нажатию

工人должен находиться на来源сайта。Файл /pushpilot-sw.js позволяет范围 /;для /shop/sw.js стандартный scope - /shop/． Текущая страница должна находиться находиться этом范围。Более широкий范围требует заголовка Service-Worker-Allowed ответе工人。

Если на сайте уже есть经典工作者，скопируйте dist/service-worker.js по адресу /assets/pushpilot/service-worker.js * добавьте * существующий工人：

importScripts('/assets/pushpilot/service-worker.js');

Укажите путь существующего工人 serviceWorkerPath． Не регистрируйте второй 工人：тем же范围。

ДляпереходапонажатиюпередайтURLевданныхуведомления:

{"title":"Заказ готов","body":"Откройте заказ","data":{"url":"/orders/123"}}

工人открываестURLвоего起源илифокусируетужеоткрытуюстраницусэтим URL。Относительныйадресразрешаетсяотносительно范围;внешний или некорректный URL заменяется адресом范围。 custom_data.url такжеподдерживается。

onNotificationClicked() сообщаетсобытиеужеоткрытойиинициализированной странице。Призапускесайтаиззакрытогосостоянияобрабатывайтеадресстраницы иегопараметры:回调послеоткрытияновойстраницынегарантируется。

Поддержка браузеров * ограничения

• Дляустановкипакетачерезnpmиспользуйтеnode . js 22.14 +。Сам SDK выполняется вбраузере。
• Нужны Service Worker, Push API, Notifications API。Проверяйте PushPilot.isSupported() доинициализации:наличиефункцийзависитотбраузера, платформы * настроек пользователя。 Таблица совместимости推送API.
• В生产нужны HTTPS для сайта * API。Для локальной разработки допустимы http://localhost и http://127.0.0.1.
• НWeb推动даiOS / iPadOS 16.4 +оступенвеб——приложениям,добавленнымнадомашний экран。 УсловияWebKit.
• Нужендоступный localStorage． Один экземпляр SDK использует одно приложение настранице;не переключайте их после инициализации。
• Только， прежнем режиме browserAuth: true：浏览器凭证действует 7 суток。 renewInstallationCredential() заменяет действующую凭据。Длявосстановленияпросроченнойилиутраченной凭据 идля login(userId, identityProof) нужен доверенный сервер вашего сайта。 Конфигурация * методы.
• SDK регистрирует经典worker。Существующий模块工作者требует адаптации регистрации на стороне сайта。Обновление工人может ждать закрытия вкладок； согласуйтеего push и notificationclick обработчики r . PushPilot。
• Успешный subscribe() подтверждает регистрацию подписки * api。Доставка * показ уведомлениязависятотсервера,推动——сервиса,ОСибраузера;этот ответ их не подтверждает。

Совместимость

Также доступны именованный экспорт PushPlatform 默认导出。Длянового кодаиспользуйте PushPilot.

По умолчанию SDK обращается /v1/installations 网址：общим ключом приложения。ОдинIDиключиспользуютсянасайте,iOS、Androidисервере。У ключа нет срока действия；отзыв/перевыпуск доступны / консоли。Ключнедаётадминистративныхправидоступакдругимприложениям。

Прежнийрежим browserAuth: true с wbpub_/安装证明сохранёндлясовместимостисуществующихсайтов。Он не нужен для новой модели общего ключа。Егоистечение/更新/ identityProofотносятсятолькокэтому遗产——режиму。

Документация

• Конфигурация * API.
• Пример сайта： NPM script标签.
• Настройка браузерного API PushPilot.

Лицензия: 麻省理工学院.