# Piano Analytics Collection API [Piano Analytics](https://piano.io/) 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](https://developers.atinternet-solutions.com/piano-analytics/data-collection/how-to-send-events/collection-api) and in form of [events](https://developers.atinternet-solutions.com/piano-analytics/data-collection/how-to-send-events/standard-events). {% hint style="info" %} The [Collection API](https://developers.atinternet-solutions.com/piano-analytics/data-collection/how-to-send-events/collection-api) is only available for [Piano Analytics](https://developers.atinternet-solutions.com/piano-analytics/#what-is-piano-analytics).\ You can check the following [compatibility table](https://developers.atinternet-solutions.com/piano-analytics/#before-i-start) to get more insights on supported features by product. {% endhint %} ## Key features The Piano Analytics Collection API destination provides the following key features: * **Events structure**: our [Events reference](https://community.commandersact.com/platform-x/developers/tracking/events-reference) matches [Piano Analytics' one](https://developers.atinternet-solutions.com/piano-analytics/data-collection/how-to-send-events/standard-events), 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](https://community.commandersact.com/platform-x/developers/tracking/events-reference#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](#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](https://developers.atinternet-solutions.com/piano-analytics/#what-is-piano-analytics). {% hint style="info" %} The client-side unique visitor identifier is recommended and is retrieved by getting the value of the [**`_pcid`**](https://developers.atinternet-solutions.com/piano-analytics/data-collection/general/cookie-storage#since-670) **,** [**`pa_vid`**](https://developers.atinternet-solutions.com/piano-analytics/data-collection/general/cookie-storage#piano-analytics-mobile-sdks) , [**`atuserid`**](https://developers.atinternet-solutions.com/piano-analytics/data-collection/general/cookie-storage#legacy-cookie-management) , or **`xtidc`** cookie in this priority order. {% endhint %} ### Configuration
SettingsDescription
Side IdRequired
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 DomainRequired
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 IdentifierYou can set your user identifier for logged users. More details are available following this LINK.
Custom PropertyWhen 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 IdentifierYou 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 PropertyWhen 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 EventsThis enables autopromo events. See Autopromo events for more details.
Send All PropertiesWhen activating this option all properties included in the root of your events are also sent, without any modification, to Piano Analytics in the data object. More details are available following this LINK.
Do Not OverwritesWhen Send All Properties is checked, you can avoid overwriting properties already set/present.
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 .

{% hint style="info" %} > **\[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}}` ).\ > \&#xNAN;**\[2]** Using "dots" (".") you can navigate deeper to the specific field you want to get the value of. See [Events reference](https://community.commandersact.com/platform-x/developers/tracking/events-reference) for more details on the standard field names by event. You can also freely set custom fields: there are no boundaries. > {% endhint %} ## Quick reference {% hint style="info" %} [Piano Analytics video/audio](https://developers.atinternet-solutions.com/piano-analytics-tagging-en/event-tagging-piano-analytics-en/standard-event-tagging-en/#audio-video_31) events are supported by [our event model](https://doc.commandersact.com/developers/tracking/events-reference/video-event-reference). {% endhint %} | 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]` **\[\*]** | {% hint style="info" %} > **\[\*]** 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 ![](https://1259070148-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-Mk6XpTQ2LaRLcr2tA-d%2Fuploads%2Fgit-blob-5aed90690b9e24f27ec864bad486d53d8dda30e9%2F1.png?alt=media) ➜ `SETTINGS` ➜ `Data Management` ➜ `Data Model` ➜`Events`.\ > \&#xNAN;**\[1]** If `page_type` is equal to `product` then `product.page_display` is sent, otherwise, `page.display` .\ > \&#xNAN;**\[2]** A `product.purchased` will be sent for each product being purchased.\ > \&#xNAN;**\[3]** Flagging `Custom Event Mapping: "view_item" matched with Piano "product.page_display"` (See [Destination setup](#destination-setup)) maps your `view_item` with Piano `product.page_display` , otherwise your event will be matched with Piano `product.display` . > {% endhint %} ## 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

| | `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)` 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` | {% hint style="info" %} > **\[1]** The timestamp related to when the event took place. Both 10 or 13-digit timestamps are supported: with the latter, the timestamp is converted in the decimal format (E.g. `1756195156953` is set as `1756195156.953` ). You can also directly set the decimal format with 13-digit timestamps.\ > \&#xNAN;**\[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` .\ > \&#xNAN;**\[3]** Boolean value: `true` or `false` .\ > \&#xNAN;**\[4]** Sum all `items.X.quantity` .\ > \&#xNAN;**\[5]** Depending on the drop-down selection (See `User Identifier` in the[`Configuration`](#configuration)section), a specific Commanders Act property is used.\ > \&#xNAN;**\[6]** Field converted to string.\ > \&#xNAN;**\[7]** Parsed from the `utm_medium` parameter in the provided url.\ > \&#xNAN;**\[8]** Parsed from the `utm_campaign` parameter in the provided url.\ > \&#xNAN;**\[9]** Parsed from the `utm_content` parameter in the provided url.\ > \&#xNAN;**\[10]** Parsed from the `utm_creative_format` parameter in the provided url.\ > \&#xNAN;**\[11]** This is either "Live" or "Recorded Broadcast". > {% endhint %} #### 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*](https://doc.commandersact.com/developers/tracking/events-reference/common-events#page_view) and *click.action* events, you can add autopromotions, by setting the array field `autopromos` . See the following example: ```json ... "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](#configuration) for more details.