Rev pA2.
Contenu
À propos de ce document. 3
Changements: 3
Comment fonctionnent les services de notification Windows (WNS). 4
Intégration. 5
Avant de commencer à coder. 5
Le code de l'application. 5
Symplify UI 5
UWP App. 6
Enregistrer votre application et recevoir les informations d'identification pour votre service en ligne. 6
Configuration de votre application UWP. 7
Rédaction du code. 7
Credentials Symplify. 7
SDK Symplify. 8
Inscription. 8
Réception des Push. 10
Déclenchement d'un envoi transactionnel. 13
Récupération d'informations sur un contact. 13
Compte Symplify. 14
Configuration App dans Symplify: 14
Contenu Symplify. 14
Tests et résolution des problèmes. 15
Envoi de notifications UWP avec Symplify. 16
Templates Toast. 16
Templates Tile. 16
Template Badge. 17
Template Raw. 17
À propos de ce document
Ce document décrit comment intégrer Symplify avec les notifications push de la plateforme universelle Windows.
Changements:
pA1 première version
pA2 a modifié l'URL et la présentation du payload pour l'enregistrement du mécanisme et le code d'exemple. Ajout d'une méthode pour l'envoi de push
Comment fonctionnent les services de notification Windows (WNS)
Le schéma suivant montre le flux complet de données pour l'envoi d'une notification push. Il comprend les étapes suivantes :
Votre application demande un canal de notification "push" à partir de la plateforme universelle Windows.
Windows demande au WNS de créer un canal de notification. Ce canal est renvoyé à l'appareil appelant sous la forme d'un identificateur de ressources uniformes (URI).
L'URI du canal de notification est renvoyé par Windows à votre application.
Votre application envoie l'URI à Symplify. Symplify stockera l'URI afin que vous puissiez y accéder lorsque vous envoyez des notifications. L'URI est une interface entre votre propre application et Symplify ;
Lorsque Symplify a une mise à jour à envoyer, il notifie le WNS en utilisant l'URI du canal. Cela se fait en émettant une requête HTTP POST, incluant la charge utile de la notification, via le protocole SSL (Secure Sockets Layer). Cette étape nécessite une authentification.
Le WNS reçoit la demande et achemine la notification vers le système approprié.
Une vue d'ensemble de la notification "window push" peut être trouvée ici : (lien anglais) http://developer.telerik.com/featured/windows-notifications-demystified/
Intégration
Les étapes de l'intégration sont les suivantes :
Avant de commencer à coder
Assurez-vous que l'application est enregistrée sur le Microsoft Store et qu'elle est dotée d'un SID et d'une clé secrète.
Assurez-vous que l'application est enregistrée dans Symplify à l'aide du SID et de la clé secrète.
Le code de l'application
L'application demande un URI à WNS
L'application envoie cet URI à Symplify en même temps que la SID.
L'URI est stocké dans le carma et associé à l'application
Symplify UI
Une nouvelle campagne est créée comme un push
La campagne est connectée à l'application enregistrée.
La campagne est envoyée au WNS qui la transmettra aux appareils enregistrés.
App UWP
Avant de commencer, vous devez disposer d'une application UWP à laquelle vous souhaitez envoyer des notifications push.
Ce tutoriel sur les notifications push suppose que Visual Studio 2015 est utilisé comme IDE, avec un périphérique cible Windows 10.
Enregistrement de votre application et réception des informations d'identification pour votre service en ligne
Avant de pouvoir envoyer des notifications à l'aide du WNS, votre application doit être enregistrée dans le Store Dashboard. Cela vous permettra d'obtenir des informations d'identification pour votre application que votre service cloud utilisera pour s'authentifier auprès du WNS. Ces identifiants se composent d'un identifiant de sécurité de paquet (SID) et d'une clé secrète. Chaque application possède son propre ensemble d'identifiants pour son service en ligne. Ces identifiants ne peuvent pas être utilisés pour envoyer des notifications à une autre application.
Pour effectuer cet enregistrement, allez dans le centre de développement de Windows et sélectionnez Dashboard.
Créer une nouvelle application et donnez-lui un nom unique tel que com.something.push.
Vous pouvez également créer ces informations à partir de Visual Studio en choisissant
Project->Store->Associate App With Store…
Pour récupérer votre SID et votre clé secrète, visitez le site Live Services. Pour ce faire, vous devez vous connecter avec le compte Microsoft qui a ouvert votre compte Dev Center.
Faites défiler vers le bas jusqu'à Application secret et enregistrez cette valeur en tant que Clé secrète, qui ressemble à ceci :
blTLazxKrbR56234Ekz1Q47XLl+WDbN
Faites défiler vers le bas jusqu'à Package SID et copiez cette valeur dans SID. Cela ressemblera à ceci :
ms-app://s-1-15-2-3559591886-3145364946-4169436704-2144837230-885026494-1372889922-3594474832
Terminez l'enregistrement conformément aux directives de Microsoft. Ce processus n'entre pas dans le cadre de ce guide. Pour plus de détails sur la manière d'enregistrer votre application, veuillez consulter la section Comment s'authentifier auprès du service de notification Windows (WNS).
Configuration de votre application UWP
Ouvrez le fichier .appmanifest de votre application.
Dans l'onglet Capabilities, cochez les cases suivantes : Internet(Client), Internet (Client et Serveur), Réseaux privés ( Client et Serveur)
Dans l'onglet Declaration, ajoutez Background Task et cochez Push Notification and Timer sous Properties
Rédaction du code
Credentials Symplify
Pour pouvoir interagir avec Symplify, vous avez besoin de quatre éléments d'information.
serverUrl (L'URL du serveur où se situe votre compte, tel que http://www5.carmamail.com/)
customerId
Username
Password
listId (si vous prévoyez de remplir une liste existante au lieu d'utiliser la liste par défaut pour l'application)
Vous pouvez demander ces informations à votre gestionnaire de compte ou en envoyant un courriel à support@symplify.com.
SDK Symplify.
Il existe quelques classes de commodité que vous pouvez télécharger pour commencer à mettre en œuvre le Push Symplify UWP.
Les classes sont :
Carma/Dtos/DeviceDto.cs Data Transfer Object pour les données des appareils
Carma/Dtos/DeviceInfoDto.cs Data Transfer Object pour les données de deviceinfo
Carma/Dtos/SendTriggerDto.cs Data Transfer Object pour l'envoi de transactionnels
Carma/AppData.cs C'est ici que vous saisissez les données spécifiques au compte
Carma/RestClient.cs Méthodes de communication avec Carma
Vous pouvez télécharger les classes ici : https://drive.google.com/file/d/0B5FRn4gbIr5LLVVuY2NuUmZiOTg/view?usp=sharing
ou envoyez un courriel à support@symplify.com et ils vous les fourniront.
Inscription
Nous pouvons maintenant commencer à coder. La première chose que nous devons faire est de nous enregistrer auprès du WNS pour obtenir un URI et le fournir à notre serveur. Cet URI identifie de manière unique un dispositif UWP, et notre serveur l'utilisera pour envoyer des messages à ce dispositif spécifique. Le code pour obtenir un canal est simple:
String channel = await PushNotificationChannelManager.CreatePushNotificationChannelForApplicationAsync();
Ce token doit être enregistré dans Symplify avec la SID et un originalid de votre choix. L'originalid est un identifiant ou l'utilisateur dans votre système. Il peut s'agir d'une adresse électronique ou d'une clé primaire de l'utilisateur dans votre base de données. Si vous n'avez pas d'originalid pour l'utilisateur actuel dans votre application, il doit être généré par votre application.
NOTE! Vous ne pouvez PAS utiliser le canal comme l'originalId car cela changera avec le temps.
Vous vous inscrivez en émettant une demande de PUT auprès de :
https://<serverUrl>/rest/<customerid>/apps//pushdevices
serverUrl et customerId sont fournis par Symplify. AppId est le même que le SID que vous avez reçu de WNS
avec un payload json contenant au minimum
deviceToken
originalId
NOTE! Même si elles sont identiques, les deux valeurs doivent être fournies.
Dans ce payload, vous pouvez également ajouter d'autres informations sur l'utilisateur qui doivent être transférées à Symplify. Vous trouverez ci-dessous la liste complète des propriétés disponibles.
{
“listId”: 0,
“country”: “”,
“originalId”: “”,
“firstName”: “”,
“lastName”: “”,
“middleName”: “”,
“emailAddress”: “”,
“title”: “”,
“dateOfBirth”: “”,
“city”: “”,
“zipcode”: “”,
“sex”: “”,
“mobileNumber”: “”,
“optOutDate”: “”,
“dateOfInvalidation”: “”,
“optOutMobileDate”: “”,
“properties”: “Map[string,string]”,
“namedProperties”: “Map[string,string]”,
“deviceInfo”: [{
“devicetoken”:””,
“Manufacturer”: “”,
“osVersion”: “”,
“model”, “”
“country”: “”
}]
}
La ressource utilise l'authentification de base pour l'authentification et vous devez définir les en-têtes Content-Type et Accept sur "application/json".
Le code de commodité suivant, qui est défini dans la classe RestClient.cs, peut être utilisé pour l'inscription :
RestClient client = new RestClient();
String emailAddress = “an.address@gmail.com”;
String originalId = “abc123”;
//
// DeviceDto contient des données essentielles qui peuvent être mises à jour pour un contact dans Symplify.
//
var device = new DeviceDto() { emailAddress = emailAddress , originalId = originalId};
await client.UpdateUser(device);
Si vous souhaitez ajouter des informations supplémentaires à un utilisateur, vous pouvez simplement les ajouter en tant que propriétés.
RestClient client = new RestClient();
String food = “meat”;
String drink = “water”;
String firstName = “Lars”;
String emailAddress = ” an.address@gmail.com”;
String originalId = “abc123”;
//
// Les données spécifiques aux clients sont ajoutées à l'aide de paires de valeurs de noms.
//
Dictionary<string, string> listData = new Dictionary<string, string>{
{“drink”, drink},
{“food”, food}
};
//
// DeviceDto contient des données essentielles qui peuvent être mises à jour pour un contact dans carma.
//
var device = new DeviceDto() { properties = listData, firstName = firstName, emailAddress = emailAddress , originalId = originalId};
await client.UpdateUser(device);
Réception Push
Le contenu d'une notification Windows dépend du type de notification.
Il existe quatre types de notifications qui peuvent être envoyées;
Badge, Tile, Toast et Raw. La définition des différents types de notifications n'entre pas dans le contexte du présent document.
Le type Toast est le type de notification le plus courant qui ressemble le plus à un push sur iOS ou Android.
Microsoft dispose d'un certain nombre de Toast prédéfinis qui ont tous une syntaxe stricte à laquelle ils adhèrent.
Voici un exemple d'un payload d'une notification Toast
<?xml version=”1.0″ standalone=”yes”?><toast launch=”http://www5.carmamail.com/mail/OBS?muid=67wp0002020DH0Pq0BwI1631593124″ duration=”long”><visual><binding template=”ToastText02″><text id=”1″>Text Line 1.</text><text id=”2″>Text Line 2.</text></binding></visual></toast>
Un message Symplify push toast contient les champs suivants :
launch – contient un lien qui peut être utilisé afin de récupérer la version à contenu riche du push.
Binding – le nom défini par Microsoft pour ce type de notification.
Il est important de se rappeler que c'est au développeur de l'application de décider comment ces champs doivent être utilisés.
Notre client UWP est maintenant enregistré dans le WNS, et notre serveur peut commencer à envoyer des messages aux appareils qui utilisent notre client en utilisant le SID, la clé secrète et l'URI du canal de l'appareil fournis. Les messages pour notre application UWP seront reçus par la classe App.xml.cs.
Si l'application reçoit un push alors qu'elle est inactive, ce push fera partie des arguments de lancement et pourra être récupéré avec le code suivant dans la méthode OnLaunch :
Vous devez ajouter un écouteur dans la méthode OnLaunched
protected async override void OnLaunched(LaunchActivatedEventArgs e)
{
// DÉBUT DU CODE SPÉCIFIQUE SYMPLIFY
//
string launchArgs = e.Arguments;
System.Diagnostics.Debug.WriteLine(string.Format(“App Launched params:{0}”, launchArgs));
if (launchArgs.Length > 0)
{
// La demande a été lancée à partir d'une notification.
// L'application a commencé à partir d'une notification.
RestClient client = new RestClient();
String notificationContent = launchArgs;
String dataFromServer = await client.ReadDataFromServer(notificationContent);
}
//
// FIN DU CODE SPÉCIFIQUE SYMPLIFY
//
…
…
…
try
{
//
// CODE SPÉCIFIQUE SYMPLIFY
//
RestClient client = new RestClient();
// mettre à jour les informations du canal dans Symplify
await client.Init();
client.PushNotificationReceived += OnPushNotification;
await client.UpdateUser(null);
}
catch (Exception ex)
{
System.Diagnostics.Debug.WriteLine(“ERROR, “, ex);
}
}
}
La méthode pour consommer le push peut être basée sur la fonction suivante :
private async void OnPushNotification(PushNotificationChannel sender, PushNotificationReceivedEventArgs e)
{
RestClient restClient = new RestClient();
String notificationContent = String.Empty;
switch (e.NotificationType)
{
case PushNotificationType.Toast:
notificationContent = e.ToastNotification.Content.GetXml();
XmlDocument doc = new XmlDocument();
doc.LoadXml(notificationContent);
String url = doc.DocumentElement.GetAttribute(“launch”);
//Si les données de carma sont une page html standard, utilisez cette méthode. // C'est normalement le cas
string myStyledHTML = await restClient.GetCustomData(url);
//Si les données de carma sont des JSON personnalisés que vous avez créés, utilisez //cette méthode.
JsonObject jsonData = await restClient.getCustomJsonData(url);
//À FAIRE insérer ce qui devrait se passer avec les données reçues.
//
break;
case PushNotificationType.Badge:
notificationContent = e.BadgeNotification.Content.GetXml();
break;
case PushNotificationType.Tile:
notificationContent = e.TileNotification.Content.GetXml();
break;
case PushNotificationType.Raw:
notificationContent = e.RawNotification.Content;
restClient.SendLocalNotification(notificationContent);
break;
}
}
Envoi d'un courriel transactionnel
Au lieu d'utiliser la fonctionnalité de campagne, vous pouvez également envoyer des messages "push" en utilisant la fonctionnalité de déclenchement de Symplify.
Cela se fait en émettant une requête PUT à :
/{appid}/pushdevices/{id}/triggers/{triggerid}/messages
https:///rest/<customerid>/apps//pushdevices//triggers//messages
avec un payload json contenant au minimum
originalId,
{
“originalId”:”abcabc123123″
}
NOTE! Même si l'originalId et le devicetoken sont identiques, les deux valeurs doivent être fournies.
Cela permettra d'envoyer des notifications "push" à tous les appareils connectés au original Id.
Si vous stockez vos contacts sur une liste autre que la liste par défaut de l'application, vous devez également ajouter son identifiant au payload, tel que :
{
“originalId”:”abcabc123123″
“listId”:12345
}
Si vous souhaitez envoyer le push à un seul appareil spécifique, vous pouvez ajouter le token de l'appareil au payload.
{
“deviceInfo”:[{“devicetoken”: “abc123abc123kmlkmlkml_2”}],
“originalId”:”abcabc123123″
“listId”:12345
}
Si vous pouvez récupérer tous les tokens d'un appareil en utilisant la méthode indiquée ci-dessous.
Récupération d'informations sur un contact
Si vous souhaitez récupérer les informations relatives à un contact, vous pouvez adresser une demande GET à
https:///rest/<customerid>/lists//contacts/
Vous recevrez la même structure que lorsque vous enregistrez un appareil. Elle contiendra une liste de tous les appareils enregistrés sur l'Id d'origine. Si vous avez importé des informations par un autre moyen, c'est-à-dire par importation programmée sur la liste, ces données seront également récupérées.
Compte Symplify
Pour envoyer un push, vous aurez besoin d'un compte dans Symplify, où vous aurez reçu les informations suivantes :
Username
Password
Server URL
Configuration App dans Symplify:
Cliquez sur Paramétrage du compte dans le menu de gauche, puis choisissez Push Apps sous Gestion.
Cliquez sur Créer nouveau et vous verrez le dialogue suivant dans lequel vous entrez les informations
Pour enregistrer votre application dans Symplify, vous aurez besoin du nom SID de votre application et du Secret de Client que vous avez obtenu de Microsoft. Le numéro d'identification de l'application sera le même que celui du SID.
Cliquez sur Créer et vous êtes prêt à envoyer des demandes Push à vos utilisateurs.
Le contenu riche de la campagne sera disponible pour le push en appelant l'URL qui est reçue dans le champ url de la notification.
Contenu Symplify
Le contenu d'un message push n'est pas envoyé dans le push lui-même, mais est situé du côté du serveur où l'url du message pointe. Le contenu est généralement une page html qui est générée pour le système en question, par un modèle du côté serveur. Il peut toutefois s'agir de JSON ou d'autres formats textuels définis par le modèle.
La façon la plus courante de traiter le contenu est de créer simplement un WebView et de le faire pointer vers l'url, ce qui lui permet d'afficher la page. Le développeur peut cependant choisir de le traiter de différentes manières. Par exemple, il pourrait ouvrir le navigateur de l'appareil en fonction d'une intention, télécharger le contenu et l'analyser pour en extraire les informations utilisées dans l'application d'une manière ou d'une autre, ou le transmettre à une autre application.
Tests et résolution des problèmes
Une fois l'intégration effectuée, effectuez les tests suivants.
Installer l'application sur un nouvel appareil
Notez que le nombre de destinataires augmente à chaque fois que vous faites cela. Si ce n'est pas le cas, vérifiez que les identifiants que vous fournissez sont corrects. Vérifiez également que l'annexe que vous avez donnée lors de l'enregistrement de la demande est la même que celle qui figure en haut de votre manifeste.
Si la liste s'allonge, testez un simple push pendant que la demande est en cours d'exécution. Si une notification n'apparaît pas après quelques minutes, vérifiez que vous avez donné la bonne clé api lors de l'enregistrement de l'application dans Symplify.
Une fois que tout fonctionne correctement, vérifiez que les notifications s'affichent lors de l'envoi d'un push même si l'application n'est pas en cours d'exécution.
Envoi de notifications UWP avec Symplify.
Microsoft définit un certain nombre de mises en page prédéfinies pour les notifications.
Lorsque vous envoyez un push, vous devez décider quel type de message vous voulez envoyer, puis ajouter le bon JSON.
Templates Toast
Symplify implémente les modèles Toast suivants :
· ToastText01· ToastText02· ToastText03· ToastText04· ToastImageAndText01· ToastImageAndText02· ToastImageAndText03· ToastImageAndText04
Pour plus d'informations sur les mises en page, veuillez consulter https://msdn.microsoft.com/sv-se/library/windows/apps/windows.ui.notifications.toasttemplatetype
Si vous envoyez un Toast qui comporte une image, cette image n'est pas envoyée dans le push mais doit faire partie de l'application qui la reçoit.
En général, vous pointerez vers une image dans la bibliothèque des ressources de votre application.
Les Toasts peuvent être affichés soit pour une courte durée (7 secondes), qui est la valeur par défaut, soit pour une longue durée (30 secondes). Cette durée est définie par le champ de durée optionnelle dans l'objet toast.
Pour un Toast, le JSON ressemble à ceci :
{“type”:”TOAST”,
“toastNotification”:”ToastText02″,
“launch”:””,
“duration”:”long”,
“data”:[
{“type”:”TEXT”,”content”:”New message for you.”,”alt”:””},
{“type”:”TEXT”,”content”:”Hello, check this.”,”alt”:””}]
}
Templates Tile
Actuellement, Symplify implémente les modèles tiles suivants :
· TileSquareBlock· TileSquareImage· TileSquarePeekImageAndText04· TileWideText09· TileWideImage· TileWideImageAndText01· TileWidePeekImageAndText01
Pour plus d'informations sur les mises en page, veuillez consulter https://msdn.microsoft.com/sv-se/library/windows/apps/windows.ui.notifications.tiletemplatetype
Si vous envoyez un Tile qui comporte une image, cette image n'est pas envoyée dans le push mais doit faire partie de l'application qui la reçoit.
En général, vous pointerez vers une image dans la bibliothèque des ressources de votre application.
Pour un Tile, le JSON ressemble à ceci :
{“type”:”TILE”,
“tileNotification”:”TileSquareBlock”,
“data”:[
{“type”:”TEXT”,”content”:”Text 1″,”alt”:””},
{“type”:”TEXT”,”content”:”Text 2″,”alt”:””}]
}
Template Badge
Il n'y a qu'un seul type de modèle de badge et il prend un nombre entier comme paramètre qui décide quel numéro doit être affiché avec le badge.
Pour un Badge, le JSON ressemble à ceci :
{“type”:”BADGE”,
“badgeNotification”:”Badge”,
“data”:[
{“type”:”TEXT”,”content”:”1″,”alt”:””}
}
Template Raw
Un template raw peut être utilisé pour envoyer des données arbitraires dans une notification. Il appartient à l'application Windows d'utiliser les données comme bon lui semble.
Pour un Raw, le JSON ressemble à ceci :
{“type”:”RAW”,
“rawNotification”:”Raw”,
“data”:[
{“type”:”TEXT”,”content”:”some raw data”,”alt”:””}]
}