Premiers pas avec le développement d'applications BoondManager

Premiers pas avec le développement d'applications BoondManager

 Restez sur la bonne voie avec notre changelog

Si vous souhaitez être averti lorsque notre équipe planifie/publie de nouvelles fonctionnalités techniques ou si vous utilisez notre API et que vous voulez vous assurer que notre nouvelle fonctionnalité ne cassera pas votre code, nous vous conseillons de vous abonner au canal changelog.

Premiers pas avec le développement d'applications BoondManager

Compléter les informations d'éditeur

Remplir les informations d'éditeur permet d'identifier le fournisseur de chaque application dans notre magasin.

Administrateurs uniquement!

Pour créer le vôtre, vous aurez besoin d'un accès administrateur :

  • Accédez à Se connecter en tant qu'administrateur
  • Allez dans 'Menu utilisateur > administration > Espace Développeur (bas de page dans les rubriques techniques)' > 'Informations éditeur'

Editor Space - Editor Information

Tous les champs ne sont pas obligatoires, mais nous vous recommandons de fournir autant d'informations que possible car ces informations seront visibles avec les détails de votre application dans notre boutique.

Déclarer votre application

Pour déclarer votre application, vous devrez :

Champs obligatoires

Tous les champs ne sont pas obligatoires mais nous avons besoin, au minimum, des champs suivants :

  • Nom
  • Code de l'app
  • Url de l'app

Une fois que vous enregistrez, la clef de l'application est générée. Il s'agit de l'identifiant unique de votre application qui est nécessaire pour l'installation de l'application et les appels d'API suivants :

 

Avoir une icône d'application sert à se démarquer et à être mémorable, nous vous recommandons de profiter de la fonctionnalité et d'en ajouter une pour votre application.

 

Voici une description détaillée de chaque champ du formulaire :

Champ Courte description
Nom

  Le nom d'affichage de votre application. Faites-le ressortir :)

Titre

  Une courte description affichée à côté du nom dans le Marketplace

Categorie

  Il caractérise votre application selon les catégories que nous avons identifiées et supportées. Chaque option, à l'exception de l'option "Autre" (choix par défaut), fournit à votre application des fonctionnalités supplémentaires.

  Consultez la section dédiée à ce sujet ici.

Site Internet

  Le site Web de votre application, les utilisateurs seront redirigés vers cette URL

Témoignages

  Si vous configurez une page de témoignages, les utilisateurs seront redirigés vers cette URL

Conditions d'utilisation

  Si vous avez besoin de conditions d'utilisation spécifiques, les utilisateurs seront redirigés vers cette URL

Code de l'app

  Le code unique de votre application. Il ne peut contenir que des lettres non espacées et non majuscules.

Clef de l'app

  Elle sera fourni automatiquement après avoir enregistré les détails de votre application.

