Links

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.
  • 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, orxtidccookie 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
SETTINGSData Collection PortalToolsSite 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 PortalToolsSite 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 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 Event property name and adding the field name holding the value in Commanders Act event property or static value. E.g. if you inputsizein the Event property name and items.0.product.size in Commanders Act event property or static value, you'll have a custom event property in Piano Analytics calledsizewith a value based on the content of the field items.0.product.size [2]. You also have the option to set a static string/numeric value in Commanders Act event property or static value. To ensure that custom event properties are picked up by Piano Analytics, you need to create them first by following
SETTINGSData ManagementData ModelProperties.
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 inputcustomer_zipcodein 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 calledcustomer_zipcodewith 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
SETTINGSData ManagementData ModelProperties.
[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
SETTINGSData ManagementData ModelEvents. [1] Ifpage_typeis equal toproductthenproduct.page_displayis sent, otherwise,page.display. [2] Aproduct.purchasedwill be sent for each product being purchased. [3] FlaggingCustom Event Mapping: "view_item" matched with Piano "product.page_display"(See Destination setup) maps yourview_itemwith Piano product.page_display, otherwise your event will be matched with Piano product.display.

Field mappings

Commanders Act Properties
Piano Analytics Properties
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 [1]
items.X.product.name
product [1]
items.X.variant
product_variant [1]
items.X.product.brand
product_brand [1]
(items.X.discount > 0)
product_discount [1][2]
items.X.product.price
product_pricetaxincluded [1]
items.X.product.currency
product_currency [1]
items.X.product.category_1
product_category1 [1]
items.X.product.category_2
product_category2 [1]
items.X.product.category_3
product_category3 [1]
items.X.product.category_4
product_category4 [1]
items.X.quantity
product_quantity [1]
cart_quantity [3]
items.X.coupon
product_promocode [1]
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 [4]
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 [5]
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 [6]
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 [5]
video_description
av_description
full_episode
av_full_episode
[1] 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, andselect_item. [2] Boolean value:trueorfalse. [3] Sum allitems.X.quantity. [4] Depending on the drop-down selection (SeeUser Identifierin theConfigurationsection), a specific Commanders Act property is used. [5] Field converted to string. [6] This is either "Live" or "Recorded Broadcast".

Headers parameters

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