Overzicht van Windows Push Notification Services (WNS)

Met de Windows Push Notification Services (WNS) kunnen externe ontwikkelaars toast-, tegel-, badge- en ruwe updates verzenden vanuit hun eigen cloudservice. Dit biedt een mechanisme voor het leveren van nieuwe updates aan uw gebruikers op een energieefficiënte en betrouwbare manier.

Hoe het werkt

In het volgende diagram ziet u de volledige gegevensstroom voor het verzenden van een pushmelding. Dit omvat de volgende stappen:

1. Uw app vraagt een pushmeldingkanaal aan bij WNS.
2. Windows vraagt WNS om een meldingskanaal te maken. Dit kanaal wordt geretourneerd naar het aanroepende apparaat in de vorm van een URI (Uniform Resource Identifier).
3. De URI van het meldingskanaal wordt door WNS geretourneerd naar uw app.
4. Uw app verzendt de URI naar uw eigen cloudservice. Vervolgens slaat u de URI op uw eigen cloudservice op, zodat u toegang hebt tot de URI wanneer u meldingen verzendt. De URI is een interface tussen uw eigen app en uw eigen service; het is uw verantwoordelijkheid om deze interface te implementeren met veilige en veilige webstandaarden.
5. Wanneer uw cloudservice een update heeft om te verzenden, wordt WNS op de hoogte gebracht met behulp van de kanaal-URI. Dit wordt gedaan door een HTTP POST-aanvraag uit te geven, inclusief de nettolading van de melding, via Ssl (Secure Sockets Layer). Voor deze stap is verificatie vereist.
6. WNS ontvangt de aanvraag en stuurt de melding door naar het juiste apparaat.

Uw app registreren en de referenties voor uw cloudservice ontvangen

Voordat u meldingen kunt verzenden met WNS, moet uw app zijn geregistreerd bij het Store-dashboard, zoals hier wordt beschreven.

Een meldingskanaal aanvragen

Wanneer een app die in staat is pushmeldingen te ontvangen wordt uitgevoerd, moet eerst een meldingskanaal worden aangevraagd via de CreatePushNotificationChannelForApplicationAsync. Zie Een meldingskanaal aanvragen, maken en opslaan voor een volledige discussie en voorbeeldcode. Deze API retourneert een kanaal-URI die uniek is gekoppeld aan de aanroepende toepassing en de bijbehorende tegel, en waarmee alle meldingstypen kunnen worden verzonden.

Nadat de app een kanaal-URI heeft gemaakt, wordt deze verzonden naar de cloudservice, samen met alle app-specifieke metagegevens die aan deze URI moeten worden gekoppeld.

Belangrijke opmerkingen

• We garanderen niet dat de URI van het meldingskanaal voor een app altijd hetzelfde blijft. We raden aan dat de app elke keer dat deze wordt uitgevoerd een nieuw kanaal aanvraagt en de service bijwerken wanneer de URI wordt gewijzigd. De ontwikkelaar mag de kanaal-URI nooit wijzigen en moet deze beschouwen als een zwarte-box-tekenreeks. Op dit moment verlopen kanaal-URI's na 30 dagen. Als uw Windows 10-app periodiek zijn kanaal op de achtergrond verlengt, dan kunt u het -voorbeeld voor push- en periodieke meldingen voor Windows 8.1 downloaden en de broncode en/of het patroon dat het demonstreert hergebruiken.
• De interface tussen de cloudservice en de client-app wordt door u, de ontwikkelaar, geïmplementeerd. Het is raadzaam dat de app een verificatieproces met een eigen service doorloopt en gegevens verzendt via een beveiligd protocol, zoals HTTPS.
• Het is belangrijk dat de cloudservice er altijd voor zorgt dat de kanaal-URI gebruikmaakt van het domein 'notify.windows.com'. De service mag nooit pushmeldingen verzenden naar een kanaal op een ander domein. Als de callback voor uw app ooit wordt aangetast, kan een kwaadwillende aanvaller een kanaal-URI verzenden om WNS te spoofen. Zonder het domein te inspecteren, kan uw cloudservice mogelijk informatie openbaar maken aan deze aanvaller. Het subdomein van de kanaal-URI kan worden gewijzigd en moet niet worden overwogen bij het valideren van de kanaal-URI.
• Als uw cloudservice probeert een melding te verzenden naar een verlopen kanaal, retourneert WNS antwoordcode 410. Als reactie op die code mag uw service geen meldingen meer verzenden naar die URI.

