跳转到主要内容

​
什么是 Service Worker？

Service Worker 如何工作

Service Worker 是一个独立于主浏览器线程运行的后台脚本。它支持推送通知、离线体验和后台同步等功能。当用户订阅网页推送时，Service Worker 会被下载并持续存在，即使用户离开页面，也能随时接收推送通知。

​
从其他推送提供商迁移

如果您正在切换提供商，请查看我们的指南： 从其他服务迁移到 OneSignal

​
如何集成 OneSignal 的 Service Worker

OneSignal Service Worker 文件通过我们的插件自动添加，您不应该手动将这些文件添加到您的站点。请返回到网页推送设置。

​
下载 .js 文件

从 OneSignal 仪表板下载 OneSignalSDKWorker.js 文件，或在此下载 OneSignal Service Worker 文件。

​
将 .js 文件上传到您的服务器

我们的 SDK 默认在您站点的根目录中查找 OneSignalSDKWorker.js 文件，例如：https://yoursite.com/OneSignalSDKWorker.js 您可以简单地将此文件上传到站点的根目录，然后返回到网页推送设置指南进行后续步骤。但是，建议将此 OneSignalSDKWorker.js 文件放在永远不会链接给用户的子目录路径中，如 https://yoursite.com/push/onesignal/OneSignalSDKWorker.js。 您可以将此文件放在根目录中，但它可能与您现在拥有或将来可能添加的其他 Service Worker 冲突。此外，文件应放在永远不会更改的永久位置路径中。一旦 Service Worker 在浏览器中注册，就很难更改。

​
Service Worker 配置

现在您需要告诉 OneSignal 在哪里找到 Service Worker 并设置注册作用域。默认情况下，OneSignal SDK 将其设置为您站点的根目录。如果您将 OneSignalSDKWorker.js 文件放在站点根目录中，如 https://yoursite.com/OneSignalSDKWorker.js，则无需进一步操作。但是，建议将 Service Worker 文件放在具有永远不会使用的注册作用域的子目录中，如 /push/onesignal/。 OneSignal service worker 文件 OneSignalSDKWorker.js 必须满足以下要求：
  • 文件必须可公开访问，这意味着您应该能够在浏览器中导航到该文件并查看代码。
  • 文件必须以 content-type 为 application/javascript; charset=utf-8 的方式提供。
  • 文件必须指向相同的站点来源（您的站点域）。不允许指向不同来源的 Service Worker。不允许 CDN 或子域。
  • Typical site setup
  • Custom Code Setup

​
典型站点设置 - Service Worker 配置

In the OneSignal dashboard, go to your App’s Settings > Push Platforms > Web在高级部分，切换自定义 service worker 路径和文件名开关并输入您的数据。

​
Service Worker 文件路径

OneSignal Service Worker 文件可用的目录。如果 Service Worker 位于：https://yoursite.com/push/onesignal/OneSignalSDKWorker.js，那么路径是：/push/onesignal/

​
主 Service Worker 和更新器 Service Worker 文件名

包含 OneSignal importScripts 行的 .js 文件名。如果您没有更改文件名，则为：OneSignalSDKWorker.js如果您的服务器强制文件使用小写，您可以将文件名设置为 onesignalsdkworker.js

​
Service Worker 注册作用域

Service Worker 控制的域上路径。这应该是一个您永远不会链接给用户并且现在或将来永远不会从中托管任何页面的路径。常见路径示例：/push/onesignal/，作用域可以是相同路径或更深的路径，如：/push/onesignal/js/

​
OneSignal Service Worker 迁移指南

仅在您已经使用 OneSignal、拥有大量网页推送订阅者并且想要更改 OneSignal 的 Service Worker 设置时才遵循此部分。
本指南仅适用于目前在网站上使用 OneSignal 并希望将 OneSignalSDKWorker.js 文件移动到不同路径或 作用域的客户。
OneSignalSDKWorker.js 文件的迁移步骤 （点击展开） OneSignal 的 Service Worker 默认为根作用域，这可能会为您的网站创建以下问题：
  • Conflict with a PWA
  • Conflict with an AMP setup
  • 与您的缓存 Service Worker 或任何其他需要根作用域的 Service Worker 功能冲突
  • 您的网站有安全要求，不允许第三方 Service Worker 代码在控制用户将访问的页面的作用域上运行。
