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
| product_id (as a key) | product_name | product_price | product_brand |
| 123456 | keyboard | 159 | kayaii |
| 654321 | flute | 20 | yamaga |
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.
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:
| Template | Clé | Utilisation |
| CRM | user_id | Pour restituer sa base utilisateur sans passer par le tag. |
| E-Commerce | product_id | Pour transmettre son catalogue produit aux analyses. |
| E-Commerce | transaction_id | Pour mettre à jour les commandes sur le site (accessible uniquement aux clients disposant de l'option Enrichissements Retroactif). |
| AV Insights | av_content_id | Pour transmettre son catalogue de contenu AV aux analyses. |
| Any ID | au choix | Pour alimenter les propriétés Piano et personnalisées sans passer par le tag depuis une propriété de votre choix.* |
* 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
| Property Key | Property Type | Property Name |
| app_fsmn | INTEGER | App - First session month number |
| app_fsw | INTEGER | App - First session week |
| app_fswd | STRING | App - First session weekday |
| app_fswdn | INTEGER | App - First session weekday number |
| app_fswy | INTEGER | App - First session year of week |
| app_fsy | INTEGER | App - Year of first session |
| app_sessionid | STRING | App - Session ID |
| app_visitor_status | STRING | App - Visitor status |
| av_buffer_total_duration | INTEGER | AV Session - Buffering time |
| av_content_duration | INTEGER | AV Content - Duration |
| av_content_genre | ARRAY_STRING | AV Content - Genre |
| av_content_time_consumed | INTEGER | AV Session - Duration of content consumed |
| av_location | STRING | AV Content - Location |
| av_playback_completion_rate | DECIMAL | AV Session - Completion rate |
| av_playback_total_duration | INTEGER | AV Session - Playback time |
| av_position | INTEGER | AV - Cursor position |
| av_rebuffer_total_duration | INTEGER | AV Session - Rebuffering time |
| av_session_backward | BOOLEAN | AV Session - Backward movement |
| av_session_bounce | BOOLEAN | AV Bounced session |
| av_session_buffering | BOOLEAN | AV Session - With buffering |
| av_session_content_duration | INTEGER | AV Session - Content duration |
| av_session_error | BOOLEAN | AV Session - With error |
| av_session_forward | BOOLEAN | AV Session - Forward movement |
| av_session_last_event | STRING | AV Session - Last event |
| av_session_rebuffering | BOOLEAN | AV Session - With rebuffering |
| av_session_time | DATE | AV Session - Start time |
| av_session_time_utc | DATE | AV Session - Start time (UTC) |
| browser | STRING | Browser |
| browser_cookie_acceptance | BOOLEAN | Cookie accepted? |
| browser_group | STRING | Browser - Group |
| browser_language | STRING | Browser - Language |
| browser_language_local | STRING | Browser local language |
| browser_version | STRING | Browser - Version |
| cart_id | STRING | Cart ID |
| cart_lifetime | INTEGER | Cart lifetime |
| click_full_name | STRING | Click - with levels |
| connection_isp | STRING | ISP |
| connection_organisation | STRING | Connection organisation |
| date | DATE | Date |
| date_day | STRING | Weekday |
| date_daynumber | INTEGER | Day number |
| date_month | STRING | Month |
| date_monthnumber | INTEGER | Month number |
| date_week | INTEGER | Week |
| date_year | INTEGER | Year |
| date_yearofweek | INTEGER | Year (week) |
| device_brand | STRING | Device - Brand |
| device_display_height | INTEGER | Window height |
| device_display_width | INTEGER | Window width |
| device_hour | INTEGER | Device hour |
| device_name | STRING | Device - Marketing name |
| device_name_tech | STRING | Device - Technical name |
| device_screen_diagonal | DECIMAL | Screen diagonal (inch) |
| device_screen_height | INTEGER | Screen height |
| device_screen_width | INTEGER | Screen width |
| device_type | STRING | Device - Type |
| event_collection_platform | STRING | Collection platform |
| event_collection_version | STRING | Collection tag version |
| event_hour | INTEGER | Hour |
| event_id | STRING | Event ID |
| event_minute | INTEGER | Minute |
| event_name | STRING | Event |
| event_position | INTEGER | Event position |
| event_second | INTEGER | Second |
| event_time | DATE | Event timestamp |
| event_time_utc | DATE | Event timestamp (UTC) |
| event_url | STRING | URL event |
| event_url_domain | STRING | Domain event |
| exclusion_cause | STRING | Exclusion cause |
| exclusion_type | STRING | Exclusion type |
| geo_city | STRING | City |
| geo_continent | STRING | Continent |
| geo_country | STRING | Country |
| geo_latitude | DECIMAL | Latitude |
| geo_longitude | DECIMAL | Longitude |
| geo_metro | STRING | Sub-region |
| geo_region | STRING | Region |
| hit_time_utc | DATE | Event collected time(UTC) |
| ise_result | STRING | Internal search - Result |
| os | STRING | OS |
| os_group | STRING | OS - Group |
| os_version | STRING | OS version |
| os_version_name | STRING | OS version (marketing name) |
| page_customcat1_id | STRING | Page category ID - 1st level |
| page_customcat2_id | STRING | Page category ID - 2nd level |
| page_customcat3_id | STRING | Page category ID - 3rd level |
| page_duration | INTEGER | Inter-pages duration |
| page_full_name | STRING | Page - with levels |
| page_position | INTEGER | Page - Position |
| privacy_status | STRING | Privacy status |
| product_promocode | ARRAY_STRING | Promotion code (product) |
| site | STRING | Site |
| site_env | STRING | Site environment |
| site_id | INTEGER | Site ID |
| site_level2_id | INTEGER | Level 2 site ID |
| site_platform | STRING | Site platform |
| src | STRING | Source |
| src_aff_identifier_id | INTEGER | Affiliate ID |
| src_aff_type_id | INTEGER | Affiliate type ID |
| src_campaign_ad | STRING | Ad - Campaign |
| src_campaign_aff | STRING | Affiliation - Campaign |
| src_campaign_deprecated | STRING | Source - Campaign (full name) |
| src_campaign_email | STRING | Emailing - Campaign |
| src_campaign_id | INTEGER | Source campaign ID |
| src_campaign_rss | STRING | RSS campaign |
| src_campaign_sl | STRING | SEA - Campaign |
| src_creation_id | INTEGER | Creation source ID |
| src_detail | STRING | Source - Detail |
| src_direct_access | STRING | Direct access |
| src_email_link_id | INTEGER | Email clicked link ID |
| src_email_recipient_id | INTEGER | Emailing recipient ID |
| src_email_recipient_list_id | INTEGER | Email recipient list ID |
| src_email_type | STRING | Email - Type |
| src_organic | STRING | Previous URL - Category |
| src_organic_detail | STRING | Previous URL - Detail |
| src_portal_domain | STRING | Portal site - Domain |
| src_portal_site | STRING | Portal site |
| src_portal_site_id | INTEGER | Portal site - ID |
| src_portal_url | STRING | Portal site - URL |
| src_referrer_site_domain | STRING | Referrer site - Domain |
| src_referrer_site_url | STRING | Referrer - URL |
| src_referrer_url | STRING | Source - URL |
| src_se | STRING | Search engine |
| src_se_category | STRING | Search engine - Category |
| src_se_country | STRING | Search engine - Location |
| src_sl_network_id | INTEGER | SEM network ID |
| src_sl_platform | STRING | SEA - Platform |
| src_sl_platform_id | INTEGER | SEM platform ID |
| src_social_networks | STRING | Social network |
| src_type | STRING | Campaign / Organic |
| src_url | STRING | Previous URL |
| src_url_domain | STRING | Previous URL - Domain |
| src_variant_id | INTEGER | Source variant ID |
| src_webmail | STRING | Webmail |
| transaction_date | DATE | Transaction date |
| transaction_id | STRING | Transaction ID |
| transaction_promocode | ARRAY_STRING | Promotion code (transaction) |
| user_recognition | BOOLEAN | User recognised? |
| visit_bounce | BOOLEAN | Bounce visit? |
| visit_converted | BOOLEAN | Visit converted? |
| visit_duration | INTEGER | Visit duration |
| visit_entry_aisle1 | STRING | Entry aisle - 1st level |
| visit_entry_aisle2 | STRING | Entry aisle - 2nd level |
| visit_entry_aisle3 | STRING | Entry aisle - 3rd level |
| visit_entry_aisle4 | STRING | Entry aisle - 4th level |
| visit_entry_aisle5 | STRING | Entry aisle - 5th level |
| visit_entry_aisle6 | STRING | Entry aisle - 6th level |
| visit_entry_site_level2 | STRING | Entry level 2 site |
| visit_entrypage | STRING | Entry page |
| visit_entrypage_chapter1 | STRING | Entry page - 1st level |
| visit_entrypage_chapter2 | STRING | Entry page - 2nd level |
| visit_entrypage_chapter3 | STRING | Entry page - 3rd level |
| visit_entrypage_full_name | STRING | Entry page - with levels |
| visit_exit_site_level2 | STRING | Exit level 2 site |
| visit_exitpage | STRING | Exit page |
| visit_exitpage_chapter1 | STRING | Exit page - 1st level |
| visit_exitpage_chapter2 | STRING | Exit page - 2nd level |
| visit_exitpage_chapter3 | STRING | Exit page - 3rd level |
| visit_exitpage_full_name | STRING | Exit page - Full name |
| visit_hour | INTEGER | Visit start - Hour |
| visit_id | STRING | Visit ID |
| visit_implication_degree | INTEGER | Implication degree (visit) |
| visit_minute | INTEGER | Visit start - Minute |
| visit_page_views | INTEGER | Page views (visit) |
| visit_sales | DECIMAL | Turnover (visit) |
| visit_second | INTEGER | Visit start - Second |
| visit_time | DATE | Visit start - Date |
| visitor_id | STRING | Visitor ID |
| visitor_privacy_consent | BOOLEAN | Visitor consent |
| visitor_privacy_mode | STRING | Visitor mode |
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.
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 ?
| Complexité technique | Taille de fichier | Fréquence | Méthode d'import |
| Facile | Léger (<10Mb) | Ponctuel | CSV |
| Moyenne | 5Gb | Ponctuel | sFTP |
| Moyenne | 1 clé par appel API | Fréquent | API |
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.
| Paramètre | Nom | Template | Sensible à la casse | Alertes | Structure |
| Edition permise | Oui | Non | Non | Oui | Oui |
| Détails | La clé ne peut être changée. | Le réglage ne peut être changé. | Les propriétés utilisées une fois dans un enrichissement rétroactif ne peuvent pas être retirées des colonnes. |
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
|
user_id |
|
age |
|
12345 |
myEmail@mail.com |
35 |
On importe le fichier correspondant à cette structure
|
user_id |
|
age |
|
12345 |
35 |
Après import, la clé retournera ces valeurs dans les analyses (pour les nouvelles occurrences de la clé).
|
user_id |
|
age |
|
12345 |
35 |
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.