# @pushplatform/web-sdk 中文文档

规范地址：https://npmcn.com/package/%40pushplatform/web-sdk/

版本：0\.3\.0
npm 元数据更新时间：2026-11-02T06:05:31.620Z
中文译文更新时间：2026-11-02T06:13:20.366Z
软件包许可：MIT

本文由上游 README 机器翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40pushplatform/web-sdk
原文对照：https://npmcn.com/package/%40pushplatform/web-sdk/?lang=original
项目主页：https://github.com/pushplatform/pushpilot-sdk-web#readme
源码仓库：https://github.com/pushplatform/pushpilot-sdk-web

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：403 kB，25 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=22\.14\.0
- 运行依赖：0 个
- 首次发布：2026-10-12T08:26:51.117Z
- 最新版本发布：2026-11-02T06:05:31.367Z
- 已发布版本数：5（近 12 个月 5 个）

## 中文简介

PushPilotдлясайтов:Web推,подпискаиотписка,обработканажатийнауведомления

## 安装

```sh
npm install @pushplatform/web-sdk
```

也可以使用：`pnpm add @pushplatform/web-sdk`、`yarn add @pushplatform/web-sdk`、`bun add @pushplatform/web-sdk`

## README

# PushPilot Web SDK

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

## Установка

```sh
npm install @pushplatform/web-sdk@0.2.0
```

```js
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`：

```sh
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。

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

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

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

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

```js
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`． 工人разместите как описано выше。

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

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

```js
const { PushPilot } = window.PushPilot;
```

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

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

工人должен находиться на来源сайта。Файл `/pushpilot-sw.js` позволяет范围 `/`;для `/shop/sw.js` стандартный scope - `/shop/`． Текущая страница должна находиться находиться этом范围。Более широкий范围требует заголовка [`Service-Worker-Allowed`](https://developer.mozilla.org/en-US/docs/Web/API/ServiceWorkerContainer/register) ответе工人。

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

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

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

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

```json
{"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://developer.mozilla.org/en-US/docs/Web/API/Push_API#browser_compatibility).
-   В生产нужны HTTPS для сайта \* API。Для локальной разработки допустимы `http://localhost` и `http://127.0.0.1`.
-   НWeb推动даiOS / iPadOS 16.4 +оступенвеб——приложениям,добавленнымнадомашний экран。 [УсловияWebKit](https://webkit.org/blog/13878/web-push-for-web-apps-on-ios-and-ipados/).
-   Нужендоступный `localStorage`． Один экземпляр SDK использует одно приложение настранице;не переключайте их после инициализации。
-   Только， прежнем режиме `browserAuth: true`：浏览器凭证действует 7 суток。 `renewInstallationCredential()` заменяет действующую凭据。Длявосстановленияпросроченнойилиутраченной凭据 идля `login(userId, identityProof)` нужен доверенный сервер вашего сайта。 [Конфигурация \* методы](https://github.com/pushplatform/pushpilot-sdk-web/blob/main/docs/API.md).
-   SDK регистрирует经典worker。Существующий模块工作者требует адаптации регистрации на стороне сайта。Обновление工人может ждать закрытия вкладок； согласуйтеего `push` и `notificationclick` обработчики r . PushPilot。
-   Успешный `subscribe()` подтверждает регистрацию подписки \* api。Доставка \* показ уведомлениязависятотсервера,推动——сервиса,ОСибраузера;этот ответ их не подтверждает。

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

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

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

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

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

-   [Конфигурация \* API](https://github.com/pushplatform/pushpilot-sdk-web/blob/main/docs/API.md).
-   [Пример сайта： NPM script标签](https://github.com/pushplatform/pushpilot-sdk-web/tree/main/example).
-   [Настройка браузерного API PushPilot](https://github.com/pushplatform/pushpilot-server/blob/main/docs/WEB_BROWSER_AUTH.md).

Лицензия: [麻省理工学院](https://github.com/pushplatform/pushpilot-sdk-web/blob/main/LICENSE).

## 常见问题

### @pushplatform/web-sdk 是什么？

PushPilotдлясайтов:Web推,подпискаиотписка,обработканажатийнауведомления

### 如何安装 @pushplatform/web-sdk？

在项目目录运行 npm install @pushplatform/web-sdk，或使用 pnpm add / yarn add / bun add。

### @pushplatform/web-sdk 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @pushplatform/web-sdk 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @pushplatform/web-sdk 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22\.14\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @pushplatform/web-sdk 可以商用吗？

@pushplatform/web-sdk 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @pushplatform/web-sdk 还在维护吗？

最新版本 0\.3\.0 发布于 2026/11/02（1 天前）；至今共发布 5 个版本，其中过去 12 个月发布了 5 个；首次发布于 2026/10/12。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。