Standard events

 

Forewords

One of the strengths of Piano Analytics data model is that it offers standard events and properties that are present by default.

These events will allow you to measure the majority of interactions present on your perimeters. So there is no need to reinvent an event from scratch when you just want to measure the loading of a page, or the consultation of a product page! Moreover, the use of these standard events allows us to provide you with dedicated metrics. For example, the time spent per page is a metric linked to the use of the standard page view event page.display.

Each standard event can be linked to standard properties dedicated to it.

However, it is not mandatory to use each of the informed properties, and it is quite possible to add other properties (standard or custom) if you wish.
 

User

In order to track your logged users, you can use the following properties:

PropertiesTypeExample
user_idStringA1192
user_categoryStringPremium
 

Content

 

Pages

Event name :

page.display

Standard properties linked:

PropertiesTypeExample
pageStringArticle3
page_chapter1StringNews
page_chapter2StringPolitique
page_chapter3StringElections

The property definition is available within your data model.

Tagging example:

tag.events.send('page.display',
  {
    'page': 'page name',
    'page_chapter1': 'chapter 1' ,
    'page_chapter2': 'chapter 2' ,
    'page_chapter3': 'chapter 3' 
  }
);
_ = tracker.events.add(name: "page.display", data:
  "page" : "page name",
  "page_chapter1" : "chapter 1",
  "page_chapter2" : "chapter 2",
  "page_chapter3" : "chapter 3"
)
tracker.dispatch()
tracker.Events().add("page.display", new HashMap() {{
  put("page", "page name");
  put("page_chapter1", "chapter 1");
  put("page_chapter2", "chapter 2");
  put("page_chapter3", "chapter 3");
}})
tracker.dispatch();
 

Clicks

Event name :

click.navigation click.action click.exit click.download

Standard properties linked:

propertiesTypeExample
clickStringArticle3
click_chapter1StringNews
click_chapter2StringPolitique
click_chapter3StringElections

The property definition is available within your data model.

Tagging example:

tag.events.send('click.navigation',
  {
    'click': 'click name',
    'click_chapter1': 'chapter 1',
    'click_chapter2': 'chapter 2',
    'click_chapter3': 'chapter 3' 
  }
);
_ = tracker.events.add(name: "click.navigation", data:
  "click": "click name",
  "click_chapter1": "chapter 1",
  "click_chapter2": "chapter 2",
  "click_chapter3": "chapter 3"
)
tracker.dispatch()
tracker.Events().add("click.navigation", new HashMap() {{
  put("click", "click name");
  put("click_chapter1", "chapter 1");
  put("click_chapter2", "chapter 2");
  put("click_chapter3", "chapter 3");
}})
tracker.dispatch();
 

Internal search engine

 

Results display

Event name :

internal_search_result.display

Standard properties linked:

propertiesTypeExample
ise_keywordStringMobile Phone
ise_pageInt2

The property definition is available within your data model.

Tagging example:

tag.events.send('internal_search_result.display',
  {
    'ise_keyword': 'Mobile Phone',
    'ise_page': 2
  }
);
_ = tracker.events.add(name: "internal_search_result.display", data:
  "ise_keyword": "Mobile Phone",
  "ise_page": 2
)
tracker.dispatch()
tracker.Events().add("internal_search_result.display", new HashMap() {{
  put("ise_keyword", "Mobile Phone");
  put("ise_page", 2);
}})
tracker.dispatch();
 

Results clicks

Event name :

internal_search_result.click

Standard properties linked:

propertiesTypeExample
ise_keywordStringMobile Phone
ise_pageInt2
ise_click_rankInt15

The property definition is available within your data model.

Tagging example:

tag.events.send('internal_search_result.click',
  {
    'ise_keyword': 'Mobile Phone',
    'ise_page': 2,
    'ise_click_rank': 15
  }
);
_ = tracker.events.add(name: "internal_search_result.click", data:
  "ise_keyword": "Mobile Phone",
  "ise_page": 2,
  "ise_click_rank": 15
)
tracker.dispatch()
tracker.Events().add("internal_search_result.click", new HashMap() {{
  put("ise_keyword", "Mobile Phone");
  put("ise_page", 2);
  put("ise_click_rank", 15);
}})
tracker.dispatch();
 

Goals

In order to track conversion goals, you can use the following property:

PropertiesTypeExample
goal_typeStringAccount creation
 

On Site Ads

