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

SettingsDescription

Side Id

Secured Collection Domain

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.

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 .

[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

Commanders Act EventsPiano 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] [*]

Field mappings

Commanders Act PropertiesPiano 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 PropertiesPiano 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.

Last updated