Piano Analytics Collection API

Piano Analytics est le successeur de AT Internet Analytics Suite 2 (AS2). C’est un outil centré sur l’utilisateur qui simplifie l’analytics produit et marketing, tout en garantissant la qualité des données. Vos données seront envoyées server-side pour tirer le meilleur parti de Piano Analytics Collection API et sous forme d' événements.

The Collection API est uniquement disponible pour Piano Analytics. Vous pouvez consulter le tableau de compatibilité pour obtenir plus d’Insights sur les fonctionnalités prises en charge par produit.

Fonctionnalités clés

La destination Piano Analytics Collection API fournit les fonctionnalités clés suivantes :

• Structure des événements : notre Référence des Events correspondances Un seul de Piano Analytics, ce qui signifie que vos données sont correctement mappées vers les champs attendus de manière optimisée.

• Mappings pré-construits : le mapping des données pour les destinations basées sur les événements se fait automatiquement, ce qui simplifie les saisies utilisateur.

• Événements personnalisés: vous pouvez librement envoyer des événements personnalisés en fonction de vos besoins spécifiques.

• Prise en charge des données multi-éléments : les informations incluses dans le tableau item array est transmis à Piano Analytics.

• Identifiant utilisateur: vous pouvez sélectionner librement un champ d’identifiant utilisateur pour les utilisateurs connectés.

• Prise en charge des événements d’autopromo: incluez des événements d’autopromo préconfigurés dans vos requêtes. Voir Événements d’autopromo pour plus de détails.

• Envoyer toutes les propriétés: envoyez toutes les propriétés de vos événements à Piano Analytics en un seul clic.

Configuration de la destination

Avant de commencer avec cette destination, assurez-vous d’avoir accès à Piano Analytics.

L’identifiant unique visiteur côté client est recommandé et est récupéré en utilisant la valeur du _pcid , pa_vid , atuserid , ou xtidc cookie dans cet ordre de priorité.

Configuration

