Pushberichten gebruiken

Overzicht van pushberichten
Pushberichten in een toepassing beheren
Een externe-berichtenprovider configureren
- Opties voor de externe-berichtenprovider
- Certificaten voor de externe-berichtenprovider
Pushberichten in een toepassing verwerken
- Configuratie en acceptatie van pushberichten
- Pushberichten en gegevens van berichtladingen verwerken

Met pushberichten kunnen externe-berichtenproviders hun berichten sturen naar toepassingen die op een mobiel apparaat worden uitgevoerd. AIR 3.4 biedt ondersteuning voor pushberichten voor iOS-apparaten met APNs (Apple Push Notification service).

Opmerking: als u pushberichten voor een AIR for Android-toepassing wilt inschakelen, moet u een native extensie gebruiken, zoals as3c2dm , ontwikkeld door Adobe-goeroe Piotr Walczyszyn.

In het resterende gedeelte van deze sectie wordt beschreven hoe u pushberichten kunt inschakelen in AIR for iOS-toepassingen.

Opmerking: in de discussie wordt aangenomen dat u beschikt over een Apple-ontwikkelaars-id, bekend bent met de iOS-ontwikkelingsworkflow en al minimaal één toepassing hebt geïmplementeerd op een iOS-apparaat.

Overzicht van pushberichten

Met APNs (Apple Push Notification service) kunnen externe-berichtenproviders hun berichten sturen naar toepassingen die op iOS-apparaten worden uitgevoerd. APNs biedt ondersteuning voor de volgende berichttypen:

Alerts (waarschuwingsberichten)
Badges
Geluiden

Voor meer informatie over APNs gaat u naar developer.apple.com .

Er is een aantal aspecten waarmee u te maken krijgt wanneer u pushberichten in uw toepassing gaat gebruiken:

Clienttoepassing : meldt zich aan voor pushberichten, communiceert met de externe-berichtenproviders en ontvangt de pushberichten.
iOS : beheert de interactie tussen de clienttoepassing en APNs.
APNs : levert een tokenID tijdens de clientregistratie en geeft berichten door van de externe-berichtenproviders aan iOS.
Externe-berichtenprovider : slaat informatie op over de tokenId-client-toepassing en levert pushberichten aan APNs.

Registratieworkflow

De workflow voor de registratie van pushberichten met een serverservice is als volgt:

De clienttoepassing dient een verzoek in bij iOS om pushberichten in te schakelen.
iOS stuurt het verzoek door naar APNs.
De APNs-server retourneert een tokenId naar iOS.
iOS retourneert het tokenId naar de clienttoepassing.
De clienttoepassing biedt het tokenId (via een toepassingsspecifiek mechanisme) aan bij de externe-berichtenprovider, die het tokenId opslaat voor gebruik met pushberichten.

Berichtenworkflow

De berichtenworkfllow is als volgt:

De externe-berichtenprovider genereert een bericht en geeft de berichtlading door aan APNs, samen met het tokenId.
APNs stuurt het bericht door naar iOS op het apparaat.
iOS stuurt de berichtlading via pushtechnologie door naar de toepassing.

Pushbericht-API

In AIR 3.4 wordt een set met API's geïntroduceerd die ondersteuning bieden voor iOS-pushberichten. Deze API's bevinden zich in het flash.notifications -pakket. Het pakket bevat onder andere de volgende klassen:

NotificationStyle : definieert constanten voor berichttypen: ALERT , BADGE en SOUND .C
RemoteNotifier : hiermee kunt u zich abonneren op pushberichten, of uw abonnement opzeggen.
RemoteNotifierSubscribeOptions : hiermee kunt u aangeven welke berichttypen u wilt ontvangen. Gebruik de eigenschap notificationStyles om een vector met tekenreeksen te definiëren waarmee u zich registreert voor meerdere berichttypen.

AIR 3.4 bevat ook flash.events.RemoteNotificationEvent , die wordt verzonden door RemoteNotifier , als volgt:

Wanneer het abonnement van een toepassing correct is ingesteld en een nieuw tokenId wordt ontvangen van APNs.
Bij het ontvangen van een nieuw extern bericht.