Uw cloudservice verifiëren

Als u een melding wilt verzenden, moet de cloudservice worden geverifieerd via WNS. De eerste stap in dit proces vindt plaats wanneer u uw app registreert bij het Microsoft Store-dashboard. Tijdens het registratieproces krijgt uw app een pakketbeveiligings-id (SID) en een geheime sleutel. Deze informatie wordt door uw cloudservice gebruikt voor verificatie met WNS.

Het WNS-verificatieschema wordt geïmplementeerd met behulp van het clientreferentieprofiel van het OAuth 2.0-protocol . De cloudservice verifieert met WNS door de referenties op te geven (pakket-SID en geheime sleutel). In ruil daarvoor ontvangt het een toegangstoken. Met dit toegangstoken kan een cloudservice een melding verzenden. Het token is vereist bij elke meldingsaanvraag die naar de WNS wordt verzonden.

Op hoog niveau is de informatieketen als volgt:

1. De cloudservice verzendt de referenties naar WNS via HTTPS volgens het OAuth 2.0-protocol. Hiermee wordt de service geverifieerd met WNS.
2. WNS retourneert een toegangstoken als de verificatie is geslaagd. Dit toegangstoken wordt gebruikt in alle volgende meldingsaanvragen totdat het verloopt.

In de verificatie met WNS verzendt de cloudservice een HTTP-aanvraag via Ssl (Secure Sockets Layer). De parameters worden opgegeven in de indeling 'application/x-www-for-urlencoded'. Geef uw pakket-SID op in het veld 'client_id' en uw geheime sleutel in het veld 'client_secret', zoals wordt weergegeven in het volgende voorbeeld. Zie voor syntaxisdetails de referentie bij de toegangstokenaanvraag.

 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

De WNS verifieert de cloudservice en verzendt, indien geslaagd, een antwoord van '200 OK'. Het toegangstoken wordt geretourneerd in de parameters die zijn opgenomen in de hoofdtekst van het HTTP-antwoord, met behulp van het mediatype 'application/json'. Nadat uw service het toegangstoken heeft ontvangen, bent u klaar om meldingen te verzenden.

In het volgende voorbeeld ziet u een geslaagd verificatieantwoord, inclusief het toegangstoken. Zie Push Notification Service-aanvraag- en antwoordheaders voor syntaxisdetails.

 HTTP/1.1 200 OK   
 Cache-Control: no-store
 Content-Length: 422
 Content-Type: application/json
 
 {
     "access_token":"EgAcAQMAAAAALYAAY/c+Huwi3Fv4Ck10UrKNmtxRO6Njk2MgA=", 
     "token_type":"bearer"
 }

Belangrijke opmerkingen

• Het OAuth 2.0-protocol dat in deze procedure wordt ondersteund, volgt conceptversie V16.
• De OAuth-aanvraag voor opmerkingen (RFC) gebruikt de term 'client' om te verwijzen naar de cloudservice.
• Deze procedure kan worden gewijzigd wanneer het OAuth-concept is voltooid.
• Het toegangstoken kan opnieuw worden gebruikt voor meerdere meldingsaanvragen. Hierdoor kan de cloudservice slechts één keer verifiëren om veel meldingen te verzenden. Wanneer het toegangstoken echter verloopt, moet de cloudservice opnieuw worden geverifieerd om een nieuw toegangstoken te ontvangen.

Een melding verzenden

Met behulp van de kanaal-URI kan de cloudservice een melding verzenden wanneer deze een update voor de gebruiker heeft.