Settings	Description
ID du site	Requis L’identifiant du site auquel appartiennent les données (Ex. 628087). Celui-ci est disponible dans l’interface Piano Analytics via ➜ SETTINGS ➜ Data Collection Portal ➜ Tools ➜ Site Management et en sélectionnant votre site. Ce paramètre prend en charge des valeurs dynamiques [1].
Domaine de collecte sécurisé	Requis Le domaine SSL sur lequel l’information est collectée (Ex. logs1412.xiti.com). Celui-ci est disponible dans l’interface Piano Analytics via ➜ SETTINGS Data Collection Portal ➜ Tools ➜ Site Management et en sélectionnant votre site.
Identifiant utilisateur	Vous pouvez définir votre identifiant utilisateur pour les utilisateurs connectés. Plus de détails sont disponibles via ce LINK.
Champ personnalisé	Lorsque vous sélectionnez « [Custom Property] » comme valeur pour le champ ci-dessus Identifiant utilisateur, ce champ apparaît afin que vous puissiez spécifier un champ personnalisé contenant la valeur de l’identifiant utilisateur [2].
Identifiant client	Vous pouvez définir un identifiant client spécifique comme notre context.device.sdk_id ou une propriété personnalisée contenant sa valeur. Si vous conservez la valeur « Default », ou si les premières options mentionnées ne donnent pas une valeur valide, il s’agit de votre identifiant unique visiteur côté client depuis les cookies comme détaillé dans la Configuration de la destination. Si aucun cookie n’est disponible, la propriété user.tcId est utilisée. Plus de détails sont disponibles via ce LINK.
Champ personnalisé	Lorsque vous sélectionnez « [Custom Property] » comme valeur pour le champ ci-dessus Identifiant client, ce champ apparaît afin que vous puissiez spécifier un champ personnalisé contenant la valeur de l’identifiant client [2].
Mappage d’événements personnalisé : « view_item » associé avec Piano « product.page_display »	Cocher cette option associera votre view_item événement avec Piano product.page_display événement. Voir Référence rapide pour plus d’informations sur le mappage d’événements.
Envoyer les événements d’autopromo	Cela active les événements d’autopromo. Voir Événements d’autopromo pour plus de détails.
Envoyer toutes les propriétés	Lors de l’activation de cette option, toutes les propriétés incluses à la racine de vos événements sont également envoyées, sans aucune modification, à Piano Analytics dans l’ des données objet. Plus de détails sont disponibles via ce LINK.
Ne pas écraser	Lorsque Envoyer toutes les propriétés est coché, vous pouvez éviter d’écraser des propriétés déjà définies/présentes.
Propriétés d'événement personnalisées	Mappez vos propriétés d'événement personnalisées en définissant leurs noms de champ dans Nom de propriété Piano Analytics et en ajoutant le nom du champ contenant la valeur dans Votre propriété d'événement . Par ex. si vous saisissez size dans le Nom de propriété Piano Analytics et items.0.product.size dans Votre propriété d'événement , vous aurez une propriété d’événement personnalisée dans Piano Analytics appelée size avec une valeur basée sur le contenu du champ items.0.product.size [2]. Dans la colonne Chemin de votre propriété d'événement vous devriez garder la valeur par défaut Default (root) car elle convient mieux à la plupart des scénarios. Dans le cas où vous sélectionnez soit In "items" {items.X} ou In "product" {items.X.product} cette destination recherchera la propriété d'événement d'entrée en partant du items ou product niveau respectivement et ajoutez ses valeurs comme propriété d’item personnalisée. Pour garantir que les propriétés d’événement personnalisées soient prises en compte par Piano Analytics, vous devez d’abord les créer en suivant ➜ SETTINGS ➜ Data Management ➜ Data Model ➜ Propriétés .
Propriétés utilisateur personnalisées	Mappez vos propriétés utilisateur personnalisées en définissant leurs noms de champs dans Nom de propriété utilisateur et en ajoutant le nom du champ contenant la valeur dans Propriété d'événement Commanders Act ou valeur statique . Par ex. si vous saisissez customer_zipcode dans Nom de propriété utilisateur et user.zipcode [2] dans Propriété d'événement Commanders Act ou valeur statique , vous aurez une propriété utilisateur personnalisée dans Piano Analytics appelée customer_zipcode avec une valeur basée sur le contenu du champ user.zipcode . Vous avez également la possibilité de définir une valeur statique chaîne/numérique dans Propriété d'événement Commanders Act ou valeur statique . Pour garantir que les propriétés utilisateur personnalisées soient prises en compte par Piano Analytics, vous devez d’abord les créer en suivant ➜ SETTINGS ➜ Data Management ➜ Data Model ➜ Propriétés .

[1] Cette fonctionnalité vous permet de définir une propriété d'événement contenant une valeur dynamique en ajoutant deux accolades ouvrantes ( {{ ) devant le nom de votre propriété et deux accolades fermantes ( }} ) à la fin (Par ex. {{myEventPropertyPathAndName}} ). &#xNAN;[2] En utilisant des "dots" (".") vous pouvez naviguer plus profondément jusqu'au champ spécifique dont vous souhaitez obtenir la valeur. Voir Référence des Events pour plus de détails sur les noms de champs standards par événement. Vous pouvez également définir librement des champs personnalisés : il n'y a pas de limites.

Référence rapide

Piano Analytics vidéo/audio les événements sont pris en charge par notre modèle d’événements.

