https://github.com/web-push-libs/web-push-csharp
Web Push library for C#
https://github.com/web-push-libs/web-push-csharp
Last synced: about 1 year ago
JSON representation
Web Push library for C#
- Host: GitHub
- URL: https://github.com/web-push-libs/web-push-csharp
- Owner: web-push-libs
- License: mpl-2.0
- Created: 2016-12-21T01:28:03.000Z (over 9 years ago)
- Default Branch: master
- Last Pushed: 2024-02-06T08:41:38.000Z (over 2 years ago)
- Last Synced: 2025-03-15T08:09:16.443Z (over 1 year ago)
- Language: C#
- Size: 122 KB
- Stars: 433
- Watchers: 29
- Forks: 107
- Open Issues: 22
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
web-push-csharp
# Why
Web push requires that push messages triggered from a backend be done via the
[Web Push Protocol](https://tools.ietf.org/html/draft-ietf-webpush-protocol)
and if you want to send data with your push message, you must also encrypt
that data according to the [Message Encryption for Web Push spec](https://tools.ietf.org/html/draft-ietf-webpush-encryption).
This package makes it easy to send messages and will also handle legacy support
for browsers relying on GCM for message sending / delivery.
# Install
Installation is simple, just install via NuGet.
Install-Package WebPush
# Demo Project
There is a ASP.NET MVC Core demo project located [here](https://github.com/coryjthompson/WebPushDemo)
# Usage
The common use case for this library is an application server using
a GCM API key and VAPID keys.
```csharp
using WebPush;
var pushEndpoint = @"https://fcm.googleapis.com/fcm/send/efz_TLX_rLU:APA91bE6U0iybLYvv0F3mf6uDLB6....";
var p256dh = @"BKK18ZjtENC4jdhAAg9OfJacySQiDVcXMamy3SKKy7FwJcI5E0DKO9v4V2Pb8NnAPN4EVdmhO............";
var auth = @"fkJatBBEl...............";
var subject = @"mailto:example@example.com";
var publicKey = @"BDjASz8kkVBQJgWcD05uX3VxIs_gSHyuS023jnBoHBgUbg8zIJvTSQytR8MP4Z3-kzcGNVnM...............";
var privateKey = @"mryM-krWj_6IsIMGsd8wNFXGBxnx...............";
var subscription = new PushSubscription(pushEndpoint, p256dh, auth);
var vapidDetails = new VapidDetails(subject, publicKey, privateKey);
//var gcmAPIKey = @"[your key here]";
var webPushClient = new WebPushClient();
try
{
await webPushClient.SendNotificationAsync(subscription, "payload", vapidDetails);
//await webPushClient.SendNotificationAsync(subscription, "payload", gcmAPIKey);
}
catch (WebPushException exception)
{
Console.WriteLine("Http STATUS code" + exception.StatusCode);
}
```
# API Reference
## SendNotificationAsync(pushSubscription, payload, vapidDetails|gcmAPIKey|options, cancellationToken)
```csharp
var subscription = new PushSubscription(pushEndpoint, p256dh, auth);
var options = new Dictionary();
options["vapidDetails"] = new VapidDetails(subject, publicKey, privateKey);
//options["gcmAPIKey"] = @"[your key here]";
var webPushClient = new WebPushClient();
try
{
webPushClient.SendNotificationAsync(subscription, "payload", options);
}
catch (WebPushException exception)
{
Console.WriteLine("Http STATUS code" + exception.StatusCode);
}
```
> **Note:** `SendNotificationAsync()` you don't need to define a payload, and this
method will work without a GCM API Key and / or VAPID keys if the push service
supports it.
### Input
**Push Subscription**
The first argument must be an PushSubscription object containing the details for a push
subscription.
**Payload**
The payload is optional, but if set, will be the data sent with a push
message.
This must be a *string*
> **Note:** In order to encrypt the *payload*, the *pushSubscription* **must**
have a *keys* object with *p256dh* and *auth* values.
**Options**
Options is an optional argument that if defined should be an Dictionary containing
any of the following values defined, although none of them are required.
- **gcmAPIKey** can be a GCM API key to be used for this request and this
request only. This overrides any API key set via `setGCMAPIKey()`.
- **vapidDetails** should be a VapidDetails object with *subject*, *publicKey* and
*privateKey* values defined. These values should follow the [VAPID Spec](https://tools.ietf.org/html/draft-thomson-webpush-vapid).
- **TTL** is a value in seconds that describes how long a push message is
retained by the push service (by default, four weeks).
- **headers** is an object with all the extra headers you want to add to the request.
## GenerateVapidKeys()
```csharp
VapidDetails vapidKeys = VapidHelper.GenerateVapidKeys();
// Prints 2 URL Safe Base64 Encoded Strings
Console.WriteLine("Public {0}", vapidKeys.PublicKey);
Console.WriteLine("Private {0}", vapidKeys.PrivateKey);
```
### Input
None.
### Returns
Returns a VapidDetails object with **PublicKey** and **PrivateKey** values populated which are
URL Safe Base64 encoded strings.
> **Note:** You should create these keys once, store them and use them for all
> future messages you send.
## SetGCMAPIKey(apiKey)
```csharp
webPushClient.SetGCMAPIKey(@"your-gcm-key");
```
### Input
This method expects the GCM API key that is linked to the `gcm_sender_id ` in
your web app manifest.
You can use a GCM API Key from the Google Developer Console or the
*Cloud Messaging* tab under a Firebase Project.
### Returns
None.
## GetVapidHeaders(audience, subject, publicKey, privateKey, expiration)
```csharp
Uri uri = new Uri(subscription.Endpoint);
string audience = uri.Scheme + Uri.SchemeDelimiter + uri.Host;
Dictionary vapidHeaders = VapidHelper.GetVapidHeaders(
audience,
@"mailto: example@example.com",
publicKey,
privateKey
);
```
The *GetVapidHeaders()* method will take in the values needed to create
an Authorization and Crypto-Key header.
### Input
The `GetVapidHeaders()` method expects the following input:
- *audience*: the origin of the **push service**.
- *subject*: the mailto or URL for your application.
- *publicKey*: the VAPID public key.
- *privateKey*: the VAPID private key.
### Returns
This method returns a Dictionary intented to be headers of a web request. It will contain the following keys:
- *Authorization*
- *Crypto-Key*.
# Browser Support
Browser
Push without Payload
Push with Payload
VAPID
Notes
Chrome
✓ v42+
✓ v50+
✓ v52+
In v51 and less, the `gcm_sender_id` is needed to get a push subscription.
Firefox
✓ v44+
✓ v44+
✓ v46+
Opera
✓ v39+ Android *
✓ v42+ Desktop
✓ v39+ Android *
✓ v42+ Desktop
✓ v42+ Desktop
* The `gcm_sender_id` is needed to get a push subscription.
Edge
✓ v17+
✓ v17+
✓ v17+
Safari
✗
✗
✗
Samsung Internet Browser
✓ v4.0.10-53+
✗
✗
The `gcm_sender_id` is needed to get a push subscription.
# Help
**Service Worker Cookbook**
The [Service Worker Cookbook](https://serviceworke.rs/) is full of Web Push
examples.
# Credits
- Ported from https://github.com/web-push-libs/web-push.
- Original Encryption code from https://github.com/LogicSoftware/WebPushEncryption