Übersicht über die Windows-Pushbenachrichtigungsdienste (Windows Push Notification Services, WNS)
Mithilfe des Windows-Pushbenachrichtigungsdiensts (WNS) können Drittanbieterentwickler*innen Popup-, Kachel-, Signalupdates und unformatierte Updates von ihren eigenen Clouddiensten aus senden. Dadurch steht ein Mechanismus zur Verfügung, mit dem Sie Ihren Benutzern auf energieeffiziente und verlässliche Weise neue Updates bereitstellen können.
Funktionsweise
Das folgende Diagramm zeigt den vollständigen Datenfluss zum Senden einer Pushbenachrichtigung. Sie umfasst die folgenden Schritte:
- Ihre App fordert einen Pushbenachrichtigungskanal von WNS an.
- Windows fordert WNS auf, einen Benachrichtigungskanal zu erstellen. Dieser Kanal wird in Form eines URI (Uniform Resource Identifier) an das aufrufende Gerät zurückgegeben.
- WNS gibt den URI des Benachrichtigungskanals an Ihre App zurück.
- Ihre App sendet den URI an Ihren eigenen Clouddienst. Anschließend speichern Sie den URI in Ihrem eigenen Clouddienst, damit Sie beim Senden von Benachrichtigungen auf diesen zugreifen können. Der URI ist eine Schnittstelle zwischen Ihrer eigenen App und Ihrem eigenen Dienst. Es liegt in Ihrer Verantwortung, diese Schnittstelle mit sicheren Webstandards zu implementieren.
- Wenn Ihr Clouddienst über ein zu sendendes Update verfügt, benachrichtigt er WNS mithilfe des Kanal-URI. Dazu wird eine HTTP POST-Anforderung über SSL (Secure Sockets Layer) ausgegeben, einschließlich der Benachrichtigungsnutzdaten. Für diesen Schritt ist eine Authentifizierung erforderlich.
- WNS empfängt die Anforderung und leitet die Benachrichtigung an das entsprechende Gerät weiter.
Registrieren Ihrer App und Empfangen der Anmeldeinformationen für Ihren Clouddienst
Um Benachrichtigungen mithilfe von WNS senden zu können, muss Ihre App zunächst beim Dashboard des Store registriert werden. Dieser Vorgang wird hier erläutert.
Anfordern eines Benachrichtigungskanals
Wenn eine App, die Pushbenachrichtigungen empfangen kann, ausgeführt wird, muss sie zuerst einen Benachrichtigungskanal über CreatePushNotificationChannelForApplicationAsync anfordern. Eine vollständige Erläuterung und Beispielcode finden Sie unter Anfordern, Erstellen und Speichern eines Benachrichtigungskanals. Diese API gibt einen Kanal-URI zurück, der eindeutig mit der aufrufenden Anwendung und deren Kachel verknüpft ist und über den alle Benachrichtigungstypen gesendet werden können.
Nachdem die App erfolgreich einen Kanal-URI erstellt hat, sendet sie ihn zusammen mit allen App-spezifischen Metadaten, die diesem URI zugeordnet werden sollen, an den Clouddienst.
Wichtige Hinweise
- Wir garantieren nicht, dass der Benachrichtigungskanal-URI für eine App immer gleich bleibt. Es wird empfohlen, dass die App bei jeder Ausführung einen neuen Kanal anfordert und den Dienst aktualisiert, wenn sich der URI ändert. Entwickler*innen sollten den Kanal-URI niemals ändern und als Blackbox-Zeichenfolge betrachten. Derzeit laufen Kanal-URIs nach 30 Tagen ab. Wenn Ihre Windows 10-App den Kanal regelmäßig im Hintergrund erneuert, können Sie das Beispiel für Push- und regelmäßige Benachrichtigungen für Windows 8.1 herunterladen und den Quellcode und/oder das Muster wiederverwenden.
- Die Schnittstelle zwischen dem Clouddienst und der Client-App wird von den Entwickler*innen implementiert. Es wird empfohlen, dass die App einen Authentifizierungsprozess beim eigenen Dienst durchläuft und Daten über ein sicheres Protokoll wie HTTPS überträgt.
- Es ist wichtig, dass der Clouddienst immer sicherstellt, dass der Kanal-URI die Domäne „notify.windows.com“ verwendet. Der Dienst sollte niemals Pushbenachrichtigungen an einen Kanal in einer anderen Domäne senden. Wenn der Rückruf für Ihre App jemals kompromittiert wird, könnte ein Angreifer einen Kanal-URI an WNS senden. Ohne Überprüfung der Domäne gibt Ihr Clouddienst unter Umständen unwissentlich Informationen an diesen Angreifer weiter. Die Unterdomäne des Kanal-URI kann sich ändern und sollte beim Validieren des Kanal-URI nicht berücksichtigt werden.
- Wenn Ihr Clouddienst versucht, eine Benachrichtigung an einen abgelaufenen Kanal zu übermitteln, gibt WNS den Antwortcode 410 zurück. Als Reaktion auf diesen Code sollte Ihr Dienst nicht mehr versuchen, Benachrichtigungen an diesen URI zu senden.
Authentifizieren Ihres Clouddiensts
Zum Senden einer Benachrichtigung muss der Clouddienst über WNS authentifiziert werden. Der erste Schritt in diesem Prozess erfolgt, wenn Sie Ihre App beim Microsoft Store-Dashboard registrieren. Während des Registrierungsprozesses erhält Ihre App eine Paketsicherheits-ID (Package Security Identifier, SID) und einen geheimen Schlüssel. Diese Informationen werden von Ihrem Clouddienst verwendet, um sich bei WNS zu authentifizieren.
Das WNS-Authentifizierungsschema wird mithilfe des Clientanmeldeinformationsprofils aus dem OAuth 2.0-Protokoll implementiert. Der Clouddienst authentifiziert sich mit WNS, indem er seine Anmeldeinformationen (Paket-SID und geheimer Schlüssel) bereitstellt. Im Gegenzug empfängt er ein Zugriffstoken. Dieses Zugriffstoken ermöglicht es einem Clouddienst, eine Benachrichtigung zu senden. Das Token ist bei jeder an den WNS gesendeten Benachrichtigungsanforderung erforderlich.
Die allgemeine Informationskette sieht folgendermaßen aus:
- Der Clouddienst sendet seine Anmeldeinformationen über HTTPS gemäß dem OAuth 2.0-Protokoll an WNS. Dadurch wird der Dienst bei WNS authentifiziert.
- WNS gibt ein Zugriffstoken zurück, wenn die Authentifizierung erfolgreich war. Dieses Zugriffstoken wird bis zu seinem Ablauf in allen weiteren Benachrichtigungsanforderungen verwendet.
Bei der Authentifizierung bei WNS sendet der Clouddienst eine HTTP-Anforderung über Secure Sockets Layer (SSL). Die Parameter werden im Format „application/x-www-for-urlencoded“ angegeben. Geben Sie die Paket-SID im Feld „client_id“ und den geheimen Schlüssel im Feld „client_secret“ an, wie im folgenden Beispiel gezeigt. Ausführliche Informationen zur Syntax finden Sie in der Referenz zur Zugriffstokenanforderung.
Hinweis
Hierbei handelt es sich lediglich um ein Beispiel. Diesen Code können Sie nicht einfach in Ihren Code einfügen und dort erfolgreich verwenden.
POST /accesstoken.srf HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: https://login.live.com
Content-Length: 211
grant_type=client_credentials&client_id=ms-app%3a%2f%2fS-1-15-2-2972962901-2322836549-3722629029-1345238579-3987825745-2155616079-650196962&client_secret=Vex8L9WOFZuj95euaLrvSH7XyoDhLJc7&scope=notify.windows.com
WNS authentifiziert den Clouddienst und sendet bei erfolgreicher Ausführung die Antwort „200 OK“. Das Zugriffstoken wird in den Parametern zurückgegeben, die im Textkörper der HTTP-Antwort enthalten sind, wobei der Medientyp „application/json“ verwendet wird. Nachdem Ihr Dienst das Zugriffstoken empfangen hat, können Sie Benachrichtigungen senden.
Das folgende Beispiel zeigt eine erfolgreiche Authentifizierungsantwort, einschließlich des Zugriffstokens. Ausführliche Informationen zur Syntax finden Sie unter Anforderungs- und Antwortheader des Pushbenachrichtigungsdiensts.
HTTP/1.1 200 OK
Cache-Control: no-store
Content-Length: 422
Content-Type: application/json
{
"access_token":"EgAcAQMAAAAALYAAY/c+Huwi3Fv4Ck10UrKNmtxRO6Njk2MgA=",
"token_type":"bearer"
}
Wichtige Hinweise
- Das in diesem Verfahren unterstützte OAuth 2.0-Protokoll folgt der Entwurfsversion V16.
- Die Request for Comments (RFC) für OAuth verwendet den Begriff „Client“ für den Clouddienst.
- Möglicherweise gibt es Änderungen an diesem Verfahren, wenn der OAuth-Entwurf fertiggestellt ist.
- Das Zugriffstoken kann für mehrere Benachrichtigungsanforderungen wiederverwendet werden. Dadurch muss sich der Clouddienst nur einmal authentifizieren, um viele Benachrichtigungen zu senden. Wenn das Zugriffstoken jedoch abläuft, muss sich der Clouddienst erneut authentifizieren, um ein neues Zugriffstoken zu empfangen.
Senden einer Benachrichtigung
Mithilfe des Kanal-URI kann der Clouddienst eine Benachrichtigung senden, wenn er über ein Update für den oder die Benutzer*in verfügt.
Das oben beschriebene Zugriffstoken kann für mehrere Benachrichtigungsanforderungen wiederverwendet werden. Der Cloudserver ist nicht erforderlich, um für jede Benachrichtigung ein neues Zugriffstoken anzufordern. Wenn das Zugriffstoken abgelaufen ist, gibt die Benachrichtigungsanforderung einen Fehler zurück. Es wird empfohlen, nicht mehr als einmal zu versuchen, die Benachrichtigung erneut zu senden, wenn das Zugriffstoken abgelehnt wird. Wenn dieser Fehler auftritt, müssen Sie ein neues Zugriffstoken anfordern und die Benachrichtigung erneut senden. Den genauen Fehlercode finden Sie unter Antwortcodes für Pushbenachrichtigungen.
Der Clouddienst sendet eine HTTP POST-Anforderung an den Kanal-URI. Diese Anforderung muss über SSL erfolgen und enthält die erforderlichen Header und die Benachrichtigungsnutzdaten. Der Autorisierungsheader muss das empfangene Zugriffstoken für die Autorisierung enthalten.
Hier wird eine Beispielanforderung gezeigt. Ausführliche Informationen zur Syntax finden Sie unter Antwortcodes für Pushbenachrichtigungen.
Ausführliche Informationen zum Zusammenstellen der Benachrichtigungsnutzdaten finden Sie unter Schnellstart: Senden einer Pushbenachrichtigung. Die Nutzdaten einer Kachel-, Popup- oder Signal-Pushbenachrichtigung wird als XML-Inhalt bereitgestellt, der dem jeweiligen definierten Schema für adaptive Kacheln oder dem Schema für Legacykacheln entspricht. Für die Nutzdaten einer unformatierten Benachrichtigung gibt es keine festgelegte Struktur. Sie wird strikt von der App definiert.
POST https://cloud.notify.windows.com/?token=AQE%bU%2fSjZOCvRjjpILow%3d%3d HTTP/1.1 Content-Type: text/xml X-WNS-Type: wns/tile Authorization: Bearer EgAcAQMAAAAALYAAY/c+Huwi3Fv4Ck10UrKNmtxRO6Njk2MgA= Host: cloud.notify.windows.com Content-Length: 24 <body> ....WNS antwortet, um zu signalisieren, dass die Benachrichtigung empfangen wurde und bei der nächsten Gelegenheit übermittelt wird. WNS sendet jedoch keine End-to-End-Bestätigung, dass Ihre Benachrichtigung vom Gerät oder von der Anwendung empfangen wurde.
Dieses Diagramm veranschaulicht den Datenfluss:
Wichtige Hinweise
- WNS garantiert nicht die Zuverlässigkeit oder Latenz einer Benachrichtigung.
- Benachrichtigungen sollten niemals vertrauliche oder personenbezogene Daten enthalten.
- Zum Senden einer Benachrichtigung muss sich der Clouddienst zuerst bei WNS authentifizieren und ein Zugriffstoken empfangen.
- Mit einem Zugriffstoken kann ein Clouddienst nur Benachrichtigungen an die App senden, für die das Token erstellt wurde. Ein Zugriffstoken kann nicht zum Senden von Benachrichtigungen für mehrere Apps verwendet werden. Wenn Ihr Clouddienst mehrere Apps unterstützt, muss er daher das richtige Zugriffstoken für die App angeben, wenn eine Pushbenachrichtigung an verschiedene Kanal-URIs gesendet wird.
- Wenn das Gerät offline ist, speichert WNS standardmäßig eine Benachrichtigung jeder Art (Kachel, Signal, Popup) für jeden Kanal-URI, jedoch keine unformatierten Benachrichtigungen.
- Falls der Benachrichtigungsinhalt für den oder die Benutzer*in personalisiert wird, empfiehlt WNS, dass der Clouddienst diese Updates sofort sendet, wenn sie empfangen werden. Beispiele für dieses Szenario sind Updates für Social-Media-Feeds, Instant-Messaging-Einladungen, Benachrichtigungen für neue Nachrichten oder Warnungen. Es können auch Szenarios vorliegen, in denen dasselbe generische Update häufig an eine große Teilmenge der Benutzer*innen übermittelt wird. z. B. Wetter-, Aktien- und Nachrichtenupdates. Gemäß den WNS-Richtlinien sollten diese Updates höchstens alle 30 Minuten gesendet werden. Der oder die Endbenutzer*in oder WNS kann häufigere Routineupdates als unangemessen einstufen.
- Die Windows-Benachrichtigungsplattform unterhält eine regelmäßige Datenverbindung mit WNS, um den Socket aktiv und fehlerfrei zu halten. Wenn keine Anwendungen vorhanden sind, die Benachrichtigungskanäle anfordern oder verwenden, wird der Socket nicht erstellt.
Ablauf von Kachel- und Signalbenachrichtigungen
Kachel- und Signalbenachrichtigungen laufen standardmäßig drei Tage nach dem Herunterladen ab. Wenn eine Benachrichtigung abläuft, wird der Inhalt aus der Kachel oder Warteschlange entfernt und dem oder der Benutzer*in nicht mehr angezeigt. Es empfiehlt sich, für alle Kachel- und Signalbenachrichtigungen eine für die jeweilige App angemessene Ablaufzeit festzulegen, damit der Inhalt der Kachel nicht länger als nötig gespeichert wird. Eine explizite Ablaufzeit ist für Inhalte mit definierter Lebensdauer unerlässlich. Dadurch wird auch sichergestellt, dass veraltete Inhalte entfernt werden, wenn Ihr Clouddienst das Senden von Benachrichtigungen beendet oder der bzw. die Benutzer*in die Verbindung zum Netzwerk für einen längeren Zeitraum trennt.
Ihr Clouddienst kann eine Ablaufzeit für jede Benachrichtigung festlegen, indem der X-WNS-TTL-HTTP-Header so festgelegt wird, dass er die Dauer (in Sekunden) angibt, die Ihre Benachrichtigung nach dem Senden gültig bleibt. Weitere Informationen finden Sie unter Anforderungs- und Antwortheader des Pushbenachrichtigungsdiensts.
So können Sie z. B. während eines aktiven Börsenhandelstages die Ablaufzeit für ein Aktienkursupdate auf doppelt so hoch wie das Sendeintervall festlegen (z. B. eine Stunde nach Erhalt, wenn Benachrichtigungen alle halbe Stunde gesendet werden). Ein weiteres Beispiel: Für eine Nachrichten-App könnte festgelegt werden, dass ein Tag eine geeignete Ablaufzeit für ein tägliches Update auf der Nachrichtenkachel ist.
Pushbenachrichtigungen und Stromsparmodus
Der Stromsparmodus verlängert die Akkulaufzeit, indem die Hintergrundaktivität auf dem Gerät eingeschränkt wird. Mit Windows 10 können Benutzer*innen den Stromsparmodus so einstellen, dass er automatisch aktiviert wird, wenn der Akkustand einen angegebenen Schwellenwert unterschreitet. Wenn der Stromsparmodus aktiv ist, wird der Empfang von Pushbenachrichtigungen deaktiviert, um Strom zu sparen. Es gibt jedoch einige Ausnahmen. Mit den folgenden Windows 10-Einstellungen für den Stromsparmodus (in der App Einstellungen) kann Ihre App Pushbenachrichtigungen auch dann empfangen, wenn der Stromsparmodus aktiv ist.
- Pushbenachrichtigungen im Stromsparmodus von jeder App zulassen: Mit dieser Einstellung können alle Apps Pushbenachrichtigungen empfangen, während der Stromsparmodus aktiv ist. Beachten Sie, dass diese Einstellung nur für Desktopeditionen von Windows 10 gilt (Home, Pro, Enterprise und Education).
- Immer zulassen: Mit dieser Einstellung können bestimmte Apps im Hintergrund ausgeführt werden, während der Stromsparmodus aktiv ist, und auch Pushbenachrichtigungen empfangen. Diese Liste wird manuell durch die Benutzer*innen verwaltet.
Es gibt keine Möglichkeit, den Status dieser beiden Einstellungen zu überprüfen, aber Sie können den Status des Stromsparmodus überprüfen. Verwenden Sie unter Windows 10 die Eigenschaft EnergySaverStatus, um den Status des Stromsparmodus zu überprüfen. Ihre App kann auch das Ereignis EnergySaverStatusChanged verwenden, um Änderungen am Stromsparmodus zu lauschen.
Wenn Ihre App stark von Pushbenachrichtigungen abhängt, sollten Benutzer*innen darüber informiert werden, dass sie möglicherweise keine Benachrichtigungen empfangen, während der Stromsparmodus aktiv ist. Dadurch wissen diese, dass sie die Einstellungen für den Stromsparmodus anpassen müssten. Mit dem URI-Schema für die Einstellungen für den Stromsparmodus unter Windows 10 (ms-settings:batterysaver-settings) können Sie einen praktischen Link zur App „Einstellungen“ bereitstellen.
Tipp
Wenn Sie Benutzer*innen mit einer Benachrichtigung über die Einstellungen für den Stromsparmodus informieren, sollte es diesen möglich sein, die zukünftige Anzeige dieser Benachrichtigung zu unterdrücken. Das Kontrollkästchen dontAskMeAgainBox im folgenden Beispiel speichert beispielsweise die Einstellung des Benutzers in LocalSettings.
Das folgende Beispiel zeigt, wie Sie unter Windows 10 überprüfen, ob der Stromsparmodus aktiv ist. In diesem Beispiel wird der oder die Benutzer*in benachrichtigt, und die App „Einstellungen“ wird mit den Einstellungen für den Stromsparmodus gestartet. Durch dontAskAgainSetting kann der oder die Benutzer*in die Benachrichtigung unterdrücken, wenn er oder sie nicht erneut benachrichtigt werden möchte.
using System;
using Windows.UI.Xaml;
using Windows.UI.Xaml.Controls;
using Windows.UI.Xaml.Navigation;
using Windows.System;
using Windows.System.Power;
...
...
async public void CheckForEnergySaving()
{
//Get reminder preference from LocalSettings
bool dontAskAgain;
var localSettings = Windows.Storage.ApplicationData.Current.LocalSettings;
object dontAskSetting = localSettings.Values["dontAskAgainSetting"];
if (dontAskSetting == null)
{ // Setting does not exist
dontAskAgain = false;
}
else
{ // Retrieve setting value
dontAskAgain = Convert.ToBoolean(dontAskSetting);
}
// Check if battery saver is on and that it's okay to raise dialog
if ((PowerManager.EnergySaverStatus == EnergySaverStatus.On)
&& (dontAskAgain == false))
{
// Check dialog results
ContentDialogResult dialogResult = await saveEnergyDialog.ShowAsync();
if (dialogResult == ContentDialogResult.Primary)
{
// Launch battery saver settings (settings are available only when a battery is present)
await Launcher.LaunchUriAsync(new Uri("ms-settings:batterysaver-settings"));
}
// Save reminder preference
if (dontAskAgainBox.IsChecked == true)
{ // Don't raise dialog again
localSettings.Values["dontAskAgainSetting"] = "true";
}
}
}
#include <winrt/Windows.Foundation.h>
#include <winrt/Windows.Storage.h>
#include <winrt/Windows.System.h>
#include <winrt/Windows.System.Power.h>
#include <winrt/Windows.UI.Xaml.h>
#include <winrt/Windows.UI.Xaml.Controls.h>
#include <winrt/Windows.UI.Xaml.Navigation.h>
using namespace winrt;
using namespace winrt::Windows::Foundation;
using namespace winrt::Windows::Storage;
using namespace winrt::Windows::System;
using namespace winrt::Windows::System::Power;
using namespace winrt::Windows::UI::Xaml;
using namespace winrt::Windows::UI::Xaml::Controls;
using namespace winrt::Windows::UI::Xaml::Navigation;
...
winrt::fire_and_forget CheckForEnergySaving()
{
// Get reminder preference from LocalSettings.
bool dontAskAgain{ false };
auto localSettings = ApplicationData::Current().LocalSettings();
IInspectable dontAskSetting = localSettings.Values().Lookup(L"dontAskAgainSetting");
if (!dontAskSetting)
{
// Setting doesn't exist.
dontAskAgain = false;
}
else
{
// Retrieve setting value
dontAskAgain = winrt::unbox_value<bool>(dontAskSetting);
}
// Check whether battery saver is on, and whether it's okay to raise dialog.
if ((PowerManager::EnergySaverStatus() == EnergySaverStatus::On) && (!dontAskAgain))
{
// Check dialog results.
ContentDialogResult dialogResult = co_await saveEnergyDialog().ShowAsync();
if (dialogResult == ContentDialogResult::Primary)
{
// Launch battery saver settings
// (settings are available only when a battery is present).
co_await Launcher::LaunchUriAsync(Uri(L"ms-settings:batterysaver-settings"));
}
// Save reminder preference.
if (dontAskAgainBox().IsChecked())
{
// Don't raise the dialog again.
localSettings.Values().Insert(L"dontAskAgainSetting", winrt::box_value(true));
}
}
}
Dies ist der XAML-Code für ContentDialog in diesem Beispiel.
<ContentDialog x:Name="saveEnergyDialog"
PrimaryButtonText="Open battery saver settings"
SecondaryButtonText="Ignore"
Title="Battery saver is on.">
<StackPanel>
<TextBlock TextWrapping="WrapWholeWords">
<LineBreak/><Run>Battery saver is on and you may
not receive push notifications.</Run><LineBreak/>
<LineBreak/><Run>You can choose to allow this app to work normally
while in battery saver, including receiving push notifications.</Run>
<LineBreak/>
</TextBlock>
<CheckBox x:Name="dontAskAgainBox" Content="OK, got it."/>
</StackPanel>
</ContentDialog>
Zugehörige Themen
- Senden einer lokalen Kachelbenachrichtigung
- Schnellstart: Senden einer Pushbenachrichtigung
- Aktualisieren eines Signals über Pushbenachrichtigungen
- Anfordern, Erstellen und Speichern eines Benachrichtigungskanals
- Abfangen von Benachrichtigungen für ausgeführte Anwendungen
- Authentifizieren beim Windows-Pushbenachrichtigungsdienst (WNS)
- Anforderungs- und Antwortheader des Pushbenachrichtigungsdiensts
- Richtlinien und Prüfliste für Pushbenachrichtigungen
- Unformatierte Benachrichtigungen
Windows developer
Feedback
Bald verfügbar: Im Laufe des Jahres 2024 werden wir GitHub-Issues stufenweise als Feedbackmechanismus für Inhalte abbauen und durch ein neues Feedbacksystem ersetzen. Weitere Informationen finden Sie unter https://aka.ms/ContentUserFeedback.
Feedback senden und anzeigen für