Commanders Act Events	Événements Piano Analytics
add_payment_info	cart.payment
add_shipping_info	cart.delivery
add_to_cart	product.add_to_cart
add_to_wishlist	product.add_to_wishlist [*]
begin_checkout	cart.begin_checkout [*]
generate_lead	generate_lead [*]
login	user.login [*]
page_view	page.display ou product.page_display [1]
purchase	transaction.confirmation et product.purchased [2]
refund	refund [*]
remove_from_cart	product.remove_from_cart
search	internal_search_result.display
select_content	select_content [*]
select_item	page.select_item [*]
sign_up	user.sign_up [*]
video_ad_complete video_ad_stop video_complete video_content_complete	av.stop
video_ad_click	av.ad.click
video_ad_playing video_content_playing video_ad_break_complete video_content_quarter_reached	av.heartbeat
video_content_start video_ad_start video_ad_break_start	av.start
video_ad_skip	av.ad.skip
video_buffer_start	av.buffer.start
video_buffer_complete	av.buffer.heartbeat
video_error	av.error
video_fullscreen_off	av.fullscreen.off
video_fullscreen_on	av.fullscreen.on
video_pause	av.pause
video_quality	av.quality
video_resume	av.resume
video_seek_start	av.seek.start
video_share	av.share
video_speed	av.speed
video_start	av.play
video_subtitle_off	av.subtitle.off
video_subtitle_on	av.subtitle.on
video_volume	av.volume
view_cart	cart.display
view_item	product.display [3] product.page_display [3]
view_item_list	page.view_item_list [*]
[Any Other Event]	[Custom Event] [*]

[*] Les événements personnalisés doivent d’abord être ajoutés au data model de Piano Analytics, sinon ils ne seront pas traités. Vous pouvez ajouter de nouveaux événements en suivant ➜ SETTINGS ➜ Data Management ➜ Data Model ➜Événements. &#xNAN;[1] Si page_type est égal à product ensuite product.page_display est envoyé, sinon, page.display . &#xNAN;[2] Un product.purchased sera envoyé pour chaque produit acheté. &#xNAN;[3] Cocher Mappage d’événements personnalisé : « view_item » associé avec Piano « product.page_display » (Voir Configuration de la destination) mappe votre view_item avec Piano product.page_display , sinon votre événement sera associé avec Piano product.display .

Mappings de champs

Propriétés Commanders Act	Propriétés Piano Analytics
event_timestamp	device_timestamp_utc [1]
context.page.referrer	full_url
page_name	page
value	generate_lead_value cart_turnovertaxincluded
currency	generate_lead_currency cart_currency
id	transaction_id generate_lead_id
item_list_name	view_item_list_name
method	login_method sign_up_method
content_type	content_type
item_id	item_id
search_term	ise_keyword
items.X.id	product_id [2]
items.X.product.name	product [2]
items.X.variant	product_variant [2]
items.X.product.brand	product_brand [2]
(items.X.discount > 0)	product_discount [2][3]
items.X.product.price	product_pricetaxincluded [2]
items.X.product.currency	product_currency [2]
items.X.product.category_1	product_category1 [2]
items.X.product.category_2	product_category2 [2]
items.X.product.category_3	product_category3 [2]
items.X.product.category_4	product_category4 [2]
items.X.quantity	product_quantity [2] cart_quantity [4]
items.X.coupon	product_promocode [2]
coupon	transaction_promocode
payment_method	payment_mode
shipping_amount	shipping_costtaxincluded
shipping_tier	shipping_delivery
cart_id	cart_id
revenue	cart_turnovertaxfree
items.length	cart_nbdistinctproduct
user.id user.email user.email_md5 user.email_sha256 [custom_property]	user_id [5]
context.device.manufacturer	device_manufacturer
context.device.model	device_model
context.device.screen.height	device_screen_height
context.device.screen.width	device_screen_width
content_asset_id	av_content_id [6]
(page.url) ou (page.location.href)	src_medium [7]
(page.url) ou (page.location.href)	src_campaign [8]
(page.url) ou (page.location.href)	src_variant [9]
(page.url) ou (page.location.href)	src_format [10]
video_session_id	av_session_id
cursor_position * 1000	av_position
prev_cursor_position * 1000	av_previous_position
time_prev_event	av_duration
prev_event_name	av_previous_event
video_title	av_content
video_category	av_content_type
total_length * 1000	av_content_duration
content_linked	av_content_linked
airdate	av_publication_date
keywords	av_content_genre
program	av_show
season	av_show_season
episode	av_episode_id
episode_label	av_episode
digital	av_channel
publisher	av_author
content_version	av_content_version
content_duration_range	av_content_duration_range
(livestream)	av_broadcasting_type [11]
broadcaster_name	av_broadcaster
ad_type	av_ad_type
video_player	av_player
video_player_version	av_player_version
auto_play	av_auto_mode
video_language	av_language
video_subtitles_language	av_subtitles
video_launch_reason	av_launch_reason
interruption_method	av_player_error
seek_position	av_seek_position
bitrate	av_bitrate
framerate	av_framerate
sound	av_sound
full_screen	av_fullscreen
ad_enabled	av_ad_enabled
image_quality	av_image_quality
content_pod_id ad_pod_id	av_pod_id [6]
video_description	av_description
full_episode	av_full_episode

