Closed mpodwysocki closed 1 year ago
Scheduled 7/13 2p-4p PDT
Great work, @mpodwysocki!
Just one thing to discuss: for me, Web Push API is more related to «Web App» rather to a «Browser» (which is just an entry point for user experience, and hopefully we’ll have browserless installations of PWAs in the future - like enterprise usecase for the managed devices). After the webapp installation, there is no longer [visible] browser involved.
To sum up: do you consider other than «browser» prefix for API namings for Web Push scenario?
Disclaimer: I’m not a Board member, just a Web Push / PWA enthusiast from Microsoft :)
On a technical topic: it would be cool to have a sample of «create installation» code for Web Push to make sure that it covers all API specifics.
Do I understand correctly that in that case a deviceToken
is endpoint
of the subscription object received after registration on the client and persisted in a separate (non NH-specific) storage by the developer?
Thank you for starting the process for approval of the client library for your Azure service. Thorough review of your client library ensures that your APIs are consistent with the guidelines and the consumers of your client library have a consistently good experience when using Azure.
The Architecture Board reviews Track 2 libraries only. If your library does not meet this requirement, please reach out to Architecture Board before creating the issue.
Please reference our review process guidelines to understand what is being asked for in the issue template.
Before submitting, ensure you adjust the title of the issue appropriately.
Note that the required material must be included before a meeting can be scheduled.
Contacts and Timeline
About the Service
About the client library
Step 1: Champion Scenarios
Azure Notification Hubs provide a scaled-out push engine that enables you to send notifications to any platform (Apple, Amazon Kindle, Android, Baidu, Web, Windows, etc.) from any back-end (cloud or on-premises). Notification Hubs works great for both enterprise and consumer scenarios. Here are a few example scenarios:
The following are the champion scenarios:
Champion Scenario 1 - Authentication and Initialization
Azure Notification Hubs currently only supports Shared Access Signature to authenticate clients to the service. This includes the following permission levels: Listen, Manage, Send.
Listen allows for a client to register itself via the Registration and Installations API. Send allows for the client to send notifications to devices using the send* APIs. Finally, Manage allows the user to do Registration and Installation management, such as queries.
Champion Scenario 2 - Create an Installation
An Installation is a more modern way of expressing a device and its associated metadata in Notification Hubs. This is expressed natively in JSON instead of the Atom+XML of the Registration APIs and adds additional features such as an Installation ID and User ID which can be used for targeting a device. In addition, it also supports templates built into the installation itself instead of being separate in the Registration APIs.
Each device type has its own factory method to create an installation:
createAdmInstallation
createAppleInstallation
createBaiduInstallation
createBrowserInstallation
createFirebaseLegacyInstallation
createWindowsInstallation
NOTE: Notification Hubs does not support the V1 Firebase API.
Update an Existing Installation via Patch
An installation can be updated in two ways, via a
createOrUupdateInstallation
method which overwrites the existing installation, or usingupdateInstallation
which uses the JSON Patch RFC6902 Specification. In this instance, we will use the PATCH semantics to update an installation.Create or Update a Registration
The Registrations API is also supported using this library. Support for all platforms and templates are also supported.
To create a registration, you use the appropriate factory method per registration type for regular or template registrations.
createAdmRegistrationDescription
|createAdmTemplateRegistration
createAppleRegistrationDescription
|createAppleTemplateRegistrationDescription
createBrowserRegistrationDescription
|createBrowserTemplateRegistrationDescription
createFcmRegistrationDescription
|createFcmTemplateRegistration
createWindowsRegistrationDescription
|createWindowsTemplateRegistration
NOTE: There are classes and factory methods for Google Cloud Messaging (GCM) and Windows Phone (MPNS) which are both deprecated and should only be used for registration list operations.
Query Registrations
Registrations be queried either by listing all registrations which supports OData queries for
$filter
and$top
withlistRegistrations
or by tag via thelistRegistrationsByTag
method. For example we can query for those that have the APNS device token of the following:Send a Direct Notification
Notification Hubs can be used to send notifications to Apple, Amazon, Android, Browsers via Web Push and Windows devices. Notifications can be sent to individual devices using Direct Send when given the device unique ID from the Platform Notification Service (PNS). These messages contain a body, headers to send to the PNS, content-type and platform type.
For debugging purposes, Enable Test Send is exposed via the options.
Support for creating messages is via the factory methods:
createAdmMessage
createAppleMessage
createBaiduMessage
createBrowserMessage
createFirebaseLegacyMessage
createTemplateMessage
createWindowsBadgeMessage
createWindowsTileMessage
createWindowsToastMessage
createWindowsRawMessage
NOTE In the future, we are considering message builders which will be more opinionated in creating messages for each platform with specific features such as Apple's, Firebase's, or Windows' message formats in future beta releases.
Send Notification to an Audience
In addition to supporting sending to a specific device, you can use tags to enrich your device for targeting. Via the
sendNotification
method, you can send a list of tags which then does a "Logical Or" of the tags, or you can specify a tag expression using&&
and||
for conditional checks.Get Notification Details from a Notification
If the developer is using the Standard SKU and above, they can get detailed results of each notification. The notification ID is sent back as a location header which is then parsed. This notification ID can then be used to query the backend using the
getNotificationOutcomeDetails
method. Currently this is an operation that could support long polling but for early beta does not. Detailed information can be found in the REST API Get Notification Telemetry DetailsStep 2: Quickstart Samples (Optional)
Each code snippet is also found in the
samples-dev
but is also here for posterity.Create Installation Full Code
Update An Installation
Create or Update a Registration
Send a Direct Notification and Get Notification Details
Send Notification to an Audience and Get Notification Details
List Registrations
List Registrations by Tag
Thank you for your submission!