Piano Analytics Collection API

Piano Analytics is the successor of AT Internet Analytics Suite 2 (AS2). It's a user-centric tool that simplifies product & marketing analytics, while ensuring data quality. Your data will be sent server-side getting the most from Piano Analytics' Collection API and in form of events.

The Collection API is only available for Piano Analytics. You can check the following compatibility table to get more insights on supported features by product.

Key features

The Piano Analytics Collection API destination provides the following key features:

• Events structure: our Events reference matches Piano Analytics' one, meaning that your data is properly bridged to the expected fields in an optimized way.

• Prebuilt mappings: data mapping for event-based destinations happens automatically, which simplifies user inputs.

• Custom events: you can freely push custom events based on your specific needs.

• Support for multi-item data: information included in the item array is dispatched to Piano Analytics.

• User identifier: you can openly select a user identifier field for logged users.

• Support autopromo events: include pre-prepared autopromo events in your requests. See Autopromo events for more details.

• Send all properties: send all your event properties to Piano Analytics with a single click.

Destination setup

Before you get started with this destination, ensure you have access to Piano Analytics.

The client-side unique visitor identifier is recommended and is retrieved by getting the value of the _pcid , pa_vid , atuserid , or xtidc cookie in this priority order.

Configuration

Settings	Description
Side Id	Required The identifier of the site the data belongs to (E.g. 628087). This can be found in the Piano Analytics interface following ➜ SETTINGS ➜ Data Collection Portal ➜ Tools ➜ Site Management and selecting your site. This setting supports dynamic values [1].
Secured Collection Domain	Required The SSL Domain on which information is collected (E.g. logs1412.xiti.com). This can be found in Piano Analytics interface following ➜ SETTINGS Data Collection Portal ➜ Tools ➜ Site Management and selecting your site.
User Identifier	You can set your user identifier for logged users. More details are available following this LINK.
Custom Property	When selecting "[Custom Property]" as value for the above User Identifier, this field will show up so you can specify a custom field holding the value for the user identifier [2].
Client Identifier	You can set a specific client identifier as our context.device.sdk_id or a custom property holding its value. When keeping the "Default" value, or the first mentioned options don't result in a valid value, this is your client-side unique visitor identifier from cookies as detailed in the Destination setup. If no cookie is available, the property user.tcId is used. More details are available following this LINK.
Custom Property	When selecting "[Custom Property]" as value for the above Client Identifier, this field will show up so you can specify a custom field holding the value for the client identifier [2].
Custom Event Mapping: "view_item" matched with Piano "product.page_display"	Flagging this option will match your view_item event with Piano product.page_display event. See Quick reference for more information on event mapping.
Send Autopromo Events	This enables autopromo events. See Autopromo events for more details.
Send All Properties	When activating this option all properties included in the root of your Commanders Act events are also sent to Piano Analytics in the data object. More details are available following this LINK.
Custom Event Properties	Map your custom event properties by setting their field names in Piano Analytics property name and adding the field name holding the value in Your event property . E.g. if you input size in the Piano Analytics property name and items.0.product.size in Your event property , you'll have a custom event property in Piano Analytics called size with a value based on the content of the field items.0.product.size [2]. In the column Your event property path you should keep the default value Default (root) as it better fits most scenarios. In case you select either In "items" {items.X} or In "product" {items.X.product} this destination will look for the input event property starting from the items or product level respectively and add its values as a custom item property. To ensure that custom event properties are picked up by Piano Analytics, you need to create them first by following ➜ SETTINGS ➜ Data Management ➜ Data Model ➜ Properties .
Custom User Properties	Map your custom user properties by setting their field names in User property name and adding the field name holding the value in Commanders Act event property or static value . E.g. if you input customer_zipcode in User property name and user.zipcode [2] in Commanders Act event property or static value , you will have a custom user property in Piano Analytics called customer_zipcode with a value based on the content of the field user.zipcode . You also have the option to set a static string/numeric value in Commanders Act event property or static value . To ensure that custom user properties are picked up by Piano Analytics, you need to create them first by following ➜ SETTINGS ➜ Data Management ➜ Data Model ➜ Properties .

[1] This feature allows you to set an event property holding a dynamic value by adding two open braces ( {{ ) in front of your property name and two close braces ( }} ) at the end (E.g. {{myEventPropertyPathAndName}} ). [2] Using "dots" (".") you can navigate deeper to the specific field you want to get the value of. See Events reference for more details on the standard field names by event. You can also freely set custom fields: there are no boundaries.

Quick reference

Piano Analytics video/audio events are supported by our event model.

Commanders Act Events	Piano Analytics Events
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 or product.page_display [1]
purchase	transaction.confirmation and 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] [*]

[*] Custom events must be added to the Piano Analytics' data model first or they won't be processed. You can add new events by following ➜ SETTINGS ➜ Data Management ➜ Data Model ➜Events. [1] If page_type is equal to product then product.page_display is sent, otherwise, page.display . [2] A product.purchased will be sent for each product being purchased. [3] Flagging Custom Event Mapping: "view_item" matched with Piano "product.page_display" (See Destination setup) maps your view_item with Piano product.page_display , otherwise your event will be matched with Piano product.display .

Field mappings

Commanders Act Properties	Piano Analytics Properties
(event_timestamp)	device_timestamp_utc [1]
context.page.referrer	previous_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
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) or (page.location.href)	src_medium [7]
(page.url) or (page.location.href)	src_campaign [8]
(page.url) or (page.location.href)	src_variant [9]
(page.url) or (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
channel	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] In seconds. [2] Field included for the following events: add_to_cart , page_view (product.page_display) , view_item , purchase (product.purchased) , remove_from_cart , add_to_wishlist , and select_item . [3] Boolean value: true or false . [4] Sum all items.X.quantity . [5] Depending on the drop-down selection (See User Identifier in theConfigurationsection), a specific Commanders Act property is used. [6] Field converted to string. [7] Parsed from the utm_medium parameter in the provided url. [8] Parsed from the utm_campaign parameter in the provided url. [9] Parsed from the utm_content parameter in the provided url. [10] Parsed from the utm_creative_format parameter in the provided url. [11] This is either "Live" or "Recorded Broadcast".

Headers parameters

Commanders Act Properties	Piano Analytics Fields
device.user_agent	User-Agent
page.url page.location.href	Referer
device.ip	X-Forwarded-For

Autopromo events

When sending page_view and click.action events, you can add autopromotions, by setting the array field autopromos . See the following example:

...
"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"
          }
        }
],
...

Each position in the array needs to include a valid Piano Analytics event and is forwarded as it's. In the above example, two additional events are included in a single request to Piano Analytics. This feature needs to be activated in the "Advanced Setting" by flagging the "Send Autopromo Events" option - See Configuration for more details.