[1] Le timestamp lié au moment où l’événement a eu lieu. Les timestamps à 10 ou 13 chiffres sont pris en charge : avec ces derniers, le timestamp est converti au format décimal (Ex. 1756195156953 est défini comme 1756195156.953 ). Vous pouvez également définir directement le format décimal avec des timestamps à 13 chiffres. &#xNAN;[2] Champ inclus pour les événements suivants : add_to_cart , page_view (product.page_display) , view_item , purchase (product.purchased) , remove_from_cart , add_to_wishlist , et select_item . &#xNAN;[3] Valeur booléenne : true ou false . &#xNAN;[4] Sommer tous items.X.quantity . &#xNAN;[5] Selon la sélection du menu déroulant (Voir Identifiant utilisateur dans leConfigurationsection), une propriété spécifique Commanders Act est utilisée. &#xNAN;[6] Champ converti en chaîne. &#xNAN;[7] Analysé à partir du utm_medium paramètre dans l’URL fournie. &#xNAN;[8] Analysé à partir du utm_campaign paramètre dans l’URL fournie. &#xNAN;[9] Analysé à partir du utm_content paramètre dans l’URL fournie. &#xNAN;[10] Analysé à partir du utm_creative_format paramètre dans l’URL fournie. &#xNAN;[11] C’est soit « Live » soit « Recorded Broadcast ».

Paramètres d’en-têtes

Propriétés Commanders Act	Champs Piano Analytics
device.user_agent	User-Agent
page.url Propriétés Criteo	Referer
device.ip	X-Forwarded-For

Événements d’autopromo

Lors de l’envoi de page_view et click.action événements, vous pouvez ajouter des autopromotions en définissant le champ array autopromos . Voir l’exemple suivant :

...
« autopromos » : [
        {
          « name » : « self_promotion.display »,
          "data": {
            « onsitead_type » : « Self promotion »,
            « onsitead_campaign » : « trv_tem »,
            « onsitead_category » : « opt_tem »,
            « onsitead_creation » : « https://mysite.com/hp-autopromo.png »,
            « onsitead_detailed_placement » : « hp_autopromo »
          }
        },
        {
          « name » : « self_promotion.display »,
          "data": {
            « onsitead_type » : « Self promotion »,
            « onsitead_campaign » : « trv_tem2 »,
            « onsitead_category » : « opt_tem2 »,
            « onsitead_creation » : « https://mysite.com/hp-autopromo-2.png »,
            « onsitead_detailed_placement » : « hp_autopromo_2 »
          }
        }
],
...

Chaque position dans l’array doit inclure un événement Piano Analytics valide et est transmise telle quelle. Dans l’exemple ci-dessus, deux événements supplémentaires sont inclus dans une seule requête vers Piano Analytics. Cette fonctionnalité doit être activée dans les « Advanced Setting » en cochant l’option « Send Autopromo Events » - Voir Configuration pour plus de détails.