Les avantages pour vous
Ce tutoriel vous explique comment configurer et utiliser la base de données AppsDB dans votre application d'expérience à l'aide d'un ensemble d'outils développeur proposés par Showpad. Il présuppose que vous avez suivi et terminé le tutoriel de création de votre première application d'expérience .
Nous allons créer et enrichir notre application d'expérience avec les fonctionnalités hors ligne suivantes :
- extraire des entrées globales de la base de données AppsDB
- extraire des entrées utilisateur de la base de données AppsDB
- publier des entrées utilisateur dans la base de données AppsDB
Vous allez voir des notes expliquant des trucs, astuces et infos pour les développeurs plus avancés. Vous pouvez tout à fait les ignorer pour suivre ce tutoriel. Au bas de cette page, vous trouverez des fichiers ZIP « avant et après » montrant l'état du projet au début et à la fin.
Remarque : L'application Windows actuelle utilise IE11 comme moteur de rendu. Notre application ne fonctionnera pas dessus, car notre syntaxe va être de type ES6.
Ce qu'il vous faut pour réussir
- toutes les conditions requises pour créer votre première application d'expérience
- un client pour exécuter des requêtes API tel que https://www.getpostman.com
- la dernière version bêta de notre SDK, car notre version actuelle ne fonctionnera pas au moment où nous rédigeons ce tutoriel
- avoir activé AppsDB sur votre domaine
Procédez étape par étape
Nous avons préparé un fichier ZIP dans lequel vous trouverez des fichiers index.html, application.js, application.css et config.json que vous pouvez copier-coller dans votre propre projet. Ouvrez maintenant votre terminal dans le répertoire et lancez le serveur de développement Showpad
showpad experience serve
Vous verrez que nous avons divisé le contenu en quatre blocs :
- interroger les ressources.
- afficher et agir sur les ressources.
- écrire des données sur une nouvelle ressource ou télécharger les données dans la base de données AppsDB.
- afficher les données recueillies dans la base de données AppsDB
Concepts
Avant de commencer à mettre en œuvre la base de données AppsDB, passons en revue quelques-uns des concepts de cette nouvelle fonctionnalité. AppsDB est une base de données clé-valeur pour les développeurs d'applications Showpad. Elle est accessible en exploitant l'API JavaScript depuis une application d'expérience ou à l'aide de l'API REST.
Base de données (« store »)
La base de données est un objet de haut-niveau qui regroupe plusieurs entrées de tableau. Vous devez enregistrer la base de données avant de pouvoir l'utiliser. Cela se fait à l'aide d'une requête POST vers le point de terminaison du la base de données .
Entrée de tableau (« store entry »)
Une entrée de tableau est l'objet qui contient vos données. Une entrée de tableau est identifiée par un ID et contient une valeur sous forme de chaîne. Chaque entrée de tableau est contenue dans une base de données et est associée à une portée.
Portée (« scope »)
La portée est la limite d'autorisation depuis laquelle une entrée est accessible. Il existe actuellement deux portées. La portée « USER » et la portée « GLOBAL ».
Portée USER
Lorsqu'une entrée est créée dans la portée « USER », cette entrée est associée à l'utilisateur Showpad qui l'a créée. Cela signifie que chaque utilisateur peut avoir son propre ensemble d'entrées dans la même base de données, sans entrer en collision avec les entrées d'un autre utilisateur. Même si les entrées USER sont limitées à un seul utilisateur, il est possible d'afficher toutes les entrées de tous les utilisateurs dans la base de données en utilisant l'appel store entries . Notez que cet appel nécessite l'ajout d'une portée OAuth2 « appsdb*online*integrations » qui peut être définie dans votre client OAuth2 ou en créant un jeton d'accès personnel.
Portée GLOBAL
Les entrées créées dans la portée « GLOBAL » peuvent être retrouvées par tous les utilisateurs mais ne peuvent être créées que lorsque le demandeur dispose de la portée OAuth2 « appsdb*online*integrations ».
Pagination
La base de données AppsDB utilise une pagination au curseur avec une limite facultative. Lors de l'appel d'une liste d'entrées USER ou GLOBAL volumineuse, nous limitons le nombre d'entrées affichées (voir la documentation sur l'API REST). Chaque fois qu'une de ces limites est atteinte, nous renvoyons une chaîne curseur qui peut être passée à une requête ultérieure pour recevoir la page d'entrées suivante. Si aucun curseur n'est renvoyé, toutes les entrées ont été affichées.
Remarque : Lorsque les cas d'utilisation hors ligne sont importants pour l'intégration de la base de données AppsDB avec l'expérience, il est conseillé de stocker les données qui ne changeront pas dans une seule entrée de tableau ou dans le moins d'entrées de tableau possibles. Pour les données susceptibles de changer, placez-les dans le niveau logique qui convient dans plusieurs entrées de tableau.
Créer des bases de données
Pour les besoins de ce tutoriel, nous allons créer deux bases de données : « TUTORIAL_COMPANIES » et « TUTORIAL_LEADS ». Allez dans postman (ou équivalent) et modifiez les valeurs « yourdomain » et « personalaccesstoken » de l'appel.
Vous pouvez créer un jeton d'accès personnel en suivant ces étapes : Dans le back-end, cliquez sur l'engrenage et appuyez sur Intégrations. Cliquez ensuite sur le bouton Jetons API, indiquez un nom et votre jeton sera créé. Veillez à conserver le jeton dans un endroit sûr car vous ne pourrez plus le voir.
POST https://yourdomain.showpad.biz/api/v3/appsdb/stores/TUTORIAL_COMPANIES https://yourdomain.showpad.biz/api/v3/appsdb/stores/TUTORIAL_LEADS
Utilisez les en-têtes suivants
{
"Authorization": "Bearer personalaccesstoken",
"Content-Type": "application/json"
}
Vous devriez recevoir une réponse 201 signifiant que notre base de données a été créée.
Créer des entreprises
Nous voulons maintenant ajouter des entreprises à notre base de données « TUTORIAL_COMPANIES ». Allez dans postman (ou équivalent) et modifiez les valeurs « yourdomain », « uuid » et « company name » de l'appel.
PUT https://yourdomain.showpad.biz/api/v3/appsdb/stores/TUTORIAL_COMPANIES/globals/entries/uuid
Ajouter le corps suivant à votre demande (brut)
{
"value": "nom de l'entreprise"
}
Vous devriez recevoir une réponse 202 signifiant que notre base de données a été créée ou mise à jour. Créez autant d'entreprises que vous le souhaitez. Les bases de données GLOBAL peuvent être peuplées depuis toutes sortes de systèmes externes : CRM, DAM, PIM, etc. et peuvent fournir au commercial les dernières données disponibles, même lorsqu'il est hors ligne.
Pour les tests locaux, vous devrez appliquer un SHIM à votre base de données GLOBAL. Créez un nouveau fichier appelé globalStores.json dans votre répertoire racine et saisissez les entreprises simulées suivantes :
{
"TUTORIAL_COMPANIES": {
"593ffc7f-1cea-4c03-af40-07f5fa1708bc": "Entreprise a",
"ca563568-1d3f-4440-8af1-410a025038aa": "Entreprise b",
"dd1f0c78-0983-4021-b6b2-da8f1bedeb11": "Entreprise c"
}
}
Pendant votre programmation, vous pouvez maintenant accéder aux entrées GLOBAL de la base de données « TUTORIAL_COMPANIES ».
Afficher les entreprises
Nous voulons que notre application d'expérience lise les entreprises saisies. Pour cela, nous utilisons la méthode ShowpadLib.getGlobalStoreEntries().
1. Remplacez le commentaire « //DISPLAY COMPANIES » par le bloc de code suivant dans la fonction displayData()
window.ShowpadLib.getGlobalStoreEntries('TUTORIAL_COMPANIES', {}, (data) => { document.getElementById('capture_data_company').innerHTML = ''
if (data !== null) { if (data.entries.length > 0) { for (var h = 0; h < data.entries.length; h++) { let parsedCompany = data.entries[h].value let company = document.createElement('option')
company.innerHTML = parsedCompany company.value = parsedCompany.
document.getElementById('capture_data_company').appendChild(company) } } } })
2. Cela extraira toutes les entrées « GLOBAL » de la base de données « TUTORIAL_COMPANIES ». Nous vérifions si la base de données existe et si elle contient des entrées. Ensuite, nous bouclons les entrées et ajoutons chaque entrée en option à notre sélection.
Créer un prospect
Nous voulons que notre application d'expérience crée un prospect et l'enregistre dans notre base de données « TUTORIAL_LEADS » dans la base de données AppsDB. Pour cela, nous utilisons la méthode ShowpadLib.setStoreEntryValue().
1. Remplacez le commentaire « //CREATE LEAD » par le bloc de code suivant dans la fonction actions().
let lead = {
'name': document.querySelector('#capture_data #capture_data_name').value,
'company': document.querySelector('#capture_data #capture_data_company').value
}
window.ShowpadLib.setStoreEntryValue('TUTORIAL_LEADS', uuidv4 (), JSON.stringify(lead))
ShowpadLib.displayToast ({
type: "info",
text: "données ajoutées à AppsDB"
})
setTimeout (() => {
displayData()
}, 500)
2. Cela publiera notre prospect accompagné d'un identifiant unique dans la base de données « TUTORIAL_LEADS ». La valeur d'une entrée doit toujours être une chaîne. Pour créer des données plus structurées, vous pouvez utiliser « parse » et « stringify » pour les données json.
3. Comme vous pouvez le voir, nous appelons displayData par la suite, car nous voulons que nos prospects apparaissent dans le dernier bloc créé.
Afficher les prospects
Nous voulons que notre application d'expérience affiche nos prospects de la base de données « TUTORIAL_LEADS » dans la base de données AppsDB. Pour cela, nous utilisons la méthode ShowpadLib.getStoreEntries.
1. Remplacez le commentaire « //DISPLAY LEADS » par le bloc de code suivant dans la fonction actions().
window.ShowpadLib.getStoreEntries('TUTORIAL_LEADS', {}, (data) => {
document.getElementById('display_data_table').innerHTML = ''
if (data !== null) {
if (data.entries.length > 0) {
for (var i = 0; i < data.entries.length; i++) {
let parsedLead = JSON.parse(data.entries[i].value)
let lead = document.createElement('tr')
let html = '<td>' + parsedLead.name + '</td>'
html += '<td>' + parsedLead.company + '</td>'
lead.innerHTML = html
document.getElementById('display_data_table').appendChild(lead)
}
}
}
})
Cela extraira tous les entrées USER de la base de données « TUTORIAL_LEADS ». Nous vérifions si la base de données existe et si elle contient des entrées. Ensuite, nous bouclons les entrées et ajoutons chaque entrée en option à notre sélection.
C'est l'heure de lancer notre application ! 🚀
Notre application est à présent prête à être déployée. Nous allons utiliser le SDK pour empaqueter notre application. Accédez à votre outil de ligne de commande dans le répertoire racine de l'application et exécutez la commande suivante :
showpad experience package
- Vous verrez le SDK valider tous nos fichiers et créer un fichier .showpad.
- Vous pouvez maintenant accéder au back-end de votre domaine et ouvrir le créateur de canaux.
- Créez un nouveau canal avec le type « Application d'expérience » et sélectionnez notre fichier .showpad nouvellement créé.
- Après le téléchargement, vous devriez voir notre application mais sans l'initialisation du JS. C'est parce que nous appelons notre fonction init() dans l'appel Showpad .getShowpadApi() qui n'est pas exécuté dans l'aperçu. Cet appel fonctionnera dans le front-end.
Si vous cliquez sur « Modifier », vous verrez la structure que nous avons définie dans le ficher config.json. Comme vous pouvez le voir, vous pouvez modifier les traductions, et ajouter et supprimer des balises à notre application. - Cliquez sur « Publier l'expérience » et attendez que la plateforme publie notre application. Cela peut prendre une minute.
Si vous accédez maintenant au front-end, ouvrez notre application améliorée et trouvez ces prospects.
Trouvez les prospects de tous les utilisateurs
Notre équipe commerciale a fait un excellent travail et a recueilli beaucoup de nouveaux prospects. Vous pouvez maintenant utiliser l'API REST pour regrouper tous ces prospects. Allez dans postman (ou équivalent) et modifiez la valeur « yourdomain » de l'appel.
GET https://yourdomain.showpad.biz/api/v3/appsdb/stores/TUTORIAL_LEADS/users/entries
Utilisez les en-têtes suivants
{
"Authorization": "Bearer personalaccesstoken",
"Content-Type": "application/json"
}
Vous pouvez maintenant utiliser ce point de terminaison pour alimenter d'autres systèmes, comme votre système CRM, et fermer la boucle. Nous espérons que vous voyez la valeur et les possibilités extrêmes que cette fonctionnalité permet. N'hésitez pas à demander plus d'informations à la communauté !
Pour finir
Vous pouvez trouver la version finie ci-dessous pour comparer les différences avec votre code.
Les pages « Développeur » sont votre source privilégiée de référence lorsque vous développez votre application d'expérience.
Nous vous invitons à poser vos questions dans la rubrique « Communauté » afin que les autres développeurs puissent répondre à vos questions et que tout le monde puisse apprendre les uns des autres.
Bon codage !