RemoteNotifier verzendt bovendien flash.events.StatusEvent als er een fout optreedt bij het abonnementsproces.

Pushberichten in een toepassing beheren

Als u een toepassing wilt registreren voor gebruik van pushberichten, moet u de volgende stappen uitvoeren:

Creëer code waarmee de toepassing zich abonneert op pushberichten.
Schakel de optie voor pushberichten in in het XML-bestand van de toepassing.
Creëer een inrichtingsprofiel en -certificaat waarmee iOS Push Services wordt ingeschakeld.

In de volgende voorbeeldcode ziet u hoe u een toepassing abonneert op pushberichten en hoe de pushberichtgebeurtenissen worden verwerkt:

package 
                        { 
                        import flash.display.Sprite; 
                        import flash.display.StageAlign; 
                        import flash.display.StageScaleMode; 
                        import flash.events.*; 
                        import flash.events.Event; 
                        import flash.events.IOErrorEvent; 
                        import flash.events.MouseEvent; 
                        import flash.net.*; 
                        import flash.text.TextField; 
                        import flash.text.TextFormat; 
                        import flash.ui.Multitouch; 
                        import flash.ui.MultitouchInputMode; 
                        // Required packages for push notifications 
                        import flash.notifications.NotificationStyle; 
                        import flash.notifications.RemoteNotifier; 
                        import flash.notifications.RemoteNotifierSubscribeOptions; 
                        import flash.events.RemoteNotificationEvent; 
                        import flash.events.StatusEvent; 
                        [SWF(width="1280", height="752", frameRate="60")] 

                        public class TestPushNotifications extends Sprite 
                        { 
                        private var notiStyles:Vector.<String> = new Vector.<String>;; 
                        private var tt:TextField = new TextField(); 
                        private var tf:TextFormat = new TextFormat(); 
                        // Contains the notification styles that your app wants to receive 
                        private var preferredStyles:Vector.<String> = new Vector.<String>(); 
                        private var subscribeOptions:RemoteNotifierSubscribeOptions = new RemoteNotifierSubscribeOptions(); 
                        private var remoteNot:RemoteNotifier = new RemoteNotifier(); 

                        private var subsButton:CustomButton = new CustomButton("Subscribe"); 
                        private var unSubsButton:CustomButton = new CustomButton("UnSubscribe"); 
                        private var clearButton:CustomButton = new CustomButton("clearText"); 

                        private var urlreq:URLRequest; 
                        private var urlLoad:URLLoader = new URLLoader(); 
                        private var urlString:String; 

                        public function TestPushNotifications() 
                        { 
                        super(); 

                        Multitouch.inputMode = MultitouchInputMode.TOUCH_POINT; 
                        stage.align = StageAlign.TOP_LEFT; 
                        stage.scaleMode = StageScaleMode.NO_SCALE; 

                        tf.size = 20; 
                        tf.bold = true; 


                        tt.x=0; 
                        tt.y =150; 
                        tt.height = stage.stageHeight; 
                        tt.width = stage.stageWidth; 
                        tt.border = true; 
                        tt.defaultTextFormat = tf; 

                        addChild(tt); 

                        subsButton.x = 150; 
                        subsButton.y=10; 
                        subsButton.addEventListener(MouseEvent.CLICK,subsButtonHandler); 
                        stage.addChild(subsButton); 

                        unSubsButton.x = 300; 
                        unSubsButton.y=10; 
                        unSubsButton.addEventListener(MouseEvent.CLICK,unSubsButtonHandler); 
                        stage.addChild(unSubsButton); 

                        clearButton.x = 450; 
                        clearButton.y=10; 
                        clearButton.addEventListener(MouseEvent.CLICK,clearButtonHandler); 
                        stage.addChild(clearButton); 

                        // 
                        tt.text += "\n SupportedNotification Styles: " + RemoteNotifier.supportedNotificationStyles.toString() + "\n"; 

                        tt.text += "\n Before Preferred notificationStyles: " + subscribeOptions.notificationStyles.toString() + "\n"; 

                        // Subscribe to all three styles of push notifications: 
                        // ALERT, BADGE, and SOUND. 
                        preferredStyles.push(NotificationStyle.ALERT ,NotificationStyle.BADGE,NotificationStyle.SOUND ); 

                        subscribeOptions.notificationStyles= preferredStyles; 

                        tt.text += "\n After Preferred notificationStyles:" + subscribeOptions.notificationStyles.toString() + "\n"; 


                        remoteNot.addEventListener(RemoteNotificationEvent.TOKEN,tokenHandler); 
                        remoteNot.addEventListener(RemoteNotificationEvent.NOTIFICATION,notificationHandler); 
                        remoteNot.addEventListener(StatusEvent.STATUS,statusHandler); 

                        this.stage.addEventListener(Event.ACTIVATE,activateHandler); 


                        } 
                        // Apple recommends that each time an app activates, it subscribe for 
                        // push notifications. 
                        public function activateHandler(e:Event):void{ 
                        // Before subscribing to push notifications, ensure the device supports it. 
                        // supportedNotificationStyles returns the types of notifications 
                        // that the OS platform supports 
                        if(RemoteNotifier.supportedNotificationStyles.toString() != "") 
                        {     
                        remoteNot.subscribe(subscribeOptions); 
                        } 
                        else{ 
                        tt.appendText("\n Remote Notifications not supported on this Platform !"); 
                        } 
                        } 
                        public function subsButtonHandler(e:MouseEvent):void{ 
                        remoteNot.subscribe(subscribeOptions); 
                        } 
                        // Optionally unsubscribe from push notfications at runtime. 
                        public function unSubsButtonHandler(e:MouseEvent):void{ 
                        remoteNot.unsubscribe(); 
                        tt.text +="\n UNSUBSCRIBED"; 
                        } 

                        public function clearButtonHandler(e:MouseEvent):void{ 
                        tt.text = " "; 
                        } 
                        // Receive notification payload data and use it in your app 
                        public function notificationHandler(e:RemoteNotificationEvent):void{ 
                        tt.appendText("\nRemoteNotificationEvent type: " + e.type + 
                        "\nbubbles: "+ e.bubbles + "\ncancelable " +e.cancelable); 

                        for (var x:String in e.data) { 
                        tt.text += "\n"+ x + ":  " + e.data[x]; 
                        } 
                        } 
                        // If the subscribe() request succeeds, a RemoteNotificationEvent of 
                        // type TOKEN is received, from which you retrieve e.tokenId, 
                        // which you use to register with the server provider (urbanairship, in 
                        // this example. 
                        public function tokenHandler(e:RemoteNotificationEvent):void 
                        { 
                        tt.appendText("\nRemoteNotificationEvent type: "+e.type +"\nBubbles: "+ e.bubbles + "\ncancelable " +e.cancelable +"\ntokenID:\n"+ e.tokenId +"\n"); 

                        urlString = new String("https://go.urbanairship.com/api/device_tokens/" + 
                        e.tokenId); 
                        urlreq = new URLRequest(urlString); 

                        urlreq.authenticate = true; 
                        urlreq.method = URLRequestMethod.PUT; 

                        URLRequestDefaults.setLoginCredentialsForHost 
                        ("go.urbanairship.com", 
                        "1ssB2iV_RL6_UBLiYMQVfg","t-kZlzXGQ6-yU8T3iHiSyQ"); 

                        urlLoad.load(urlreq); 
                        urlLoad.addEventListener(IOErrorEvent.IO_ERROR,iohandler); 
                        urlLoad.addEventListener(Event.COMPLETE,compHandler); 
                        urlLoad.addEventListener(HTTPStatusEvent.HTTP_STATUS,httpHandler); 

                        } 

                        private function iohandler(e:IOErrorEvent):void 
                        { 
                        tt.appendText("\n In IOError handler" + e.errorID +" " +e.type); 

                        } 
                        private function compHandler(e:Event):void{ 
                        tt.appendText("\n In Complete handler,"+"status: " +e.type + "\n"); 
                        } 

                        private function httpHandler(e:HTTPStatusEvent):void{ 
                        tt.appendText("\n in httpstatus handler,"+ "Status: " + e.status); 
                        } 

                        // If the subscription request fails, StatusEvent is dispatched with 
                        // error level and code. 
                        public function statusHandler(e:StatusEvent):void{ 
                        tt.appendText("\n statusHandler"); 
                        tt.appendText("event Level" + e.level +"\nevent code " + 
                        e.code + "\ne.currentTarget: " + e.currentTarget.toString()); 
                        } 
                        } 
                        }