Event name :

publisher.display publisher.click self_promotion.display self_promotion.click

Standard properties linked:

propertiesTypeExample
onsitead_type (required)StringPublisher
onsitead_campaignStringAcquisition
onsitead_categoryStringGold
onsitead_creationStringBanner_main
onsitead_variantStringBlue
onsitead_formatString400×300
onsitead_general_placementStringSidebar
onsitead_detailed_placementStringSidebar_bottom
onsitead_advertiserStringMy Site
onsitead_urlStringwww.mysite.com

The property definition is available within your data model.

awaiti

tag.events.send('publisher.display',
  {
    'onsitead_type': 'Publisher',
    'onsitead_campaign': 'Acquisition',
    'onsitead_category': 'Gold',
    'onsitead_creation': 'Banner_main',
    'onsitead_variant': 'Blue',
    'onsitead_format': '400x300',
    'onsitead_general_placement': 'Sidebar',
    'onsitead_detailed_placement': 'Sidebar_bottom',
    'onsitead_advertiser': 'My Site',
    'onsitead_url': 'www.mysite.com'
  }
);
_ = tracker.events.add(name: "publisher.display", data:
  "onsitead_type": "Publisher",
  "onsitead_campaign": "Acquisition",
  "onsitead_category": "Gold",
  "onsitead_creation": "Banner_main",
  "onsitead_variant": "Blue",
  "onsitead_format": "400x300",
  "onsitead_general_placement": "Sidebar",
  "onsitead_detailed_placement": "Sidebar_bottom",
  "onsitead_advertiser": "My Site",
  "onsitead_url": "www.mysite.com"
)
tracker.dispatch()
tracker.Events().add("publisher.display", new HashMap() {{
  put("onsitead_type", "Publisher",);
  put("onsitead_campaign", "Acquisition",);
  put("onsitead_category", "Gold",);
  put("onsitead_creation", "Banner_main",);
  put("onsitead_variant", "Blue",);
  put("onsitead_format", "400x300",);
  put("onsitead_general_placement", "Sidebar",);
  put("onsitead_detailed_placement", "Sidebar_bottom",);
  put("onsitead_advertiser", "My Site",);
  put("onsitead_url", "www.mysite.com",);
}})
tracker.dispatch();

 

Sales Insights

 

Properties

 

Product properties

PropertyDescriptionTypeMandatoryExample
product_idIDstringYes'LPTAX174'
productLabelstring'Laptop AX174'
product_variantVariantstring'8Go RAM'
product_brandBrandstring'Loptap'
product_discountDiscounted product?booleanfalse
product_pricetaxincludedPrice tax includedfloat1399.90
product_pricetaxfreePrice tax freefloat1120.90
product_currencyCurrency (ISO 4217)string'EUR'
product_stockProduct in stock?booleantrue
product_quantityQuantityint1
product_category1Level 1 categorystring'Hardware'
product_category2Level 2 categorystring'Computer'
product_category3Level 3 categorystring'Gaming'
product_category4Level 4 categorystring'Laptop'
product_cartcreationCart created by this product addition?booleanfalse
product_promocodeProduct promotion codearray of string['BDAY15', 'SUMMER']
 

Cart properties

PropertyDescriptionTypeMandatoryExample
cart_idIDstringYes'HW-8892'
cart_currencyCurrency (ISO 4217)string'EUR'
cart_turnovertaxincludedTurnover tax includedfloat2900.00
cart_turnovertaxfreeTurnover tax freefloat2340.50
cart_creation_utcCart creation date (timestamp UTC in seconds)int1501065673
cart_quantityNumber of productsint3
cart_nbdistinctproductNumber of distinct productsint2
cart_versionWhen updating the cart awaiting payment (adding/removing a product), it will be necessary to generate a new unique version identifier (cart_version) associated with the cart (cart_id). This is necessary when using pending carts/products (cart.awaiting_payment / product.awaiting_payment)string'v1'
 

Transaction properties

PropertyDescriptionTypeMandatoryExample
transaction_idIDstringYes'29984'
transaction_promocodePromo code listarray of string['BLACKFRIDAY', 'VIP']
transaction_firstpurchaseFirst purchase of the customer?booleantrue
 

Shipping properties

PropertyDescriptionTypeMandatoryExample
shipping_deliveryShipping typestring'Express'
shipping_costtaxincludedShipping cost tax includedfloat10.50
shipping_costtaxfreeShipping cost tax freefloat8.00
 