如果一个或多个适用于您，请遵循此指南。

​
选择 OneSignal Service Worker 作用域

建议您选择一个永远不会链接给用户但仍然清楚其功能的 Service Worker 作用域路径。示例：/push/onesignal/。这样，您的 PWA、AMP 或任何其他缓存 ServiceWorker 可以控制用户查看的页面以正常工作。 可以将多个 Service Worker 放在相同的位置路径中，但必须具有唯一的作用域路径。
  • Option 1: Change scope
  • Option 2: Change filename or location

​
Safely change the OneSignal Service Worker Scope

建议仅在可能的情况下更改作用域，更改 Service Worker 本身的文件名或 位置路径有额外的注意事项。请注意 close attention to both the details of which scenario applies to you as well as each step to ensure you don’t lose subscribers or run into notification display issues

​
Setup Type 1. Default OneSignal Setup - Scope root “/” AND default OneSignalSDKWorker.js Contents

确认您的 OneSignalSDKWorker.js 文件内容与在此下载 OneSignal Service Worker 文件中找到的相同。（不包含您可能需要的任何其他非 OneSignal 代码）在这种情况下，您可以将 OneSignal 作用域更改为您选择的任何内容，以为另一个 Service Worker 放置在根作用域腾出空间。请参见上方自定义您的 Service Worker 集成。
If your OneSignalSDKWorker.js is not hosted on root of your domain today, example you do NOT have it hosted like this: https://mysite.com/OneSignalSDKWorker.js then you MUST keep hosting it with the Service-Worker-Allowed header for an extended period of time. (1 year or more is recommended)如果可能，我们建议在您的后端代码或内部文档中添加注释，以确保它不会被意外删除。

​
Setup Type 2. Uncommon - Scope root “/” AND OneSignalSDKWorker.js (or your configured filename) contains OneSignal + other code or importScripts

This is less common but you may have already done this by following this OneSignal guide “Integrating Multiple Service Workers”. If this setup still meets all your requirements highly recommend keeping your setup as is due to the complex and two phase roll out required break up the merged ServiceWorker file that handles push events.
This section applies if you have OneSignal AND either some other custom code or importScript like the following in in your current Service Worker.
importScripts("https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.sw.js");
//And some other site specific code in the same file example.
importScripts("https://site.com/my-other-service-worker.js");
1

Keep your existing service worker code.

Add a code comment to your existing ServiceWorker file above this line importScripts("https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.sw.js"); to keep it for a extended period of time. (a year or more is recommend, depends on how long you want to keep sending pushes to users who never re-visit your site). Example: // KEEP Until YYYY-MM-DD: Required for pushes to work correctly for users who have not re-visited to migrate to the new OneSignal specific ServiceWorker.
2

Create a new service worker file

Create a new OneSignalSDKWorker.js under a different directory, such as /push/onesignal/ with the following single line of code importScripts("https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.sw.js");
3

Follow the guide on “Customizing Your Service Worker Integration” to change your scope and filename and path.

4

At this point new and returning users will automatically be subscribed to the new OneSignal ServiceWorker.

5

Wait the amount of time (a year or so) as noted in step 1.

6

Follow the OneSignal - “Delete Users” guide to delete users older than the timeline you picked.

7

Remove comment from original service worker

Lastly finally remove the importScripts("https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.sw.js"); line with the comment from your original root ServiceWorker.

​
迁移 OneSignal Service Worker 作用域 - 常见问题

Why must I keep hosting the original ServiceWorker file URL if I change the name or location path?
This is required for those users who have not re-visited your site for the new filename to be picked up. The original ServiceWorker file will be fetched by the browser each time you send a push (if past cache expire time, max cache is 24 hours). You will see a spike in 404 errors returned from your hosting provider when sending a push if the original ServiceWorker file isn’t available. This may result more requests to your server. This also means those users won’t be getting the new OneSignal features and fixes.