Référence de l'application

  L'identifiant unique de votre application généré après l'enregistrement du formulaire ( En bas à gauche de la page sous le format : "Référence : APPXXXXXX"

Url de l'app

  Ce champ contient l'URL technique fournie par vos développeurs. C'est l'URL racine que nous utiliserons pour installer, désinstaller, configurer et appeler l'application. Selon votre les règles de votre ".htaccess" votre URL doit potentiellement finir par "/"

Page de configuration de l'app

  Ce champ permet de déclarer que l'App dispose d'une page de configuration. Nous allons créer un accès à cette page en appelant "App url"/configuration

Visibilité

   Une application est privée par défaut, c'est-à-dire que seuls les utilisateurs appartenant à votre entreprise peuvent la voir et l'utiliser. Pour rendre une application publique, c'est-à-dire disponible en dehors de votre organisation, nous devrons passer par un processus de validation. Veuillez nous contacter si vous avez ce besoin.

Vous pouvez lancer le processus de validation à l'aide du bouton Publier disponible sur la page de votre application.

Sécurité du token pour l'authentification X-Jwt-App

Décrit le type de sécurité pour le token X-Jwt-App :

  • token permanent : peut être utilisé pour une application privée
  • token temporaire: Obligatoire pour l'application publique
API autorisées

  Ce champ permet de restreindre les API accessibles par un utilisateur d'une App ou une personne ayant accès au jeton d'authentification. La définition de ce champ bloquera toute tentative d'accès à l'API non autorisée, même en mode GOD.

Lors de la publication d'une application dans la boutique publique, ce champ est obligatoire.

Description

  Une description plus détaillée de votre application qui sera affichée aux utilisateurs

Tarif

  Les frais que vous facturez pour l'utilisation ou l'installation de votre application. Il est affiché aux utilisateurs.

Ajouter des boutons d'accès à l'application   Décrit l'emplacement des boutons d'accès de votre application dans une vue en spécifiant :
  • Page: la page dans laquelle le bouton de l'application sera affiché
  • Titre du bouton: le titre du bouton
  • Fonction de l'app: l'endpoint (URL/fonction de l'application) qui sera appelé lorsqu'un utilisateur cliquera sur le bouton de l'application
Ajouter des pages où afficher l'application   Décrit l'emplacement des boutons d'accès de votre application dans l'iFrame en spécifiant :
  • Page: la page dans laquelle l'application sera affiché
  • Défilement: indique si une barre de défilement est affichable sur l'iFrame de l'App
  • Hauteur: la hauteur de l'iFrame de l'App en pixels
  • Largeur: la largeur de l'iFrame de l'App en pourcentage
  • Fonction de l'app: l'endpoint (URL/fonction de l'application) qui sera appelée lorsque l'iFrame de l'application s'affichera
Ajouter des événements déclenchant des hooks à l'application   Décrit le déclencheur qui affichera votre application :
  • Page: La page sur laquelle il faut ce rendre pour déclencher le hook
  • Evènement: Le type d'événement qui affichera votre App ( Créer / Mettre à jour / Supprimer )
  • Fonction de l'app: l'endpoint qui sera appelé lorsque l'événement choisis déclenchera le hook
Commencer à construire

Toute application doit fournir des endpoints spécifiques via une API Rest qui répond aux requêtes HTTP. Il vous permettra d'installer, de configurer et de désinstaller l'application depuis BoondManager :

  • your-App-URL/install: requêtes POST à partir de la page d'administration de l'application
  • your-App-URL/configure: une requête GET depuis l'iFrame de l'application
  • your-App-URL/uninstall: SUPPRIMER les requêtes de la page d'administration de l'application

Une fois que vous êtes à l'aise avec le code de l' application Hello, vous pouvez commencer à implémenter le vôtre. Dans les sections suivantes, nous approfondirons les paramètres attendus par chaque endpoint.

Cette application a été conçue pour fonctionner immédiatement en supposant que les règles de réécriture d'URL de votre serveur sont correctement configurées. Si nécessaire, consultez cette page .

Installez votre application

Pour installer votre application, vous devrez :

Si vous avez créé votre application pour exiger l'installation d'un code, vous serez invité à le saisir dans une fenêtre contextuelle. Les clients ont généralement besoin d'un code d'installation lorsque leur application est publique, mais ils souhaitent toujours en restreindre l'accès.

code_produit

Cliquer sur Confirmer lancera le processus d'installation de l'application. process.

Une fois l'installation terminée, votre administrateur BoondManager peut activer l'application pour chaque utilisateur (Administration > Managers / Rôles > Accéder au profil du manager > Activer l'App pour le manager)

Présentation approfondie de l'installation

Le processus d'installation d'une application se résume à vous fournir un jeton qui sera utilisé dans les appels d'API de votre application. C'est un processus en 4 étapes :

  • Nous faisons une requête POST à votre serveur avec le  installationCode. Il sera vide si aucun n'a été choisi.
  • Nous recevons une confirmation de réussite ou d'échec en réponse.
  • Nous faisons une requête POST à votre serveur avec appToken qui sera nécessaire pour tous vos futurs appels d'API. Ce jeton devra être stocké sur votre infrastructure.
  • Nous recevons une confirmation de réussite ou d'échec en réponse. 

app_install.png

Attribut de corps détaillé de la requête

  • Chaque corps de requête à un attribut unique signedRequest: un objet JSON, dans lequel les attributs détaillés ci-dessous sont encodés.
  • L'objet censé être renvoyé à notre serveur en réponse a également besoin d'un attribut encodé signedRequest .

Cet attribut est la concaténation d'une signature HMAC SHA-256 , d'un point et d'un objet JSON encodé en base64url

Voici un extrait en PHP montrant comment nous pouvons le décoder :

defined('rest_key') || define('rest_key', your_app_key_here);
        function signedRequest_decode($signed_request) {
            list($encoded_signature, $payload) = explode('.', $signed_request, 2);
            if(base64_url_decode($encoded_signature) == hash_hmac('sha256', $payload, rest_key))
                return $data = json_decode(base64_url_decode($payload), true);
            else
                return false;
        }
        
        function base64_url_decode($input) {return base64_decode(strtr($input, '-_', '+/'));}
      

 

Ce qui suit présente les attributs des requêtes et réponses successives que nous échangeons avec le serveur de votre application lors de l'installation.

Requête POST avec le code d'installation

Attribut Description Type Obligatoire
clientToken

  Un jeton client unique

String Oui
installationCode

  Code d'installation (Peut être vide si votre application n'a pas besoin de vérifier ce code).

String Oui
issuedAt (délivré à)

  Date formatée :

  • [0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}[+-][0-9]{4}
String Oui

 

Confirmation de la "response"

La "response" est un objet JSON avec les attributs suivants :

Attribut Description Type Obligatoire
result

  true if success, otherwise false

boolean Oui
expirationDate

  Date formatée :

  • [0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}[+-][0-9]{4}
Non utilisé si votre application est censée être toujours disponible.
String Non
errorMessage

  Message d'erreur si "result = false"

String Non

 

Requête POST avec le jeton d'application

Attribut Description Type Obligatoire
clientToken

  Jeton unique du client

String Oui
clientName

Nom du client

String oui
appToken

  Le jeton de l'application

String Oui
refreshToken

  Le jeton d'actualisation de l'application.   Non utilisé si le jeton de sécurité est permanent.

String Non
createdAt

La date de création du jeton de l'application.

  Date formatée :

  • [0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}[+-][0-9]{4}
Non utilisé si le jeton de sécurité est permanent.
String Non
expiresIn

  Le délai d'expiration du jeton de l'application en secondes. Non utilisé si le jeton de sécurité est permanent.

integer Non
issueAt

  Date formatée :

  • [0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}[+-][0-9]{4}
string Oui
expirationDate

  Date formatée :

  • [0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}[+-][0-9]{4}
  Non utilisé si votre application est censée être toujours disponible.
String Oui

 

Confirmation "response"

La "response" est un objet JSON avec les attributs suivants :

Attribut Description Type Obligatoire
result

  true if success, otherwise false

boolean Oui
redirectToConfiguration

  true si nous devons rediriger vers unepage de configuration   false ou undefined dans les autres cas

Boolean Non
visibility   Visibilité de l'application pour les gestionnaires et les ressources.   Les valeurs autorisées sont :
  • Accessible uniquement des managers autorisés : (valeur par défaut si vide)
  • Accessible de tous les managers : (tous les gestionnaires)
  • Accessible uniquement des managers autorisés & de toutes les ressources
  • Accessible de tous les managers & ressources
String Non
errorMessage

  Message d'erreur si "result = false"

String Non
Désinstallez votre application

Pour désinstaller votre application, vous devrez :

Vous serez invité avec une fenêtre de confirmation. Une fois que vous avez confirmé, la désinstallation d'une application se résume à la suppression du jeton de l'application. le processus est en 2 étapes :

  • Demander à l'hôte de votre application d'autoriser la désinstallation de l'application.
  • Votre serveur confirme l'opération.

Nous enverrons une requête DELETE à l'endpoint /uninstall . Le body est encodé comme nous l'avons fait pour l' installation.

Demande de désinstallation de l'application

Attribut Description Type Obligatoire
clientToken

  Un jeton client unique

String Oui
issuedAt

  Date formatée :

  • [0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}[+-][0-9]{4}
String Oui

 

Confirmation de la "response"

La "response" est un objet JSON avec les attributs suivants :

Attribut Description Type Obligatoire
result

  L'application sera désinstallée quelle que soit la valeur du résultat

boolean Oui
errorMessage

  Message d'erreur si "result = false"

String Non
Aller plus loin

Veuillez consulter les articles suivants pour vous aider à aller plus loin dans vos développements d'application :

  • Utilisation de l'application
  • Hello App example
  • Publiez votre App: nous permettons aux clients de publier leurs Apps sur notre Marketplace. Ces applications doivent passer par un processus de validation lorsque nous examinons l'application. La condition préalable à cette étape est que le champ API autorisée doit être défini. Pour démarrer le processus de validation, utilisez le bouton Publier à côté de Installer.

Nous espérons que cet article vous a été utile et nous vous invitons grandement à nous l'indiquer en votant juste en dessous.

S'il vous reste des questions sans réponse alors n'hésitez surtout pas à contacter notre service Support qui reste à votre écoute :

Contacter le support

Tel : (+33) 03 62 27 61 05

Boondmanager-Mascot-Desk-lg.png

Cet article vous a-t-il été utile ?
Utilisateurs qui ont trouvé cela utile : 2 sur 2

Commentaires

0 commentaire

Vous devez vous connecter pour laisser un commentaire.