Het hierboven beschreven toegangstoken kan opnieuw worden gebruikt voor meerdere meldingsaanvragen; de cloudserver is niet vereist om voor elke melding een nieuw toegangstoken aan te vragen. Als het toegangstoken is verlopen, retourneert de meldingsaanvraag een fout. We raden u aan uw melding niet meer dan één keer opnieuw te verzenden als het toegangstoken wordt geweigerd. Als deze fout optreedt, moet u een nieuw toegangstoken aanvragen en de melding opnieuw verzenden. Zie Antwoordcodes voor pushmeldingen voor de exacte foutcode.

1. De cloudservice maakt een HTTP POST naar de kanaal-URI. Deze aanvraag moet worden gedaan via SSL en bevat de benodigde headers en de nettolading van de melding. De autorisatieheader moet het verkregen toegangstoken voor autorisatie bevatten.

   Hier ziet u een voorbeeldaanvraag. Zie Antwoordcodes voor pushmeldingen voor syntaxis.

   Zie Quickstart: Een pushmelding verzendenvoor meer informatie over het samenstellen van de notificatiepayload. De inhoud van een pushmelding voor tegels, meldingen of badges wordt geleverd als XML-inhoud die voldoet aan het respectievelijk gedefinieerde schema voor adaptieve tegels of legacytegel-schema. De nettolading van een onbewerkte melding heeft geen opgegeven structuur. Het is strikt door de app gedefinieerd.

    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>
    ....
   

2. WNS reageert om aan te geven dat de melding is ontvangen en zal worden bezorgd bij de eerstvolgende beschikbare gelegenheid. WNS biedt echter geen end-to-end bevestiging dat uw melding is ontvangen door het apparaat of de toepassing.

Dit diagram illustreert de gegevensstroom:

Belangrijke opmerkingen

• WNS garandeert geen betrouwbaarheid of latentie van een melding.
• Meldingen mogen nooit vertrouwelijke, gevoelige of persoonlijke gegevens bevatten.
• Als u een melding wilt verzenden, moet de cloudservice eerst worden geverifieerd met WNS en een toegangstoken ontvangen.
• Met een toegangstoken kan alleen een cloudservice meldingen verzenden naar de enkele app waarvoor het token is gemaakt. Eén toegangstoken kan niet worden gebruikt om meldingen over meerdere apps te verzenden. Als uw cloudservice meerdere apps ondersteunt, moet deze daarom het juiste toegangstoken voor de app opgeven bij het pushen van een melding naar elke kanaal-URI.
• Wanneer het apparaat offline is, slaat WNS standaard één van elk meldingstype op (tegel, badge, toastmelding) voor elke kanaal-URI en worden er geen onbewerkte meldingen opgeslagen.
• In scenario's waarin de meldingsinhoud wordt aangepast aan de gebruiker, raadt WNS aan dat de cloudservice deze updates onmiddellijk verzendt wanneer deze worden ontvangen. Voorbeelden van dit scenario zijn updates voor sociale mediafeeds, uitnodigingen voor directe communicatie, nieuwe berichtmeldingen of waarschuwingen. Als alternatief kunt u scenario's hebben waarin dezelfde algemene update vaak wordt geleverd aan een grote subset van uw gebruikers; Bijvoorbeeld weer-, voorraad- en nieuwsupdates. WNS-richtlijnen geven aan dat de frequentie van deze updates maximaal elke 30 minuten moet zijn. De eindgebruiker of WNS kan bepalen dat vaker routine-updates misbruik vormen.
• Windows Notification Platform onderhoudt een periodieke gegevensverbinding met WNS om de socket actief en gezond te houden. Als er geen toepassingen zijn die meldingskanalen aanvragen of gebruiken, wordt de socket niet gemaakt.

Vervaldatum van tegel- en badgemeldingen

Tegel- en badgemeldingen verlopen standaard drie dagen nadat ze zijn gedownload. Wanneer een melding verloopt, wordt de inhoud verwijderd uit de tegel of wachtrij en wordt deze niet meer weergegeven aan de gebruiker. Het is een best practice om een vervaldatum in te stellen (met een tijd die zinvol is voor uw app) op alle tegel- en badgemeldingen, zodat de inhoud van de tegel niet langer blijft bestaan dan relevant is. Een expliciete verlooptijd is essentieel voor inhoud met een gedefinieerde levensduur. Dit zorgt er ook voor dat verouderde inhoud wordt verwijderd als uw cloudservice stopt met het verzenden van meldingen of als de gebruiker gedurende een langere periode de verbinding met het netwerk verbreekt.

