Enrichissements

Définition générale

Les Enrichissements sont des tableaux contenant des propriétés alimentant Piano Analytics.
Ils se composent d'une propriété utilisée en tant que clé et de propriétés associées qui peuvent être alimentées par des valeurs spécifiques dès qu'une clé est détectée dans les données.

Exemple

Si la donnée envoyée dans les hits contient le product_id:123456, vous serez en mesure de requêter les autres propriétés et obtenir les valeurs correspondantes pour cet identifiant via les autres colonnes de votre enrichissement.

Accès

Droits

Les Enrichissements ne peuvent être définis et édités que par les utilisateurs suivants :

• Administrateurs

• Data Supervisors

Localisation

Vous pouvez accéder aux Enrichissements en vous rendant dans Data Management > Enrichment (menu latéral gauche).

Tableau de bord

Dès que votre organisation dispose au moins d'un enrichissement, vous verrez la liste des enrichissements depuis le tableau de bord dédié.

Ici, vous trouverez pour chaque enrichissement :

• Le nom de l'enrichissement

• La catégorie de template utilisée

• La propriété utilisée en tant que clé de l'enrichissement

• La date de création de l'enrichissement

• Le statut de la dernière mise à jour par API

• Le statut de la dernière mise à jour par CSV

• La configuration rétroactive (sur les imports Retroactive et Retroactive (former))

Types d'enrichissements

Les enrichissements sont toujours composés d'une structure 1 propriété clé / x propriétés associées.
Ces propriétés associées peuvent varier en fonction du type d'enrichissement.

Portée

Les propriétés associées doivent être du même portée (visite, page vue ou événement que le propriété clé.

Le type d'enrichissement correspond également à une alimentation spécifique des propriétés associées.

Standard

Définition

L'enrichissement Standard permet d'alimenter des propriétés Piano et des propriétés personnalisées. 
Les valeurs renseignées dans les propriétés associées pour une clé alimentent les propriétés associées pour tout nouvel événement (validé) reçu une fois la valeur de la clé et de la/les propriété(s) associée(s) configurée dans l'import.
En cas d'absence de valeur de propriété associée pour une valeur de clé renseignée, la propriété peut s'alimenter avec le contenu d'un tag parameter collecté dans un hit.

Note

Les Enrichissements ne sont disponibles que si au moins un des contrats de votre organisation dispose de l'option Enrichissements standard activée.
Pour bénéficier de l'option, nous vous invitons à contacter notre centre support.

Retroactive

Définition

L'enrichissement Retroactive permet d'alimenter des propriétés personnalisées dédiées.
Les valeurs renseignées par import dans l'enrichissement seront appliquées à tout événement validé (passé/présent/futur).
Ces propriétés associées seront alimentées seulement par les valeurs renseignées dans l'import (elles ne pourront être alimentées par les hits dans le cas où la ligne de l'import serait vide).

Note

Les Enrichissements ne sont disponibles que si au moins un des contrats de votre organisation dispose des Enrichissements standard et rétroactifs activés.
Pour bénéficier des options, nous vous invitons à contacter notre centre support.

Retroactive (former)

Définition

L'enrichissement Retroactive (former) permet d'alimenter des propriétés Piano et des propriétés personnalisées. 
Les valeurs renseignées dans les propriétés associées pour une clé alimentent les propriétés associées pour tout événement validé (passé/présent/futur) reçu une fois la valeur de la clé et de la/les propriété(s) associée(s) configurée dans l'import.
En cas d'absence de valeur de propriété associée pour une valeur de clé renseignée, la propriété peut s'alimenter avec le contenu d'un tag parameter collecté dans un hit.

Note

Les Enrichissements ne sont disponibles que si au moins un des contrats de votre organisation dispose des Enrichissements standard et rétroactifs activés.
Pour bénéficier des options, nous vous invitons à contacter notre centre support.

Note

Ce type d'enrichissement ne peut plus être créé hors utilisation de l'enrichissement Standard > Template E-Commerce > transaction_id (mise à jour de commande).
Les enrichissements de ce type mis en place par le passé sont maintenus et accessibles à l'édition.

Création

Dans Data Management > Enrichment, vous pouvez cliquer sur le bouton "Créer un enrichissement".

Si vous disposez de l'option Enrichissement rétroactif, alors vous pourrez choisir le type d'enrichissement que vous souhaitez mettre en place.

Si vous disposez uniquement de l'option Enrichissement standard, vous serez dirigé directement vers le formulaire de création d'Enrichissement standard.

Création d'Enrichissement Standard

Vous aurez besoin de renseigner la configuration listée ci-dessous.

Nom

Le nom affiché dans le tableau de bord d'enrichissements.

