Noteecast Connect

Endpoint de l'API

L'URL https://noteecast.nicolasdevienne.com/api/index.php est le seul et unique endpoint que dispose Noteecast Connect. C'est donc à partir de cette adresse que vous allez envoyer vos appels par la méthode GET ou POST.

Nous vous conseillons vivement de privilégier la méthode POST afin de conserver la confidentialité de vos données transmises ainsi qu'une certaine flexibilité concernant la taille de ces dernières.

Noteecast Connect vous permet :

• D'ajouter ou mettre à jour un jeton
• De récupérer l'historique des notifications envoyées
• De récupérer la liste des appareils

Ajouter ou mettre à jour un jeton

Lorsque votre app s'enregistre auprès de l'APNs ou FCM, un jeton est généré qui doit aussitôt être inscrit dans Noteecast Hosting.

LES PARAMÈTRES DE L'APPEL

• action=updateuser

«action» est le premier paramètre. Sa valeur est updateuser et signifie que l'on souhaite ajouter ou mettre à jour le jeton d'un utilisateur. Le jeton d'un utilisateur peut expirer à tout moment. L'APNS ou FCM renvoie à l'app un jeton actualisé qu'il faut mettre à jour pour que l'utilisateur puisse continuer à recevoir les notifications.

• key=xxx

«key» est le deuxième paramètre. Sa valeur est unique et correspond à la clé privée spécifique à Noteecast de votre app définie lors de la création de son espace dans Noteecast Hosting. Sa taille est de 32 caractères. Exemple : b85ef4505dc4a54e593e6103f76c92bb

• bundleid=com.domainname.appname

«bundleid» est le troisième paramètre. Sa valeur correspond à l'identifiant unique de votre app, la même que celle renseignée dans la clé bundle_id du fichier JSON. Sa taille maximale est de 64 caractères.

• uuid=xxx

«uuid» est le quatrième paramètre. Sa valeur correspond à l'identifiant unique de l'appareil. Sa taille maximale est de 36 caractères. Exemple : 864372C8-A575-4C2F-8EE5-218493BC116F

• platform=ios|android|web

«platform» est le cinquième paramètre. Sa valeur correspond à la plateforme de l'appareil est vaut l'une des 3 valeurs ios, android ou web. La notification envoyée à l'APNs ou FCM s'appelle un «payload». Son format est différent suivant la plateforme de l'appareil vers qui la notification est destinée. Il est donc très important de renseigner la bonne valeur sans quoi la notification ne sera jamais réceptionnée.

• token=xxx

«token» est le sixième paramètre. Sa valeur correspond au jeton généré par l'APNs ou FCM. Sa taille maximale est de 163 caractères. Exemple : fecy-IBvOUIDiu66-qzvNN:APA91bFlKOcTLgINgUPqHX7R3QdhsW0Ce7UiAmCDS_hLcu2n0cn-4Pzxk1sUmLcLaPCGDsXcLEzlzTHoubXxDjzUv6Sa6WzLCoJ9mcl1SQpq1M8rb1yz-gQsdIrQDG33MumLOpMyQYPv

Il conviendra d'envoyer la valeur «undefined» dans le cas où aucun jeton n'est généré (si l'utilisateur n'autorise pas votre app à lui envoyer des notifications par exemple).

• custom=xxx

«custom» est le septième et dernier paramètre. Sa valeur est libre et doit correspondre à une chaîne de caractères contenant la représentation JSON d'une valeur. Sa taille est celle d'un champ de type text pour MySQL soit 65535 caractères. Exemple : {"name":"Nico's iPhone 12 Pro Max","categories":["updates","tips","events"]}

EXEMPLE D'UN APPEL AVEC LA MÉTHODE GET

https://noteecast.nicolasdevienne.com/api/index.php
?action=updateuser
&key=b85ef4505dc4a54e593e6103f76c92bb
&bundleid=com.domainname.appname
&uuid=864372C8-A575-4C2F-8EE5-218493BC116F
&platform=ios
&token=fecy-IBvOUIDiu66-qzvNN:APA91bFlKOcTL...
&custom={"name":"Nico's iPhone 12 Pro Max","categories":["updates","tips","events"]}

RÉPONSE DE L'API

À la suite de l'appel, Noteecast Connect retourne une réponse au format JSON qui contient 2 informations :

