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

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 :

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

Query Parameters

Request Body

Exemples de récupération du token :

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
	$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 -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

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

{
    // 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>

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>