Payment properties

PropertyDescriptionTypeMandatoryExample
payment_modePayment modestring'Credit card'
 

Events

 

product.display

Used to measure the display of a product (not on the product page). For example on a listing page.

Recommended properties:

product_id, product, product_variant, product_brand, product_discount, product_pricetaxincluded, product_pricetaxfree, product_currency, product_stock, product_category1, product_category2, product_category3, product_category4

 

product.page_display

Used to measure the display of a product page.

Recommended properties:

product_id, product, product_variant, product_brand, product_discount, product_pricetaxincluded, product_pricetaxfree, product_currency, product_stock, product_category1, product_category2, product_category3, product_category4

 

product.add_to_cart

Used to measure the addition of a product to the cart.

Recommended properties:

cart_id, product_id, product, product_variant, product_brand, product_discount, product_pricetaxincluded, product_pricetaxfree, product_currency, product_stock, product_category1, product_category2, product_category3, product_category4, product_quantity, product_cartcreation

 

product.remove_from_cart

Used to measure the removal of a product from the basket.

Recommended properties:

cart_id, product_id, product, product_variant, product_brand, product_discount, product_pricetaxincluded, product_pricetaxfree, product_currency, product_stock, product_category1, product_category2, product_category3, product_category4, product_quantity

 

product.awaiting_payment

Used to measure a product waiting for payment.

Recommended properties:

transaction_id, cart_id, product_id, product, product_variant, product_brand, product_discount, product_pricetaxincluded, product_pricetaxfree, product_currency, product_stock, product_category1, product_category2, product_category3, product_category4, product_quantity

 

product.purchased

Used to measure a purchased product.

Recommended properties:

transaction_id, cart_id, product_id, product, product_variant, product_brand, product_discount, product_pricetaxincluded, product_pricetaxfree, product_currency, product_stock, product_category1, product_category2, product_category3, product_category4, product_quantity

 

cart.creation

Used to measure the creation of a basket.

Recommended properties:

cart_id, cart_currency, cart_turnovertaxincluded, cart_turnovertaxfree, cart_quantity, cart_nbdistinctproduct

 

cart.update

Used to measure the update of a basket.

Recommended properties:

cart_id, cart_currency, cart_turnovertaxincluded, cart_turnovertaxfree, cart_quantity, cart_nbdistinctproduct

 

cart.display

Used to measure the display of a basket.

Recommended properties:

cart_id, cart_currency, cart_turnovertaxincluded, cart_turnovertaxfree, cart_quantity, cart_nbdistinctproduct

 

cart.delivery

Used to measure the delivery method selection step.

Recommended properties:

cart_id, cart_currency, cart_turnovertaxincluded, cart_turnovertaxfree, cart_quantity, cart_nbdistinctproduct

 

cart.payment

Used to measure the payment stage.

Recommended properties:

cart_id, cart_currency, cart_turnovertaxincluded, cart_turnovertaxfree, cart_quantity, cart_nbdistinctproduct, shipping_delivery, shipping_costtaxincluded, shipping_costtaxfree

 

cart.awaiting_payment

Used to measure a cart awaiting payment.

Recommended properties:

cart_id, cart_currency, cart_turnovertaxincluded, cart_turnovertaxfree, cart_quantity, cart_nbdistinctproduct, shipping_delivery, shipping_costtaxincluded, shipping_costtaxfree

A transaction.confirmation event with the same cart_id and an offsite_confirmation property (boolean, true) allows to confirm this cart afterwards. A delay of 24 hours is left for the arrival of this confirmation.

 

transaction.confirmation

Used to measure a completed transaction.

Recommended properties:

cart_id, cart_currency, cart_turnovertaxincluded, cart_turnovertaxfree, cart_creation_utc, cart_quantity, cart_nbdistinctproduct, transaction_id, transaction_promocode, transaction_firstpurchase, shipping_delivery, shipping_costtaxincluded, shipping_costtaxfree, payment_mode

 

Audio / Video

 

Specifications

 

Important notes

In order to properly monitor the measurement of your AV content, there are a few things you need to know.

 
play vs playbackStart

The events av.play (play) represent the first click on the play button, which starts loading the video.

The events av.start (playbackStart) represent the playback of the first frame of the content.

The classic sequence of events is therefore av.play followed by av.start. In between, the video loading time can be measured with events av.buffer.start followed by av.buffer.heartbeat..