• status qui prend comme valeur «success» en cas de succès et «error» en cas d'erreur.
• reason qui, en cas d'erreur, donnera la raison de cet échec.

Récupérer l'historique des notifications envoyées

LES PARAMÈTRES DE L'APPEL

• action=getnotifications
• key=xxx
• bundleid=com.domainename.appname

EXEMPLE D'UN APPEL AVEC LA MÉTHODE GET

https://noteecast.nicolasdevienne.com/api/index.php
?action=getnotifications
&key=b85ef4505dc4a54e593e6103f76c92bb
&bundleid=com.domainname.appname

RÉPONSE DE L'API

À la suite de l'appel, Noteecast Connect retourne également une réponse au format JSON. L'information reason contient un tableau composé de la liste des notifications avec pour chaque :

• timestamp contient le nombre de secondes écoulées entre le 1er janvier 1970 à minuit UTC précise et la date d'envoi de la notification. Exemple : 1622187660 pour la date du 28 mai 2021 à 07:41
• title contient le titre de la notification.
• body contient le message de la notification.
• image contient l'URL de l'image de la notification.
• data contient les données additionnelles de la notification. Cliquez ici pour voir comment ajouter des données additionnelles.
• target peut contenir au choix : une valeur vide si la notification est destinée à toutes les plateformes, l'une des 3 valeurs ios, android ou web si la notification est destinée à une seule des 3 plateformes ou l'uuid de l'appareil si la notification est destinée à un appareil en particulier.
• category peut contenir au choix : une valeur vide si la notification n'appartient pas à une catégorie, l'id de la catégorie sinon. Cliquez ici pour voir comment ajouter des catégories.

Exemple : {"timestamp":1622187660,"title":"👨‍💻👩‍💻 Comment ajouter Noteecast à votre app ?","body":"Noteecast s’appuie sur les services de Firebase et plus particulièrement sur la solution de messagerie multiplateforme Firebase Cloud Messaging (FCM).","image":"https://noteecast.nicolasdevienne.com/api/images/...","data":{"click_action":"https://noteecast.nicolasdevienne.com/www/fr/developer/"},"target":"ios","category":"updates"}

Suite à l'ajout de cet appel, vous pouvez prévoir un écran dédié dans votre app permettant à un nouvel utilisateur de consulter les notifications envoyées dans le passé comme c'est le cas pour Noteecast Connect.

Récupérer la liste des appareils

La liste des appareils correspond à la liste des utilisateurs qui ont téléchargé et installé votre app.

LES PARAMÈTRES DE L'APPEL

• action=getusers
• key=xxx
• bundleid=com.domainename.appname

EXEMPLE D'UN APPEL AVEC LA MÉTHODE GET

https://noteecast.nicolasdevienne.com/api/index.php
?action=getusers
&key=b85ef4505dc4a54e593e6103f76c92bb
&bundleid=com.domainname.appname

RÉPONSE DE L'API

À la suite de l'appel, Noteecast Connect retourne également une réponse au format JSON. L'information reason contient un tableau composé de la liste des utilisateurs qui ont téléchargé et installé votre app avec pour chaque :

• id contient l'uuid de l'appareil. Exemple : 082F64D6-43CF-4356-A62F-DCC0700DD69F
• label contient le nom de l'appareil. Exemple : Nico's iPhone 12 Pro Max
• platform contient la platforme de l'appareil parmi 3 valeurs possible : ios, android ou web.
• granted est un booléen qui prend la valeur true si l'appareil a autorisé la réception des notifications, false sinon. Attention ! Pour que cette valeur soit correctement renseignée, vous devez envoyer la valeur «undefined» pour le paramètre token lors de l'ajout ou de la mise à jour d'un jeton dans le cas où FCM ne génère pas de jeton.
• custom contient les données personnalisées que vous aurez décidé de récupérer lors de l'ajout ou mise à jour du jeton. Exemple : {"name":"Nico's iPhone 12 Pro Max","categories":["updates","tips","events"]}

Exemple complet : {"id":"082F64D6-43CF-4356-A62F-DCC0700DD69F","platform":"ios","label":"Nico's iPhone 12 Pro Max","granted"":true,"custom":{"name":"Nico's iPhone 12 Pro Max","categories":["updates","tips","events"]}}

> Étape suivante : Noteecast Go > Envoyez votre première notification