什么是 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 文件名
包含 OneSignalimportScripts
行的 .js
文件名。如果您没有更改文件名,则为:OneSignalSDKWorker.js
如果您的服务器强制文件使用小写,您可以将文件名设置为 onesignalsdkworker.js
Service Worker 注册作用域
Service Worker 控制的域上路径。这应该是一个您永远不会链接给用户并且现在或将来永远不会从中托管任何页面的路径。常见路径示例:/push/onesignal/
,作用域可以是相同路径或更深的路径,如:/push/onesignal/js/
OneSignal Service Worker 迁移指南
仅在您已经使用 OneSignal、拥有大量网页推送订阅者并且想要更改 OneSignal 的 Service Worker 设置时才遵循此部分。本指南仅适用于目前在网站上使用 OneSignal
并希望将
OneSignalSDKWorker.js
文件移动到不同路径或
作用域的客户。- 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.
importScript
like the following in in your current Service Worker.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.