Uw cloudservice kan voor elke melding een vervaldatum instellen door de X-WNS-TTL HTTP-header in te stellen om de tijd (in seconden) op te geven dat uw melding geldig blijft nadat deze is verzonden. Zie Push Notification Service-aanvraag- en antwoordheaders voor meer informatie.

Tijdens de actieve handelsdag van een beurs kunt u bijvoorbeeld de vervaldatum voor een aandelenkoersupdate instellen op twee keer dat van uw verzendinterval (bijvoorbeeld één uur na ontvangst als u elke half uur meldingen verzendt). Een andere voorbeeld: een nieuws-app kan bepalen dat een dag een geschikte verlooptijd is voor een dagelijkse update van een nieuwstegel.

Pushmeldingen en batterijbesparing

Batterijbesparing verlengt de levensduur van de batterij door de achtergrondactiviteit op het apparaat te beperken. Met Windows 10 kan de gebruiker batterijbesparing instellen om automatisch in te schakelen wanneer de batterij onder een opgegeven drempelwaarde daalt. Wanneer de batterijbesparing is ingeschakeld, wordt de ontvangst van pushmeldingen uitgeschakeld om energie te besparen. Maar er zijn een paar uitzonderingen hierop. Met de volgende instellingen voor batterijbesparing voor Windows 10 (te vinden in Windows-instellingen) kan uw app pushmeldingen ontvangen, zelfs wanneer de batterijbesparing is ingeschakeld.

• Pushmeldingen van elke app toestaan terwijl de batterijbesparing actief is: met deze instelling kunnen alle apps pushmeldingen ontvangen terwijl de batterijbesparing is ingeschakeld. Houd er rekening mee dat deze instelling alleen van toepassing is op Windows 10 voor desktopversies (Home, Pro, Enterprise en Education).
• Altijd toegestaan: Met deze instelling kunnen specifieke apps op de achtergrond worden uitgevoerd terwijl de batterijbesparing is ingeschakeld, inclusief het ontvangen van pushmeldingen. Deze lijst wordt handmatig onderhouden door de gebruiker.

Er is geen manier om de status van deze twee instellingen te controleren, maar u kunt de status van batterijbesparing controleren. Gebruik in Windows 10 de eigenschap EnergySaverStatus om de status van de batterijbesparing te controleren. Uw app kan ook de gebeurtenis EnergySaverStatusChanged gebruiken om te luisteren naar wijzigingen in batterijbesparing.

Als uw app sterk afhankelijk is van pushmeldingen, wordt u aangeraden gebruikers op de hoogte te stellen dat ze mogelijk geen meldingen ontvangen terwijl de batterijbesparing is ingeschakeld en om de instellingen voor batterijbesparing eenvoudig aan te passen. Met het URI-schema voor batterijbesparing in Windows ms-settings:batterysaver-settingskunt u een handige koppeling naar Windows-instellingen bieden.

Hier volgt een voorbeeld van hoe u kunt controleren of batterijbesparing is ingeschakeld in Windows 10. In dit voorbeeld wordt de gebruiker geïnformeerd en worden de instellingen geopend voor instellingen voor batterijbesparing. Hiermee dontAskAgainSetting kan de gebruiker het bericht onderdrukken als hij of zij geen melding meer wil ontvangen.

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));
        }
    }
}

Dit is de XAML voor de ContentDialog- in dit voorbeeld.

<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>

Verwante onderwerpen

• Verstuur een lokale tegelmelding
• Quickstart: Een pushmelding verzenden
• Een badge bijwerken via pushmeldingen
• Een meldingskanaal aanvragen, maken en opslaan
• Meldingen onderscheppen voor het uitvoeren van toepassingen
• Verifiëren met de Windows Push Notification Service (WNS)
• Aanvraag- en antwoordheaders voor pushmeldingen
• Richtlijnen en controlelijst voor pushmeldingen
• Ruwe meldingen