Template

3 catégories de templates sont actuellement disponibles pour créer votre enrichissement:

• Les propriétés disponibles dans le cadre d'un enrichissement utilisant le template AnyID doivent répondre aux critères suivants :

• Type de propriété : STRING / INTEGER

• Traitement de la propriété : Processée

• Statut de la propriété : Validée

• La propriété ne fait pas partie de la liste suivante : event_id, visit_id, visitor_id, rm_session_id, av_session_id, app_sessionid

Les templates ou une propriétés clé grisées dans les listes, représentent ceux déjà utilisés dans un autre enrichissement et par conséquent non disponibles.

Clé sensible à la casse

Vous pouvez choisir de distinguer les clés dans votre enrichissement entre les versions majuscule et minuscule.

Exemple

Si vous sélectionnez Oui, vous aurez deux clés pour des valeurs comme mykey and MyKey, en choisissant Non vous n'auriez qu'une clé.

Alertes

Dans le cas d'une erreur API à l'import de données, nous pouvons vous notifier par e-mail de cette erreur aux e-mails que vous auriez renseigné dans le champ dédié.
Ce champ dispose d'une liste pour vous aider à choisir un utilisateur de votre organisation, vous pouvez également renseigner une adresse e-mail non associée à un compte Piano Analytics.

Structure

Une fois les paramètres précédents renseignés, vous pouvez cliquer sur le bouton Suivant et voir les propriétés que vous pouvez utiliser en tant que colonnes.

Dans la table Colonnes, vous trouverez toutes les propriétés proposées par le template que vous avez sélectionné.
La première ligne représente la propriété utilisée en tant que clé qui ne peut être changée ou supprimée.
Les autres lignes peuvent être supprimées en cliquant sur l'icône corbeille à la fin de la ligne.

Vous pouvez également ajouter d'autre colonnes en les sélectionnant depuis la liste Sélectionner une propriété.

Dans cette liste de propriétés vous trouverez des propriétés correspondant à tous ces critères :

• Statut de la propriété : Validée

• Traitement de la propriété : Processée