If you are not able to differentiate these two times, it is necessary to send av.start (playbackStart).

 
start vs resume

If playback is resumed (after a pause or loading time (rebuffer) for example), it will be necessary to send an event av.resume (playbackResumed) rather than av.play.

 
Cursor position management

When using methods related to reading content, the cursor position is required.

This position makes it possible to know the real progress of the reading.

 
Playback speed management

In order to measure the position of the cursor, the libraries calculate the time actually spent playing. By default, one real second will correspond to one second of playing.

However, you can change this playback speed via the method setPlaybackSpeed, by specifying the speed factor.

 

Tracking examples

 
Full playback
 
seek event tracking
 

Automatic processing

Some automatic processings are managed by the tagging libraries.

However, it is necessary to know them and to take them into account when tagging not using libraries.

 
seek (seek start, forward/backward)

When calling a seek (seek) method, several events are raised:

  • av.seek.start, indicating the start of seek, and bearing the cursor position before the move
  • av.forward or av.backward, depending on the start and end positions of the cursor move
  • .
 
session id

Each playback session has a unique identifier (property av_session_id).

A playback session is defined by a content play. It stops if the content changes, or if the video is stopped (av.stop).

 
buffer vs rebuffer

Two types of loading times can be identified:

  • buffer (av.buffer.start (bufferStart) and av.buffer.heartbeat), for loading before the start of playback (between av.play and av.start)
  • rebuffer (av.rebuffer.start (bufferStart) and av.rebuffer.heartbeat), for loading during playback (after av.start)
  • ).

The method bufferStart checks if a playbackStart has been called on the current session, in order to send the corresponding load type.

 
heartbeat

During playback, in order to measure durations more precisely, heartbeat events provide information on the status of the player.
Several types of heartbeat are available:

  • av.heartbeat, triggers after a playbackStart or playbackResumed, allows to measure the content playback
  • av.(re)buffer.heartbeat, triggers after a bufferStart, allows to measure the duration of loading times

The time between two heartbeats is defined at the moment of media instantiation. It can be fixed for the whole playback, or it can evolve via a JSON object.

On short media, we recommend to fill in 5 seconds between each heartbeat, in order to have a fine enough measurement without overloading the user’s network and the collection servers. On larger media, you should space heartbeats with more time, up to 30 minutes in order to keep the playback session alive.

 
duration

The time actually spent in front of the content is filled in the property av_duration, via a timer.

This is the time elapsed in milliseconds between the previous event and the current one.

 
previous event/position

On each event, it is necessary to fill in the position (av_previous_position) and the name (av_previous_event) of the previously sent event.

 

Pattern

 

Common standard properties

PropertyDescriptionTypeMandatoryExample
av_content_idContent IDstringYes'bc35'
av_session_idSession IDuuid*Yes'799d9f3b-7307-5113-a260-2e1371e35fe6'
av_contentContent Labelstring 'Broadchurch 3.5'
av_content_typeContent Typestring 'TV Show'
av_content_durationContent Duration (in milliseconds)int 2760000
av_content_linkedLinked Content Labelstring 'myLinkedContent'
av_publication_datePublication Date (timestamp)date 1501065673
av_content_genreContent genre(s)array of string ["Crime","Drama","Mystery"]
av_showShow Labelstring 'Broadchurch'
av_show_seasonShow Season Labelstring '3'
av_episode_idEpisode IDstring '5'
av_episodeEpisode Labelstring 'Episode #3.5'
av_channelChannel Labelstring 'ITV'
av_authorAuthor Namestring 'Chris Chibnall'
av_content_versionContent Version (full length, …)string 'Full length'
av_content_duration_rangeDuration rangestring '0-10'
av_broadcasting_typeBroadcasting Typestring 'Live'
av_broadcasterBroadcaster Namestring 'ITV'
av_ad_typeAd Typestring 'Mid-roll'
av_playerPlayer Labelstring 'Main'
av_player_versionPlayer Versionstring '1.55'
av_player_positionPlayer Positionstring 'Homepage'
av_auto_modeAuto play modebooleantrue
av_languageMedia languagestring'fr'
av_subtitlesSubtitlesstring'en'
av_launch_reasonLaunch reasonstring'auto'

* uuid type requires a version 5 (random) or version 5 (named) RFC 5122-compliant UUID, otherwise, our processing will generate one to replace the tagged value.

 

