Skip to content

Commit a7a1039

Browse files
Added core concepts section to readme
1 parent 8a3e95b commit a7a1039

File tree

1 file changed

+43
-0
lines changed

1 file changed

+43
-0
lines changed

README.md

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -51,6 +51,49 @@ targets: [
5151

5252
## Usage
5353

54+
### Terminology and Core Concepts
55+
56+
If you are unfamiliar with the WebPush standard, we suggest you first familiarize yourself with the following core concepts:
57+
58+
<details>
59+
<summary><strong>Subscriber</strong></summary>
60+
61+
A **Subscriber** represents a device that has opted in to receive push messages from your service.
62+
63+
> [!IMPORTANT]
64+
> A subscriber should not be conflated with a user — a single user may be logged in on multiple devices, while a subscriber may be shared by multiple users on a single device. It is up to you to manage this complexity and ensure user information remains secure across session boundaries by registering, unregistering, and updating the subscriber when a user logs in or out.
65+
66+
</details>
67+
68+
<details>
69+
<summary><strong>Application Server</strong></summary>
70+
71+
The **Application Server** is a server you run to manage subscriptions and send push notifications. The actual servers that perform these roles may be different, but they must all use the same VAPID keys to function correctly.
72+
73+
> [!CAUTION]
74+
> Using a VAPID key that wasn't registered with a subscription <strong>will</strong> result in push messages failing to reach their subscribers.
75+
76+
</details>
77+
78+
<details>
79+
<summary><strong>VAPID Key</strong></summary>
80+
81+
**VAPID**, or _Voluntary Application Server Identification_, describes a standard for letting your application server introduce itself at time of subscription registration so that the subscription returned back to you may only be used by your service, and can't be shared with other unrelated services.
82+
83+
This is made possible by generating a VAPID key pair to represent your server with. At time of registration, the public key is shared with the browser, and the subscription that is returned is locked to this key. When sending a push message, the private key is used to identify your application server to the push service so that it knows who you are before forwarding messages to subscribers.
84+
85+
> [!CAUTION]
86+
> It is important to note that you should strive to use the same key for as long as possible for a given subscriber — you won't be able to send messages to existing subscribers if you ever regenerate this key, so keep it secure!
87+
88+
</details>
89+
90+
<details>
91+
<summary><strong>Push Service</strong></summary>
92+
93+
A **Push Service** is run by browsers to coordinate delivery of messages to subscribers on your behalf.
94+
95+
</details>
96+
5497
### Generating Keys
5598

5699
Before integrating WebPush into your server, you must generate one time VAPID keys to identify your server to push services with. To help we this, we provide `vapid-key-generator`, which you can install and use as needed:

0 commit comments

Comments
 (0)