Skip to content

Commit b3ef14f

Browse files
v-dirichardsv-dirichards
authored
Merge pull request #253183 from sethmanheim/anh-web
Add browser push notification hubs article
2 parents 5228181 + 39b59b3 commit b3ef14f

File tree

4 files changed

+266
-0
lines changed

4 files changed

+266
-0
lines changed

‎articles/notification-hubs/TOC.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -102,6 +102,8 @@
102102
href: notification-hubs-aspnet-cross-platform-notification.md
103103
- name: Push rich content to devices
104104
href: notification-hubs-aspnet-backend-ios-apple-push-notification-service-apns-rich.md
105+
- name: Send browser push notifications
106+
href: browser-push.md
105107
- name: Send scheduled notifications
106108
href: notification-hubs-send-push-notifications-scheduled.md
107109
- name: Deploy and manage notification hubs using Azure PowerShell

‎articles/notification-hubs/browser-push.md

Lines changed: 264 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,264 @@
1+
---
2+
title: Send browser (web push) notifications with Azure Notification Hubs
3+
description: Learn about support for browser push notifications in Azure Notification Hubs.
4+
services: notification-hubs
5+
documentationcenter: .net
6+
author: sethmanheim
7+
manager: femila
8+
9+
ms.service: notification-hubs
10+
ms.workload: mobile
11+
ms.tgt_pltfrm: mobile-multiple
12+
ms.topic: article
13+
ms.date: 09/29/2023
14+
ms.author: sethm
15+
ms.reviewer: heathertian
16+
ms.lastreviewed: 09/29/2023
17+
---
18+
19+
# Web push notifications with Azure Notification Hubs
20+
21+
This article describes how to send browser push notifications to single users through Azure Notification Hubs.
22+
23+
At a high level, the process is:
24+
25+
1. [Set credentials](#set-credentials):
26+
- [In the Azure portal](#set-credentials-in-azure-portal)
27+
- [Using the REST API](#set-credentials-using-rest-api)
28+
- Using the .NET SDK
29+
30+
2. [Create registrations and installations](#create-registrations-and-installations).
31+
32+
3. [Send push notifications](#send-push-notifications):
33+
- [Direct sends](#create-direct-sends)
34+
- [Batch (audience) sends](#create-audience-sends)
35+
- [Debug/test sends](#create-debugtest-sends)
36+
37+
## Overview
38+
39+
Web push (or browser push) is a type of notification that customers get on their desktop browsers, or in some cases mobile browsers, on a per-website basis.
40+
41+
Azure Notification Hubs now supports [*browser push*](https://developers.google.com/web/ilt/pwa/introduction-to-push-notifications) for all major browsers, including Microsoft Edge, Google Chrome, and Mozilla Firefox. Apple Safari isn't included. For Apple Safari, you can use existing APNS support as described in [Configuring Safari Push Notifications](https://developer.apple.com/library/archive/documentation/NetworkingInternet/Conceptual/NotificationProgrammingGuideForWebsites/PushNotifications/PushNotifications.html#//apple_ref/doc/uid/TP40013225-CH3-SW1), with certificate-based authentication.
42+
43+
Browser push is supported across platforms on devices with the following operating systems and browsers.
44+
45+
Browser push support on laptop computers:
46+
47+
| Operating system | Browsers |
48+
|------------------|---------------------------------------------------------|
49+
| Windows OS | Google Chrome v48+<br>Microsoft Edge v17+<br>Mozilla Firefox v44+<br>Safari v7+<br>Opera v42+ |
50+
| macOS | Chrome v48+<br>Firefox v44+<br>Safari v7+<br>Opera v42+ |
51+
| Linux OS | Chrome v48+<br>Firefox v44+<br>Safari v7+<br>Opera v42+ |
52+
53+
Browser push support on tablet PCs:
54+
55+
| Operating system | Browsers |
56+
|------------------|-------------------------------------------|
57+
| Windows OS | Chrome v48+<br>Firefox v44+<br>Opera v42+ |
58+
| iOS | Not supported. |
59+
| Android OS | Chrome v48+<br>Firefox v44+<br>Opera v42+ |
60+
61+
Browser push support on mobile devices:
62+
63+
| Operating system | Browsers |
64+
|------------------|-------------------------------------------|
65+
| iOS | Not supported. |
66+
| Android OS | Chrome v48+<br>Firefox v44+<br>Opera v42+ |
67+
68+
## Set credentials
69+
70+
To subscribe to browser push notifications on your web site, you can use VAPID keys. You can generate VAPID credentials by using services such as the [VAPID key generator](https://www.attheminute.com/vapid-key-generator/). The credentials should look similar to the following:
71+
72+
```json
73+
{
74+
"location": "South Central US",
75+
"properties": {
76+
"browserCredential": {
77+
"properties": {
78+
"subject": "mailto:[email protected]",
79+
"vapidPublicKey": "some-vapid-public-key",
80+
"vapidPrivateKey":"some-vapid-private-key"
81+
}
82+
}
83+
}
84+
}
85+
```
86+
87+
### Set credentials in Azure portal
88+
89+
You can set credentials for browser push in the Azure portal using the browser credentials.
90+
91+
To set browser push credentials in the portal, follow these steps:
92+
93+
1. In the [Azure portal](https://portal.azure.com), open the **Browser (Web Push)** blade in your notification hub.
94+
95+
[![Screenshot showing the Browser (Web Push) blade in Notification Hubs.](media/browser-push/notification-hubs-browser-web-push.png)](media/browser-push/notification-hubs-browser-web-push.png#lightbox)
96+
97+
1. Enter your existing VAPID keys, or generate a new VAPID key pair using a service such as the [VAPID Key Generator](https://www.attheminute.com/vapid-key-generator/).
98+
99+
1. Select **Save**.
100+
101+
### Set credentials using REST API
102+
103+
You can also set the browser credentials for browser push by using the REST API, such as using the [Create Or Update Hub REST API](/rest/api/notificationhubs/notification-hubs/create-or-update) method, the Azure Resource Manager API, or the V2 RP.
104+
105+
Enter the credentials in this format, providing the subscription ID, resource group, namespace, and notification hub:
106+
107+
```http
108+
https://management.azure.com/subscriptions/{subcription}/resourceGroups/{resource-group}/providers/Microsoft.NotificationHubs/namespaces/{namespace}/notificationHubs/{hub}api-version=2016-03-01
109+
```
110+
111+
## Create registrations and installations
112+
113+
Bulk sends require registrations or installations. You can also use the registrations and installations in debug sends.
114+
115+
The following examples show the registration request body for a native registration, a template registration, and a browser installation.
116+
117+
### Native registration request body
118+
119+
```xml
120+
<?xml version="1.0" encoding="utf-8"?><entry xmlns="http://www.w3.org/2005/Atom"><content type="application/xml"><BrowserRegistrationDescription xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://schemas.microsoft.com/netservices/2010/10/servicebus/connect"><Endpoint></Endpoint><P256DH></P256DH><Auth></Auth></BrowserRegistrationDescription></content></entry>
121+
```
122+
123+
### Browser template registration request body
124+
125+
```xml
126+
<?xml version="1.0" encoding="utf-8"?>
127+
<entry xmlns="http://www.w3.org/2005/Atom">
128+
<content type="application/xml">
129+
<BrowserTemplateRegistrationDescription xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://schemas.microsoft.com/netservices/2010/10/servicebus/connect">
130+
<Endpoint></Endpoint>
131+
<P256DH></P256DH>
132+
<Auth></Auth>
133+
<BodyTemplate><![CDATA[{"title":"asdf","message":"xts"}]]></BodyTemplate>
134+
</BrowserTemplateRegistrationDescription>
135+
</content>
136+
</entry>
137+
```
138+
139+
### Installation request body
140+
141+
```json
142+
{
143+
"installationId": "installation-id",
144+
"platform": "browser",
145+
"pushChannel": {
146+
"endpoint": "",
147+
"p256dh": "",
148+
"auth": ""
149+
}
150+
}
151+
```
152+
153+
### Create native registrations with .NET SDK
154+
155+
To create a native registration, use the following statement:
156+
157+
```csharp
158+
await notificationHubClient.CreateBrowserNativeRegistrationAsync(subscriptionInfo, tagSet);
159+
```
160+
161+
### Create template registrations with .NET SDK
162+
163+
To create a template registration using the .NET SDK, use the following statement:
164+
165+
```csharp
166+
await notificationHubClient.CreateBrowserTemplateRegistrationAsync(subscriptionInfo, template, tagSet);
167+
```
168+
169+
### Create browser installation with .NET SDK
170+
171+
To create a browser installation using the .NET SDK, enter the following code:
172+
173+
```csharp
174+
var browserPushSubscription = new BrowserPushSubscription
175+
{
176+
Endpoint = "",
177+
P256DH = "",
178+
Auth = "",
179+
};
180+
var browserInstallation = new BrowserInstallation
181+
{
182+
InstallationId = installationId,
183+
Tags = tags,
184+
Subscription = browserPushSubscription,
185+
UserId = userId,
186+
ExpirationTime = DateTime.UtcNow.AddDays(1),
187+
};
188+
await notificationHubClient.CreateOrUpdateInstallationAsync(browserInstallation);
189+
```
190+
191+
## Send push notifications
192+
193+
After you [set credentials for browser push](#set-credentials) and [create registrations and installations](#create-registrations-and-installations) for the devices, you're ready to create push notifications. This section describes how to create a notification for a [direct send|](#create-direct-sends), [audience send](#create-audience-sends), and [debug (test) send](#create-debugtest-sends).
194+
195+
### Create direct sends
196+
197+
For a direct send, you'll need the endpoint URI, p25DH key, and auth secret from a browser subscription. For more information about direct send notifications, see [Direct send](/rest/api/notificationhubs/direct-send).
198+
199+
To create a direct send notification, follow these steps:
200+
201+
1. Set the following headers for browser push:
202+
203+
- `ServiceBusNotification-Format - browser`
204+
- `ServiceBusNotification-DeviceHandle - endpoint`: the `endpoint` field from the subscription
205+
- `P256DH`: the `p256dh` field from the subscription
206+
- `Auth`: the `auth` field from the subscription
207+
208+
1. Create the message body. The message body is typically in this format:
209+
210+
```json
211+
{
212+
"title": "Some Title",
213+
"body": "Some body of a message"
214+
}
215+
```
216+
217+
You can specify other fields in the body; for example, `icon`, to change the icon per message.
218+
219+
1. Send the notification.
220+
221+
To create a direct send using the .NET SDK, use this code:
222+
223+
```csharp
224+
var browserSubscriptionEndpoint = "";
225+
var browserPushHeaders = new Dictionary<string, string>
226+
{
227+
{ "P256DH", "" },
228+
{ "Auth", "" },
229+
};
230+
var directSendOutcome = await notificationHubClient.SendDirectNotificationAsync(new BrowserNotification("payload", browserPushHeaders), browserSubscriptionEndpoint);
231+
```
232+
233+
### Create audience sends
234+
235+
For an audience send, use the same `ServiceBus Notification-Format` header used for a direct send, and modify the message payload as desired. Optionally, specify a tag expression using the `ServiceBusNotification-Tags` header. For more information about creating an audience send, see [Send an APNS native notification](/rest/api/notificationhubs/send-apns-native-notification).
236+
237+
To create an audience send using the SDK, use the following statement:
238+
239+
```csharp
240+
var outcome = await notificationHubClient.SendNotificationAsync(new BrowserNotification(payload, tagExpression);
241+
```
242+
243+
### Create debug/test sends
244+
245+
Debug sends are created in the Azure portal and require registrations and installations.
246+
247+
After you [create registrations for the devices](#create-registrations-and-installations), follow these steps to create a debug send notification:
248+
249+
1. In the [Azure portal](https://portal.azure.com), open the **Test Send** blade in your notification hub.
250+
251+
[![Screenshot showing the Test Send blade in a notification hub, for sending a test/debug notification.](media/browser-push/notification-hubs-test-send.png)](media/browser-push/notification-hubs-test-send.png#lightbox)
252+
253+
1. In the **Platform** field, select **Browser**.
254+
255+
1. Specify **Send to Tag Expression**.
256+
257+
1. Modify **Payload** to your desired message.
258+
259+
1. Select **Send**.
260+
261+
## Next steps
262+
263+
- [Find out more about direct sends](/rest/api/notificationhubs/direct-send)
264+
- [Send batches directly to a collection of device handles](/rest/api/notificationhubs/direct-batch-send)

‎articles/notification-hubs/media/browser-push/notification-hubs-browser-web-push.png

75.6 KB
Loading

‎articles/notification-hubs/media/browser-push/notification-hubs-test-send.png

184 KB
Loading

0 commit comments

Comments
 (0)