Events

 
av.heartbeat
PropertyDescriptionTypeMandatoryExample
av_durationTime spent since previous event (ms)intYes5000
av_positionCurrent event cursor positionintYes15000
av_previous_eventPrevious event namestringYes'av.heartbeat'
av_previous_positionPrevious event cursor positionintYes10000
 
av.buffer.heartbeat
PropertyDescriptionTypeMandatoryExample
av_durationTime spent since previous event (ms)intYes5000
av_positionCurrent event cursor positionintYes15000
av_previous_eventPrevious event namestringYes'av.heartbeat'
av_previous_positionPrevious event cursor positionintYes10000
 
av.rebuffer.heartbeat
PropertyDescriptionTypeMandatoryExample
av_durationTime spent since previous event (ms)intYes5000
av_positionCurrent event cursor positionintYes15000
av_previous_eventPrevious event namestringYes'av.heartbeat'
av_previous_positionPrevious event cursor positionintYes10000
 
av.play
PropertyDescriptionTypeMandatoryExample
av_durationTime spent since previous event (ms)intYes5000
av_positionCurrent event cursor positionintYes15000
av_previous_eventPrevious event namestringYes'av.heartbeat'
av_previous_positionPrevious event cursor positionintYes10000
 
av.buffer.start
PropertyDescriptionTypeMandatoryExample
av_durationTime spent since previous event (ms)intYes5000
av_positionCurrent event cursor positionintYes15000
av_previous_eventPrevious event namestringYes'av.heartbeat'
av_previous_positionPrevious event cursor positionintYes10000
 
av.rebuffer.start
PropertyDescriptionTypeMandatoryExample
av_durationTime spent since previous event (ms)intYes5000
av_positionCurrent event cursor positionintYes15000
av_previous_eventPrevious event namestringYes'av.heartbeat'
av_previous_positionPrevious event cursor positionintYes10000
 
av.start
PropertyDescriptionTypeMandatoryExample
av_durationTime spent since previous event (ms)intYes5000
av_positionCurrent event cursor positionintYes15000
av_previous_eventPrevious event namestringYes'av.heartbeat'
av_previous_positionPrevious event cursor positionintYes10000
 
av.resume
PropertyDescriptionTypeMandatoryExample
av_durationTime spent since previous event (ms)intYes5000
av_positionCurrent event cursor positionintYes15000
av_previous_eventPrevious event namestringYes'av.heartbeat'
av_previous_positionPrevious event cursor positionintYes10000
 
av.pause
PropertyDescriptionTypeMandatoryExample
av_durationTime spent since previous event (ms)intYes5000
av_positionCurrent event cursor positionintYes15000
av_previous_eventPrevious event namestringYes'av.heartbeat'
av_previous_positionPrevious event cursor positionintYes10000
 
av.stop
PropertyDescriptionTypeMandatoryExample
av_durationTime spent since previous event (ms)intYes5000
av_positionCurrent event cursor positionintYes15000
av_previous_eventPrevious event namestringYes'av.heartbeat'
av_previous_positionPrevious event cursor positionintYes10000
 
av.forward
PropertyDescriptionTypeMandatoryExample
av_durationTime spent since previous event (ms)intYes5000
av_positionCurrent event cursor positionintYes15000
av_previous_eventPrevious event namestringYes'av.heartbeat'
av_previous_positionPrevious event cursor positionintYes10000
 
av.backward
PropertyDescriptionTypeMandatoryExample
av_durationTime spent since previous event (ms)intYes5000
av_positionCurrent event cursor positionintYes15000
av_previous_eventPrevious event namestringYes'av.heartbeat'
av_previous_positionPrevious event cursor positionintYes10000
 
av.seek.start
PropertyDescriptionTypeMandatoryExample
av_durationTime spent since previous event (ms)intYes5000
av_positionCurrent event cursor positionintYes15000
av_previous_eventPrevious event namestringYes'av.heartbeat'
av_previous_positionPrevious event cursor positionintYes10000
 
av.ad.click
 
av.ad.skip
 
av.error
PropertyDescriptionTypeMandatoryExample
av_player_errorError messagestring 'Content not available'
 
av.display
 
av.close
 
av.volume
 
av.subtitle.on
 
av.subtitle.off
 
av.fullscreen.on
 
av.fullscreen.off
 
av.quality
 
av.speed
 
av.share
Last update: 06/05/2022