Déployer un tableau de bord dans votre application (Embedded analytics)

Introduction

Les tableaux de bord préparés dans le logiciel Biwee peuvent être intégrés au sein d’une autre application. L’API d’intégration Biwee s’occupe du mécanisme et de la communication entre Biwee et votre application.

Les tableaux de bord sont restitués au format HTML et incorporés via une balise iframe. Il est alors possible de les incorporer dans un site web, une application web ou une application classique.

Mise en place de l'intégration par API

Pour intégrer un tableau de bord, vous devez posséder une clé API au niveau de votre société. Cette clé est personnelle et secrète et constitue vos identifiants.

Pour consulter ou générer votre clé API, rendez-vous dans le backoffice (backoffice.biwee.fr), dans le menu Sociétés. Cliquez sur une société, pour visualiser sa clé API.

Vous pouvez vous générer ou regénérer une clé API, en cliquant sur le crayon vert à droite du nom de la société.

Pour intégrer un tableau de bord dans votre application, voici les 3 grandes étapes :

Intégration d'un tableau de bord en API

Détail des étapes d'intégration

1. Rendre le tableau de bord accessible par API

Dans le logiciel Biwee, après avoir sauvegardé le tableau de bord, aller dans le menu "Partager" et cocher la case "Accessible en API", l'icône Code Api n'est plus grisée.

En cliquant sur Code API, un exemple de code d’intégration pour votre tableau de bord vous est présenté :

1. Récupérez les parties de code qui vous intéressent :

• votre clé API

• l'appel de la méthode getToken()

• l'URL d'appel du tableau de bord : https://www.biwee.fr/Tdb/...
• le GUID de votre tableau de bord

• l'exemple de code d'initialisation du session_id, ainsi que le code de fermeture de session

Dans l'exemple en PHP fourni par Biwee, l'identifiant de session est celui de la session PHP retourné par session_id(). L'identifiant de session sera utilisé au moment où l'utilisateur se déconnecte de votre application. Le même identifiant de session doit être utilisé pour l'affichage du tableau de bord et pour la fermeture de session. Ainsi, cela assure que lorsqu’un utilisateur de votre application ferme sa session, il ne peut plus accéder aux tableaux de bord.

3. Dans le code de votre application côté serveur appelez la méthode getToken

GetToken

POST https://www.biwee.fr/Api/GetToken/apiKey/sessionId/dashboardGuid

Récupérer un token en pouvant remplacer la chaîne de connexion avec des logs supplémentaires. Ce token a une durée de vie de 2h et peut être invalidé par un appel à la méthode Logout.

Path Parameters

Name	Type	Description
apiKey*	string	Votre clé d'Api
sessionId*	string	Identifiant de l'utilisateur au sein de votre application qui sera ensuite utilisé lors de l'appel à la fonction logout qui ferme la session du tableau de bord et invalide le token
dashboardGuid*	string	Identifiant du tableau de bord

Query Parameters

Name	Type	Description
SQLparameters	string	Dans le cas d'un jeu de données connecté à une base de données SQL, vous avez la possibilité de passer des valeurs de paramètres dynamiquement. Ces valeurs sont passées à la requête SQL au moment de son exécution.

Request Body

Name	Type	Description
Content	object	Objet JSON pouvant contenir les champs suivants : - ConnectionString : chaine de connexion à utiliser pour afficher le tableau de bord - User : information permettant d'identifier l'utilisateur qui ouvre le tableau de bord dans votre application - Organization : information permettant d'identifier l'organisation à laquelle appartient l'utilisateur qui ouvre le tableau de bord - CustomInfo (Permettent l'ajout de données supplémentaire dans notre base de données à des fins d'analyses statistiques.)

200 Token à utiliser pour appeler la méthode GetDashboard

Attention à ce que ce token soit généré par utilisateur. Si vous avez un système de cache sur vos pages, veillez à ce que le cache soit bien par utilisateur et non global.

Exemples de récupération du token :

.Net

string apiKey = "votreCleApi";
string sessionId = "leSessionId";
string dashboardGuid = "leGuidDeVotreTableauDeBord";

HttpClient client = new HttpClient();

//Informations supplémentaires pouvant être envoyées
var data = new
{
    ConnectionString = "La chaîne de connexion",
    User = "Votre utilisateur",
    Organization = "La société de l'utilisateur",
    CustomInfo = "Information"
};

string json = JsonSerializer.Serialize(data);

// Création des paramètres de la requête HTTP POST
var content = new StringContent(json, Encoding.UTF8, "application/json");
var requestUri = new Uri($"https://www.biwee.fr/Api/GetToken/{apiKey}/{sessionId}/{dashboardGuid}");

// Envoi de la requête HTTP POST et récupération de la réponse
HttpResponseMessage response = await client.PostAsync(requestUri, content);
response.EnsureSuccessStatusCode();

string token = await response.Content.ReadAsStringAsync();

PHP

<?php
	$apiKey = "votreCleApi";
	$sessionId = "leSessionId";
	$dashboardGuid = "leGuidDeVotreTableauDeBord";

	// Informations supplémentaires pouvant être envoyées
	$data = array(
		'ConnectionString' => 'La chaîne de connexion',
		'User' => 'Votre utilisateur',
		'Organization' => 'La société de l\'utilisateur',
		'CustomInfo' => 'Information'
	);

	$json = json_encode($data);

	// Création des paramètres de la requête HTTP POST
	$options = array(
		'http' => array(
			'header' => "Content-type: application/json",
			'method' => 'POST',
			'content' => $json
		)
	);

	$url = "https://www.biwee.fr/Api/GetToken/$apiKey/$sessionId/$dashboardGuid";

	// Envoi de la requête HTTP POST et récupération de la réponse
	$context = stream_context_create($options);
	$result = file_get_contents($url, false, $context);
	$token = substr($tokenGUID, 1, -1);