Pushberichten inschakelen in het XML-bestand van de toepassing

Als u pushberichten wilt gebruiken in uw toepassing, moet u het volgende invoeren in de Entitlements -tag (onder de iphone -tag):

<iphone> 
                            ... 
                               <Entitlements> 
                                  <![CDATA[ 
                                     <key>aps-environment</key> 
                                     <string>development</string> 
                                  ]]> 
                               </Entitlements> 
                            </iphone>

Wanneer u gereed bent om de toepassing via pushtechnologie aan te melden bij de App Store, een <string> -element voor ontwikkeling naar productie:

      <string>production</string>

Als uw toepassing ondersteuning biedt voor gelokaliseerde tekenreeksen, moet u de desbetreffende talen opgeven in de supportedLanguages -tag, onder de intialWindow -tag, zoals in het volgende voorbeeld:

<supportedLanguages>en de cs es fr it ja ko nl pl pt</supportedLanguages>

Een inrichtingsprofiel en -certificaat maken voor iOS Push Services

Als u de communicatie tussen de toepassing en APNs wilt inschakelen, moet u de toepassing in een pakket plaatsen met een inrichtingsprofiel en -certificaat voor iOS Push Services, als volgt:

Meld u aan bij uw Apple-ontwikkelaarsaccount.
Ga naar de portal Provisioning (Inrichting).
Klik op de tab App IDs (Toepassings-id's).
Klik op de knop New App ID (Nieuwe toepassings-id).
Voer een beschrijving en een bundel-id in (gebruik geen asterisk * in de bundel-id).
Klik op Submit (Verzenden). De portal Provisioning (Inrichting) genereert vervolgens uw toepassings-id en de pagina App IDs (Toepassings-id's) wordt weergegeven.
Klik op Configure (Configureren), rechts van uw toepassings-id. De pagina Configure App ID (Toepassings-id configureren) wordt weergegeven.
Schakel het selectievakje Enable for Apple Push Notification service (Inschakelen voor APNs) in. Opmerking: er zijn twee typen Push-SSL-certificaat: een voor onwikkeling/testen en een voor productiedoeleinden.
Klik op de knop Configure (Configureren), rechts van het push-SSL-certificaat voor ontwikkeling. De pagina Generate Certificate Signing Request (CSR genereren) wordt weergegeven.
Volg de instructies op de pagina om een CSR met het hulpprogramma Keychain Access te maken.
Genereer het SSL-certificaat.
Download en installeer het SSL-certificaat.
(Optioneel) Herhaal stap 9-12 voor het Push-SSL-certificaat voor productiedoeleinden.
Klik op Done (Gereed). De pagina Configure App ID (Toepassings-id configureren) wordt weergegeven.
Klik op Done (Gereed). De pagina App IDs (Toepassings-id's) wordt weergegeven. Controleer of er een groene cirkel wordt weergegeven naast het pushbericht voor uw toepassings-id.
Sla uw SSL-certificaten op. Deze worden later gebruikt voor de communicatie tussen de toepassing en de provider.
Klik op de tab Provisioning (Inrichting) om de pagina Provisioning Profiles (Inrichtingsprofielen) weer te geven.
Maak een inrichtingsprofiel voor uw nieuwe toepassings-id en download dit profiel.
Klik op de tab Certificates (Certificaten) en download een nieuw certificaat voor het nieuwe inrichtingsprofiel.

Geluidsopties gebruiken voor pushberichten

Als u geluidsopties wilt inschakelen voor de pushberichten op uw toepassing, moet u de geluidsbestanden bundelen, net als elk ander element, maar wel in dezelfde directory als de SWF- en app-xml-bestanden. Bijvoorbeeld:

Build/adt -package -target ipa-app-store -provisioning-profile _-_.mobileprovision -storetype pkcs12 -keystore _-_.p12 test.ipa test-app.xml test.swf sound.caf sound1.caf

Apple biedt ondersteuning voor de volgende geluidsindelingen (in AIFF-, WAV- of CAF-bestanden):

Linear PCM
MA4 (IMA/ADPCM)
uLaw
aLaw

Gelokaliseerde waarschuwingsberichten gebruiken

Als u gelokaliseerde waarschuwingsberichten wilt gebruiken in uw toepassing, moet u de gelokaliseerde tekenreeksen bundelen in de vorm van lproj-mappen. Stel bijvoorbeeld dat uw toepassing ondersteuning biedt voor Spaanse waarschuwingsberichten, zoals volgt:

Maak een es.lproj-map in het project op hetzelfde niveau als het app-xml-bestand.
Maak een tekstbestand met de naam Localizable.Strings in de map es.lproj.
Open het bestand Localizable.Strings in een teksteditor en voeg berichtsleutels en de bijbehorende gelokaliseerde tekenreeksen toe. Bijvoorbeeld:
```
"PokeMessageFormat" = "La notificación de alertas en español."
```
Sla het bestand op.
Wanneer de toepassing een waarschuwingsbericht ontvangt met deze sleutelwaarde en het apparaat is ingesteld op Spaans, wordt de vertaalde waarschuwingstekst weergegeven.

Een externe-berichtenprovider configureren

Als u pushberichten wilt versturen naar uw toepassing, hebt u een externe-berichtenprovider nodig. Deze servertoepassing fungeert als provider: uw pushinvoer wordt geaccepteerd en het bericht en de bijbehorende berichtlading wordt doorgegeven aan APNs, waarna het pushbericht wordt doorgestuurd naar een clienttoepassing.

Voor gedetailleerde informatie over pushberichten van een externe-berichtenprovider gaat u naar Provider Communication with Apple Push Notification Service (Providercommunicatie via APNs) in de Apple-ontwikkelaarsbibliotheek.

Opties voor de externe-berichtenprovider

U kunt onder andere de volgende opties voor de externe-berichtenprovider instellen:

Maak uw eigen provider op basis van de APNS-php open-source-server. U kunt een PHP-server instellen met behulp van http://code.google.com/p/apns-php/ . Met dit Google Code-project kunt u een interface ontwerpen die voldoet aan uw specifieke vereisten.

Gebruik een serviceprovider. Zo vindt u bijvoorbeeld een kant-en-klare APNs-provider op http://urbanairship.com/ . Nadat u zich bij deze service hebt geregistreerd, kunt u uw apparaat-token aanbieden via code die lijkt op de volgende code:

private var urlreq:URLRequest; 
                                    private var urlLoad:URLLoader = new URLLoader(); 
                                    private var urlString:String; 

                                    //When subscription is successful then only call the following code 
                                    urlString = new String("https://go.urbanairship.com/api/device_tokens/" + e.tokenId); 
                                    urlreq = new URLRequest(urlString); 

                                    urlreq.authenticate = true; 
                                    urlreq.method = URLRequestMethod.PUT; 
                                    URLRequestDefaults.setLoginCredentialsForHost("go.urbanairship.com", 
                                       "Application Key","Application Secret"); 
                                    urlLoad.load(urlreq); 
                                    urlLoad.addEventListener(IOErrorEvent.IO_ERROR,iohandler); 
                                    urlLoad.addEventListener(Event.COMPLETE,compHandler); 
                                    urlLoad.addEventListener(HTTPStatusEvent.HTTP_STATUS,httpHandler); 

                                    private function iohandler(e:IOErrorEvent):void{ 
                                       trace("\n In IOError handler" + e.errorID +" " +e.type); 
                                    } 

                                    private function compHandler(e:Event):void{ 
                                       trace("\n In Complete handler,"+"status: " +e.type + "\n"); 
                                    } 

                                    private function httpHandler(e:HTTPStatusEvent):void{ 
                                       tt.appendText("\n in httpstatus handler,"+ "Status: " + e.status); 
                                    }

Vervolgens kunt u testberichten verzenden met de hulpprogramma's van Urban Airship.

Certificaten voor de externe-berichtenprovider

U moet het SSL-certificaat en de privésleutel (die u eerder hebt gegenereerd) kopiëren naar de juiste locatie op de server van de externe-berichtenprovider. Deze twee bestanden worden normaal gesproken gecombineerd in een enkel .pem -bestand. Hiervoor voert u de volgende stappen uit:

Open een terminalvenster.
Maak een .pem -bestand van het SSL-certificaat door de volgende opdracht te typen:
```
openssl x509 -in aps_developer_identity.cer -inform der -out TestPushDev.pem
```
Maak een .pem-betand van het privésleutelbestand ( .p12 ) door de volgende opdracht te typen:
```
openssl pkcs12 -nocerts -out TestPushPrivateKey.pem -in certificates.p12
```
Combineer beide .pem-bestanden tot een enkel bestand met de volgende opdracht:
```
cat TestPushDev.pem TestPushPrivateKey.pem > FinalTestPush.pem
```
Biedt het gecombineerde .pem -bestand aan bij de serverprovider wanneer u de serverpushtoepassing maakt.

Voor meer informatie gaat u naar Installing the SSL Certificate and Key on the Server (SSL-certificaat en -sleutel op de server installeren) in de Apple-programmeergids getiteld 'Apple Local and Push Notification Programming Guide'.

Pushberichten in een toepassing verwerken

Bij de verwerking van pushberichten in een toepassing wordt de volgende procedure doorlopen:

Algemene gebruikersconfiguratie en acceptatie van pushberichten
Gebruikersacceptatie van individuele pushberichten
Verwerking van pushberichten en berichtladinggegevens

Configuratie en acceptatie van pushberichten

Wanneer een gebruiker voor het eerst een toepassing start waarbij de functie voor pushberichten is ingeschakeld, wordt het appname -dialoogvenster 'Would Like to Send You Push Notifications' (Wilt u pushberichten verzenden) weergegeven. Dit dialoogvenster bevat de knoppen Don’t Allow (Niet toestaan) en OK. Als de gebruiker op OK klikt, kan de toepassing alle berichttypen ontvangen waarop de toepassing is geabonneerd. Als de gebruiker geen pushberichten toestaat, ontvangt de toepassing geen berichten.

Opmerking: via de optie Settings > Notifications (Instellingen > Berichten) kan de gebruiker aangeven welke specifieke berichttypen al dan niet zijn toegestaan voor elke toepassing waarbij de pushtechnologie is ingeschakeld.

Apple raadt aan dat toepassingen zich na elke activering abonneren op pushberichten. Wanneer uw toepassing RemoteNotifier.subscribe() aanroept, ontvangt de toepassing een RemoteNotificationEvent van het type token . Dit token bevat een uniek numeriek tokenID van 32 bits waarmee de desbetreffende toepassing op het specifieke apparaat wordt geïdentificeerd.

Wanneer het apparaat een pushbericht ontvangt, wordt een pop-upvenster weergegeven met de knoppen Close en Launch (respectievelijk Sluiten en Starten). Als de gebruiker Close (Sluiten) aantikt, gebeurt er niets. Als de gebruiker Launch (Starten) aantikt, wordt de toepassing door iOS aangeroepen en ontvangt de toepassing een flash.events.RemoteNotificationEvent van het type notification , zoals hieronder beschreven.

Pushberichten en gegevens van berichtladingen verwerken

Wanneer de externe-berichtenprovider een bericht verstuurt naar een apparaat (met behulp van het tokenID), ontvangt uw toepassing een flash.events.RemoteNotificationEvent van het type notification , onafhankelijk of de toepassing al dan niet wordt uitgevoerd. Op dit punt wordt een toepassingsspecifieke berichtverwerking uitgevoerd door uw toepassing. Als de berichtgegevens door uw toepassing worden verwerkt, hebt u toegang hiertoe via de eigenschap RemoteNotificationEvent.data die gebruikmaakt van de JSON-indeling.