• ReadOnly : Non (l'édition des règles de la propriété est disponible)

• Utilisation dans un autre enrichissement : Aucun (actuellement ou précédemment)

• Certaines propriétés sont interdites, même si elles rencontrent ces critères, vous pouvez consulter la liste de propriétés standards interdite ci-dessous

Propriétés restreintes

Création d'Enrichissement Rétroactif

Vous aurez besoin de renseigner la configuration listée ci-dessous.

Nom

Le nom affiché dans le tableau de bord d'enrichissements.

Clé

La clé désigne la propriété consultée par notre système d'enrichissement, une fois sa valeur remontée dans un hit, les propriétés associées seront complétées selon les données que vous importerez.

Vous pouvez choisir en clé toute propriété qui réponde à ces critères.

• Type de propriété : STRING / INTEGER

• Traitement de la propriété : Processée

• Statut de la propriété : Validée

• La propriété ne fait pas partie de la liste suivante :

event_id, visit_id, visitor_id, rm_session_id, av_session_id, app_sessionid

Clé sensible à la casse

Vous pouvez choisir de distinguer les clés dans votre enrichissement entre les versions majuscule et minuscule.

Exemple

Si vous sélectionnez Oui, vous aurez deux clés pour des valeurs comme mykey and MyKey, en choisissant Non vous n'auriez qu'une clé.

Alertes

Dans le cas d'une erreur API à l'import de données, nous pouvons vous notifier par e-mail de cette erreur aux e-mails que vous auriez renseigné dans le champ dédié.
Ce champ dispose d'une liste pour vous aider à choisir un utilisateur de votre organisation, vous pouvez également renseigner une adresse e-mail non associée à un compte Piano Analytics.

Structure

Une fois les paramètres précédents renseignés, vous pouvez cliquer sur le bouton Suivant et créer les propriétés associées de cet import.

Vous disposez de 3 paramètres pour créer ces propriétés associées :

• Nom : libellé d'affichage de la propriété dans les interfaces

• Type : format de la propriété au choix (string/integer/data/boolean/decimal/array string)

• Property key : la clé de propriété qui sera utilisée dans le processing et les appels API

Pour tout ajout de nouvelle propriété, vous devrez renseigner les 3 paramètres et la valider avec le bouton dédié en fin de ligne. Vous pouvez également annuler la création de propriété avec l'icône croix en fin de ligne tant que la structure de l'import n'a pas été sauvegardée.

Une fois vos propriétés renseignées, vous pouvez cliquer sur le bouton de sauvegarde en bas de page.

Importer des données

Une fois la configuration de votre enrichissement définie, vous pouvez importer les données de votre table d'enrichissement.
Pour cela, vous pouvez vous appuyer sur 3 méthodes d'imports différentes.

API

Pour utiliser l'API afin de gérer les imports, il est important de suivre plusieurs règles :

• Méthode POST obligatoire

• Présence du header x-api-key 

• Le body JSON doit être correctement formatté

• Des vérifications sont faites sur les paramètres de l'appel :

• {codeOrga} : présent et en majuscule

• {importId} : présent

Vous pouvez lire notre article dédié sur la récupération d'une API key permettant l'utilisation de l'API.

Une fois votre API key récupérée, vous pouvez vous rendre dans l'interface d'enrichissement, puis sur l'onglet Importer des données. Vous y trouverez les informations requises à l'utilisation de l'API avec un exemple. L'import par API fonctionnant par clé, cette méthode ne permet d'importer les données que pour une clé par appel.

sFTP

Vous pouvez également vous appuyer sur notre sFTP pour importer des fichiers volumineux avec la configuration détaillée de l'import :

• Host

• Login

• Public key

• Folder

Pour créer votre clé sFTP key veuillez vous référer à cette documentation, mais n'hésitez pas à vous rapprocher de vos équipes techniques.

Le moteur d'import ne validera que les fichiers .csv ou .csv.gz.
Vous devriez également télécharger ou copier le header pour vous assurer de vous appuyer sur le format attendu.

CSV

En utilisant un fichier CSV, il est important de suivre certaines règles :

• Le séparateur utilisé est la virgule

• La taille de l'import ne peut dépasser 10Mb

Vous devriez également télécharger le header pour vous assurer de vous appuyer sur le format attendu.

Note

Pour vous assurer que le format du fichier ou son encodage ne soit pas altéré, nous vous invitons à éditer le fichier csv que nous fournissons depuis un éditeur de texte neutre (pas Excel).

Lequel utiliser ?

Résumé

Une fois l'import de données complété, vous pouvez retrouver un résumé des dernières lignes importées dans l'onglet Reporting.

Dans cet onglet, vous trouverez :

• Le nombre de lignes de votre enrichissement

• Le statut de votre dernier import API

• Le statut de votre dernier import CSV

• L'historique de vos imports CSV avec le statut de chaque import

• Une vue rapide des données présentes, basée sur les dernières données importées

Edition

Configuration

Vous pouvez mettre à jour votre enrichissement en cliquant dessus ou sur l'icône crayon depuis le tableau de bord des enrichissements.
Ci-dessous, vous retrouverez une vue détaillée des possibilités d'éditions d'un enrichissement.

Mise à jour de données

Il est possible de mettre à jour les données à tout moment en ajoutant de nouvelles clés.
Vous pouvez également mettre à jour les valeurs associées à une clé déjà renseignée.

Changer les données associées

La valeur associée à une propriété peut être mise à jour en important une ligne dans votre table avec toutes les colonnes correspondantes renseignées et complétées (pas d'envoi partiel). Si vous mettez à jour la valeur associée, les nouveaux événements avec la clé seront enrichis pour les propriétés associées, mais pas les anciens événements (sauf si l'import est rétroactif comme décrit plus tôt dans cet article). 

Vider les données associées

Vous souhaiterez potentiellement supprimer une valeur associée à une clé pour une colonne spécifique de votre enrichissement.
S'il n'est pas possible de supprimer les données historiques, vous pouvez vous assurer que les nouveaux événements associés à une clé n'enrichissent plus une colonne et ce via différentes méthodes.

API

Si la propriété n'est pas dans l'appel API <DATA>, la valeur de l'enrichissement n'est pas modifiée. 
Si elle était vide, elle reste vide.
Si elle était complétée la valeur enregistrée ne change pas.

Exemple 

Si vous ne souhaitez pas spécifier l'e-mail pourtant présent dans la structure de l'import.

{ 
  "user_id": "12345", 
  "age": 35 
} 

Pour forcer la suppression de la valeur associée, vous devrez spécifier « null » 

{ 
  "user_id": "12345", 
  "email": null, 
  "age": 35 
} 

CSV

La ligne importée dans le CSV sera utilisée. Si une valeur est vide dans le CSV et que l'enrichissement n'avait pas de valeur associée pour cette clé, alors la valeur associée sera vidée.

Exemple 

Dans l'import nous avons

On importe le fichier correspondant à cette structure

Après import, la clé retournera ces valeurs dans les analyses (pour les nouvelles occurrences de la clé).

 Suppression

Un enrichissement ne peut être supprimé. Si vous ne voulez pas enrichir de propriété malgré cela, vous pouvez mettre à jour votre enrichissement pour vider les valeurs associées aux clés.