?>

CURL

curl -X POST "https://www.biwee.fr/Api/GetToken/{apiKey}/{sessionId}/{dashboardGuid}" \
-H 'Content-Type: application/json' \
-d '{"ConnectionString": "La chaîne de connexion",
    "User": "Votre utilisateur",
    "Organization": "La société de l'utilisateur",
    "CustomInfo": "Information"}'

4. Dans le code de votre application côté client appelez l'URL de récupération du tableau de bord, soit dans un IFRAME, soit directement dans une page à part

L'affichage du tableau de bord s'effectue via un appel de l'URL https://www.biwee.fr/Tdb/:token

Vous pouvez passer les paramètres de requête suivants

Paramètre	Description	Exemple d'utilisation
theme	Thème à utiliser pour l'affichage du tableau de bord	theme=dark
color	Couleur de la police des titres	color=cyan color= $7FFF00
background-color	Couleur de fond du tableau de bord	background-color=red background-color=$7FFF00

Exemples

Application du thème dark :

https://www.biwee.fr/Tdb/{token}?theme=dark&background-color=$37474f

Changement de la couleur de fond et la couleur de la police :

https://www.biwee.fr/Tdb/{token}?background-color=$37474f&color=$00b599

Code iframe

<iframe src="https://www.biwee.fr/Tdb/{token}" scrolling="no" style="width:100%; height:100%; border:none;">
</iframe>

Cet appel de l'URL, peut se faire :

• soit dans une iframe au sein d'une page de votre application

• soit via un lien qui appelle cette URL et qui affichera le tableau de bord pleine page dans le navigateur

Par défaut le fond de la page contenant le tableau de bord est blanc. Vous pouvez le personnaliser si vous le souhaitez, soit en spécifiant une couleur de fond et une couleur de police du tableau de bord, soit en choisissant le thème dark. Plus de détail

1. Fermeture de la session

Dans le code de votre application côté serveur appelez la méthode Logout pour invalider le token et fermer la session.

Logout

GET https://www.biwee.fr/api/logout/:apiKey/:sessionId

Permet d'invalider le token créé avec la méthode GetToken

Path Parameters

Name	Type	Description
apiKey*	String	Votre clé d'Api
sessionId*	String	L'identifiant de l'utilisateur que vous avez fourni lors de l'appel à GetToken

200: OK

{
    // Response
}

Passage de paramètres SQL au tableau de bord

Dans le cas d'un jeu de données connecté à une base de données SQL, vous avez la possibilité de passer des valeurs de paramètres dynamiquement. Ces valeurs sont passées à la requête SQL au moment de son exécution.

Lors de l'appel de la méthode GetToken, vous pouvez passer une liste de paramètres SQL qui seront transmis à la/aux requête(s) SQL de votre tableau de bord.

Ces paramètres doivent être passés dans l'url de la méthode GetToken en respectant ce format :

param1=value1,param2=value2,param3=value3

Par exemple si votre tableau de bord contient la requête SQL suivante :

SELECT * FROM Customers
WHERE Country = @country AND AccountTypeId = @typeId

Alors l'url à appeler sera de la forme suivante :

https://www.biwee.fr/Api/GetToken/{apiKey}/{sessionId}/{dashboardGuid}/country=France,typeId=1

Changement de la chaîne de connexion SQL du tableau de bord

Lors de l'appel de la méthode GetToken, vous pouvez passer des paramètres en envoyant les données via un objet JSON sérialisé.

Cet objet peut comporter les champs suivants :

• customInfo

• organization

• user

• connectionString

Le champ « connectionString » permet de spécifier une chaîne de connexion qui sera utilisée par le tableau de bord pour aller se connecter aux données. Cela est utile si vous souhaitez faire varier la chaîne de connexion en fonction des utilisateurs qui consultent le tableau de bord.

Les champs « user », « organization » et « customInfo » permettent l’ajout de données supplémentaires dans notre base de données à des fins d’analyses statistiques sur les connexions et accès aux tableaux de bord

Personnalisation du tableau de bord affiché

Personnalisation des couleurs du tableau de bord

Lors de l'appel de la méthode www.biwee.fr/Tdb/ vous pouvez passer en paramètre de requête

• la couleur du fond du tableau de bord, via le paramètre background-color

• la couleur de la police des titres, via le paramètre color

Dans l'exemple ci-dessous, la couleur de fond a été changée en gris anthracite et la couleur de la police en vert.

<iframe src="https://www.biwee.fr/Tdb/{token}?background-color=$37474f&color=$00b599" scrolling="no" style="width:100%; height:100%; border:none;">
</iframe>

Les couleurs utilisables sont toutes les couleurs nommées définies dans les spécifications HTML et CSS, ainsi que les couleurs décrites selon la notation hexadécimale.

Attention : dans le cas d’utilisation de la notation hexadécimale, il faut remplacer le # habituel par un $.

Changement du thème du tableau de bord

Vous pouvez utiliser le thème Dark pour un ou plusieurs tableaux de bord que vous intégrez dans votre application.

Pour cela, il suffit de le spécifier au moment de l'appel de la méthode www.biwee.fr/Tdb/ en rajoutant ?theme=dark

<iframe src="https://www.biwee.fr/Tdb/{token}?theme=dark&background-color=$37474f" scrolling="no" style="width:100%; height:100%; border:none;">
</iframe>