General definition
Enrichments are tables containing properties that feed Piano Analytics.
They consist of a property used as a key and associated properties that can be fed with specific values as soon as a key is detected in the data.
Example
| product_id (as a key) | product_name | product_price | product_brand |
| 123456 | keyboard | 159 | kayaii |
| 654321 | flute | 20 | yamaga |
If the data sent in the hits contains the product_id:123456, you will be able to query the other properties and obtain the corresponding values for this identifier via the other columns of your enrichment.
Access
Access rights
Enrichments can only be defined and edited by the following users:
- Administrators
- Data Supervisors
Location
You can access Enrichments by going to Data Management > Enrichment (left side menu).
Dashboard
As soon as your organisation has at least one enrichment, you will see the list of enrichments from the dedicated dashboard.
Here you will find for each enrichment :
- The name of the enrichment
- The template category used
- The property used as a key for the enrichment
- The date the enrichment was created
- The status of the last update by API
- The status of the last update by CSV
- The retroactive configuration (on Retroactive and Retroactive (former) imports)
Types of Enrichments
Enrichments are always composed of a 1 key property / x associated properties structure.
These associated properties can vary according to the type of enrichment.
The type of enrichment also corresponds to a specific supply of associated properties.
Standard
Definition
The Standard enrichment is used to feed Piano properties and custom properties.
The values entered in the associated properties for a key feed the associated properties for any new (validated) event received once the value of the key and the associated property(ies) are configured in the import.
If there is no associated property value for a key value, the property can be fed with the content of a parameter tag collected in a hit.
Options
Enrichments are only available if at least one of your organisation's contracts has the Standard Enrichments option activated.
To benefit from this option, please contact our support centre.
Retroactive
Definition
The Retroactive enrichment is used to populate dedicated custom properties.
The values entered by import in the enrichment will be applied to any validated event (past/present/future).
These associated properties will only be fed by the values entered in the import (they cannot be fed by hits if the import line is empty).
Options
Enrichments are only available if at least one of your organisation's contracts has Standard and Retroactive Enrichments activated.
To benefit from the options, please contact our support centre.
Retroactive (former)
Définition
The Retroactive Enrichment (former) allows you to populate Piano properties and custom properties.
The values entered in the associated properties for a key feed the associated properties for any validated event (past/present/future) received once the value of the key and the associated property(ies) are configured in the import.
If there is no associated property value for a key value, the property can be fed with the content of a parameter tag collected in a hit.
Options
Enrichments are only available if at least one of your organisation's contracts has Standard and Retroactive Enrichments activated.
To benefit from the options, please contact our support centre.
Availability
This type of enrichment can no longer be created when not using the Standard enrichment > E-Commerce Template > transaction_id (order update).
Enrichments of this type set up in the past are maintained and accessible for editing.
Creation
In Data Management > Enrichment, you can click on the "Create an enrichment" button.
If you have the Retroactive Enrichment option, then you will be able to choose the type of enrichment you wish to set up.
If you only have the Standard Enrichment option, you will be taken directly to the Standard Enrichment creation form.
Creating a Standard Enrichment
You will need to fill in the configuration listed below.
Name
The name displayed in the Enrichments dashboard.
Template
3 categories of templates are currently available to create your enrichment:
| Template | Key | Usage |
| CRM | user_id | To restore your user base without going through the tag. |
| E-Commerce | product_id | To transmit your product catalogue to the analyses. |
| E-Commerce | transaction_id | To update orders on the site (only available to customers with the Retroactive Enrichments option). |
| AV Insights | av_content_id | To transmit its AV content catalogue to the analyses. |
| Custom ID | your key | To feed the Piano and custom properties without going through the tag from a property of your choice*. |
* The properties available for enrichment using the Custom ID template must meet the following criteria: :
- Property type: STRING / INTEGER
- Property treatment: Processed
- Property status: Validated
- The property is not one of the following: event_id, visit_id, visitor_id, rm_session_id, av_session_id, app_sessionid
Templates or a key properties that are greyed out in the lists represent those already used in another enrichment and therefore not available.
Case-sensitive key
You can choose to distinguish the keys in your enrichment between upper and lower case versions.
Example
If you select Yes, you will have two keys for values such as mykey and MyKey, choosing No would give you only one key.
Alerts
In the event of an API error when importing data, we can notify you by email of this error to the emails you would have entered in the dedicated field.
This field has a list to help you choose a user from your organisation, you can also enter an email address not associated with an Piano Analytics account.
Structure
Once you have filled in the previous parameters, you can click on the Next button and see the properties that you can use as columns.
In the Columns table, you will find all the properties proposed by the template you have selected.
The first row represents the property used as a key that cannot be changed or deleted.
The other rows can be deleted by clicking on the bin icon at the end of the row.
You can also add other columns by selecting them from the Select property list.
In this list of properties you will find properties that match all these criteria:
- Property status: Validated
- Property treatment: Processed
- ReadOnly: No (editing of property rules is available)
- Use in another enrichment : None (currently or previously)
- Some properties are prohibited, even if they meet these criteria, you can consult the list of standard prohibited properties below
Prohibited properties
| 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 |
Creating a Retroactive Enrichment
You will need to fill in the configuration listed below.
Name
The name displayed in the Enrichments dashboard.
Key
The key designates the property consulted by our enrichment system, once its value is brought up in a hit, the associated properties will be completed according to the data you import.
You can choose as a key any property that meets these criteria.
- Property type: STRING / INTEGER
- Property treatment: Processed
- Property status: Validated
- The property is not part of the following list:
event_id, visit_id, visitor_id, rm_session_id, av_session_id, app_sessionid
Case-sensitive key
You can choose to distinguish keys in your enrichment between upper and lower case versions.
Example
If you select Yes, you will have two keys for values such as mykey and MyKey, choosing No would give you only one key.
Alerts
In the event of an API error when importing data, we can notify you by email of this error to the emails you would have entered in the dedicated field.
This field has a list to help you choose a user from your organisation, you can also enter an email address not associated with an Piano Analytics account.
Structure
Once the previous parameters have been filled in, you can click on the Next button and create the associated properties for this import.
You have 3 parameters to create these associated properties:
- Name: label for displaying the property in the interfaces
- Type : format of the property (string/integer/data/boolean/decimal/array string)
- Property key: the property key that will be used in processing and API calls
To add a new property, you must fill in the 3 parameters and validate it with the dedicated button at the end of the line. You can also cancel the property creation with the cross icon at the end of the line as long as the import structure has not been saved.
Once your properties are filled in, you can click on the save button at the bottom of the page.
Import data
Once your enrichment configuration is set up, you will need to add data to the table.
To do so you can rely on 3 different import types.
API
To use the API in order to mange imports, it is important to follow several rules:
- Mandatory POST method
- Presence of the header x-api-key
- The body of the JSON should be correctly formatted
- Checks on the call parameters are made:
- {codeOrga} : present and in capital letters
- {importId} : present
You can read our dedicated article on how to retrieve an API key allowing you to use the API.
Once your API key has been retrieved, you can go to the enrichment interface, select the enrichment of your choice and access the Import Data tab. You can find in there the API to use with an example.
sFTP
You can also rely on our sFTP to upload large files relying on the details of your import:
- Host
- Login
- Public key
- Folder
To create your sFTP key please refer to this documentation, please feel free to reach out to your tech teams to assist you on creating this key.
Please note that the engine expects a .csv or .csv.gz format to process the file.
You should also download the header to make sure to rely on the expected format.
CSV
When using a CSV file it is important to follow several rules:
- The separator to use is the comma
- The size of the import file cannot exceed 10 Mb
You should also download the header to make sure to rely on the expected format.
Note
To make sure the file format or encoding is not altered by any program, please edit the csv file we provide with the most neutral text editor (not Excel).
Which one should you use?
| Technical difficulty | File size | Frequency | Import type |
| Easy | Light (<10Mb) | Punctual | CSV |
| Medium | 5Gb | Punctual | sFTP |
| Medium | 1 key per call | Frequent | API |
Summary
Once you imported data, you can see a preview of your table in the Reporting tab.
In this tab you can find:
- The number of lines of your import
- The status of your last API import
- The status of your last CSV import
- The history of your CSV imports with the status of all imports
- A short preview of the data held in your enrichment table based on your last imports
Edition
Configuration
You can update an enrichment by clicking on it or on its pencil icon in the Enrichment dashboard.
Below is a detailed view of the ability to edit the configuration of an enrichment.
| Parameter | Name | Template | Case-sensitivity | Retroactivity | Alerting | Columns |
| Edition allowed | Yes | No | No | No | Yes | Yes |
| Details | The key cannot be changed. | The setting cannot be changed. | The setting cannot be changed. | Properties used once in a retroactive or retroactive (former) enrichment cannot be deleted from the columns. |
Update data
It is possible to update your enrichment's data at any time by adding new keys.
And you can also update the values associated to an already existing key.
Change the associated data
The value of an associated property can be updated by importing the line of your table with all columns filled as you want your enrichment done (no partial update of a line). If you updated the associated value, new events with the key will be enriched with the latest values while former events will not be updated (unless you rely on retroactive imports as described earlier in this article).
Empty the associated data
You may want to delete the value associated to a key for a specific column in your enrichment.
While you cannot delete historical data, you can make sure new events with this key will not enrich the column through different methods.
API
If the property is not in the API call in <DATA>, the value stored in our catalog isn’t modified.
If it was empty, it remains empty
If it was completed, the recorded value is not changed.
Example
If we don’t want to specify the email however defined in the import structure
{
"user_id": "12345",
"age": 35
}
To force the deletion of a value stored in the catalog, you must specify « null »
{
"user_id": "12345",
"email": null,
"age": 35
}
CSV
The line imported into the CSV will be used. If a value is empty in the CSV and in our database we had a value for this cell, it will clear the value and make it empty.
Example
In the import we have
|
user_id |
|
age |
|
12345 |
myEmail@mail.com |
35 |
We import the following file
|
user_id |
|
age |
|
12345 |
35 |
After the update we will have
|
user_id |
|
age |
|
12345 |
35 |
Deletion
An enrichment cannot be deleted, if you do not want any new event to be enriched, you can update your enrichments to empty the values associated to your key.