Commanders Act X
Platform XDocumentationWelcome to Success
  • Welcome !
  • Platform updates
    • Announcements
    • Documentation updates
    • Release notes
  • Getting started
    • How the platform works
      • Glossary
        • Condensed platform concepts
    • Platform interface
      • Prod and Testing environments
      • Productivity tools
        • Commander's AI
    • Integrating your data
      • GTM Tutorial
      • OneTag Tutorial
      • Migration guides to the Platform X
        • Migrate from SSv1 to SSv2
          • Send data to serverside v2
            • Purchase event example (ssv1 to ssv2)
        • Migrate from old mobile sdk
  • Features
    • Sources
      • Sources Overview
      • Sources Catalog
        • Web
          • Web container
            • User guides for browser-side platform
              • Container
                • Hosting
                • Creation and modification
                • Generation
                • Testing
                • Deployment and roll back
                • Deletion
                • Statistics
                • Modification history
                • Javascript block
                • Branches
                • Plugin Commanders Act Assistant
              • Tags
                • Add tags
                • Configure tags
                • Rules
                  • Basic actions
                  • Triggers
                  • Perimeters & constraints
              • Data layer and data types
                • External variables
                • Internal variables
                • Event variables
                • Data storage
              • Deduplication
                • Setup guide
                • Setup example
                • Deduplication reports
              • TagPerformance
                • Setup guide
                • Report analysis
                • Troubleshooting
            • Setup guides for developers
              • Web container setup
              • Datalayer setup
              • Browser-side events setup
              • AMP
              • Angular
              • AngularJS
              • React
              • SPA implementation guide
              • VueJS
              • IOT & TV Apps
            • Best Practices
              • FAQ
              • Common Container Strategies
              • Common Trigger Strategies
              • Performance Optimization
              • tC.* attributes and methods
              • APIs
                • Onsite API
              • TMS & Consent banners IDs
          • Javascript SDK
            • Next.js serverside rendering
          • Pixel Tracking API
          • Google Tag Manager (GTM)
          • Shopify
        • Mobile APP
          • Android
          • iOS
          • Flutter
          • React native
        • Advertising
          • Bing Ads (cost import)
          • Facebook Ads (cost import)
          • Criteo (cost import)
          • Realytics
        • Import CRM users
          • API users
          • Users file importer
        • Import conversions
          • API Conversions and Product catalog
          • Conversions files importer
        • Product catalog
          • Product catalog files importer (FTP)
        • Server
          • HTTP tracking API source
            • (deprecated) HTTP tracking API source 1.0
          • Node.JS
          • Python
          • PHP
      • Source Live Event Inspector
      • Source data quality
    • Destinations
      • Destinations overview
        • Automatic Audience replay
      • Destinations catalog
        • AbTasty
        • Actito
        • Adform
        • Adobe
          • Adobe Analytics
          • Adobe Campaign
        • AdRoll
        • Adition
        • Adventori
        • Affilae
        • Alphalyr Marketing Studio
        • Amazon
          • Amazon Ads Conversions API
          • Amazon S3
        • Attraqt
        • Awin
        • Batch Audience
        • Branch Events
        • Button
        • Campaign Analysis Legacy
        • Commission Junction
        • Criteo
          • Criteo - Events
          • Criteo (audiences)
          • Criteo (offline conversions)
        • Data Activation Legacy
        • Dataventure
        • Destination Logs Exporter (closed beta)
        • Dialog-Mail
        • Dynamic Yield
        • Easyence
        • Effinity
        • Eloqua
        • Emarsys
        • Email export
        • Equativ Audience
        • Experian
        • Facebook
          • Facebook Conversions API
            • Facebook CAPI through GTM
            • Performance tab (Event Match Quality)
          • Facebook Custom Audiences
          • Facebook Lead Ads
        • FTP
        • Gamned
        • Google
          • Google Analytics 4
            • Google Analytics 4 - Proxy Mode
          • Google BigQuery
          • Google Conversion Adjustments
          • Google Customer Match
          • Google Display & Video 360
          • Google Enhanced Conversions
          • Google Enhanced Conversions for Leads
          • Google Floodlight Mobile App Conversion
          • Google Search Ads 360 Enhanced Conversions
          • Google Store Sales Direct
        • IBM
        • Inxmail
        • IntelliAd
        • Jellyfish
        • Kameleoon
          • Kameleoon Audience
          • Kameleoon Events
        • Kelkoo
        • Kwanko
        • LinkedIn Conversions API
        • Liveramp
        • Magento
        • Marin Software
        • Mapp
        • Matomo
        • MediaMath
        • Microsoft Advertising Universal Event Tracking
        • Mindlytix
        • Moebel
        • Nextdoor Conversion API
        • OXID
        • Optimizely
        • Outbrain
        • Partnerize
        • Piano Analytics
          • Piano Analytics Collection API
          • Piano Analytics Enrichment API
        • Pinterest
        • Piwik PRO
        • Prediggo
        • Qlik
        • Quantcast
        • Quora Ads Conversion API
        • Rakuten
          • Rakuten Audience
          • Rakuten Events
        • Realytics
        • Reddit Conversions API
        • Responsys
        • RhythmOne
        • Rich Relevance
        • RTB House Audience
        • Salesforce
          • Salesforce Audience Studio
          • Salesforce Marketing Cloud
          • Salesforce Commerce Cloud
        • SAP Commerce Cloud
        • Selligent
        • Skai
        • Smart Adserver
        • SmartFocus
        • Snapchat Conversions API
        • Splio
        • Syte
        • Tableau Online
        • Taboola
          • Taboola Audience
          • Taboola Events
        • Target2sell
        • Temelio
        • Teradata
        • The Trade Desk
          • The Trade Desk Conversions API
          • The Trade Desk Audience
        • TikTok
          • TikTok Events API
          • TikTok Offline Events
        • TimeOne
        • Tradedoubler
        • TradeTracker
        • X (Twitter) Conversion API
        • Xandr
        • Webhook
        • Webtrends
        • ZBO Media
        • Zeta
      • Destination builder
        • Javascript destination builder
          • Tutorial - How to build a server destination with the JS sandbox
          • Serverside javascript helpers
      • Destination filters
      • Mapping and Properties transformation
      • Event delivery
      • Destination event inspector
      • Dry mode (lab)
    • Enrichments
      • Augmented User Attributes
        • Business case
      • Events enrichment
      • Storage Settings
    • Data Quality
      • Event Specification
      • Sources data quality
      • Data cleansing
        • Supported transformation functions - Data cleansing
          • Format a date
    • Identity resolution
      • Migrate from Fuse v1 to Fuse v2
    • Customers
      • Segment
        • Segment overlap
        • Segment stats
    • Explore
      • Campaign analysis
        • Attribution
        • Control Group (Closed Beta )
      • User analysis
        • Dashboards
      • Consent Analysis
    • Consent management
      • Responsability of actors
      • Setup Guides
        • Tag Manager
          • Commanders Act TMS
          • Google Tag Manager (GTM)
          • Google Tag Manager (GTM) - Consent Mode
          • Google Consent Mode in Commanders Act CMP
          • Adobe Launch
        • Websites (Hardcoded)
        • FR : Suppression des cookies lors du retrait du consentement
        • Mobile apps
          • iOS
            • ATT - App Tracking Transparency (iOS 14.5+)
          • Android
      • User Guides
        • Categories & Tags
          • Manage Categories
          • Manage Vendors
          • Assign Categories
        • Privacy Banners
          • Banner Templates
            • Accessibility Template
          • Manage Banner
          • Deploy Banner
          • Copy Banner
        • Consent Analysis
        • Exports
        • Settings
      • Extensions
        • Cookie Scanner
        • Piggybacking
        • Tag Firewall
      • Marketing Preferences Center (additional module)
      • Knowledge Base
        • Consent Object
        • Consent cookies exemption
          • Implementation guide for exempted consent statistics FR market
        • Consent Cookie
        • IAB TCF V2.2 Release details
          • IAB TCF v2.2 CMP requirements
          • IAB TCF v2.2 Migration guide Web
          • IAB TCF v2.2 Migration guide App
        • IAB TCF V2.2 Consent
        • IAB TCF V2.2 and Google FAQ
        • Google ACM requires IAB TCF
        • CCPA & Global Privacy control
      • Rest Data API
        • GET/PUT Consents / preferences
      • OnSite API
        • Getting Started
        • consent.get
        • consent.update
        • consent.revoke
        • consent.onUpdate
        • consent.onReady
        • consentBanner.show
        • consentBanner.hide
        • consentCenter.show
        • consentCenter.hide
      • Platform API
        • Get statistics
  • Use cases
    • Data activation
      • Engage new customers
        • Welcome banner for new customers
        • Real-time promotion for hesitant customers
        • Discount banner for installing the application
        • Personalized ads
        • Engage similar audience (lookalike)
      • Increase loyalty
        • Drive to favourite store
        • Increase Customer Lifetime Value with a loyalty program
        • Notification about order delay
      • Increase revenue
        • Abandoned cart
        • Products recommendations
        • Complementary product offer
      • Retain customers
        • Identify a churn risk with RFM segmentation
        • Identify customers’ preferred channel
        • Contact with the customer support
      • Advocacy
        • Incentive to share customers' experience and rating
        • Sponsorship Program
        • Social Media Hashtag
    • Website performance
    • Consent banners A/B testing
    • Customer analysis
    • Campaigns performance analysis
  • Developers
    • Tracking & Integrations
      • Tracking
        • About events
          • E-commerce/retail events
          • Web event specificity
          • Mobile App event specificity
        • Events reference
          • Common events
          • E-commerce events
          • Video events
          • Campaign Tracking events
        • Properties reference
          • Global properties
          • Video properties
          • Permanent properties
        • Data API
          • HTTP API
          • Segment API
          • User API
          • Product catalog and conversion API
      • Server IP Whitelisting
    • Config API
    • Changelogs
      • Measure.js changelog
      • Web container generator
    • Content Security Policy
  • CONFIGURE
    • Data Management
      • Events collection
      • Data retention duration
      • Data Governance
    • Administration
      • User management
      • Domain Management
        • WAF Proxy (CloudFlare,...)
        • A record
        • CNAME record
        • On-Premise Proxy
        • Cookie CAID
        • First party hosting
      • Single Sign-On
      • Two-factor authentication (2FA)
      • Copy Management
    • Cookies
      • Cookie 1st
      • Cookie sync partners
      • First domain tracking (Phoenix)
    • Disclaimer
Powered by GitBook
On this page
  • Key features
  • Destination setup
  • Configuration
  • Quick reference
  • Field mappings
  • Autopromo events

Was this helpful?

Edit on GitHub
Export as PDF
  1. Features
  2. Destinations
  3. Destinations catalog
  4. Piano Analytics

Piano Analytics Collection API

PreviousPiano AnalyticsNextPiano Analytics Enrichment API

Last updated 5 months ago

Was this helpful?

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' and in form of .

The is only available for . You can check the following 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 matches , 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 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 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 .

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

Configuration

Settings
Description

Side Id

Secured Collection Domain

User Identifier

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

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"

Send Autopromo Events

Send All Properties

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].

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 .

Quick reference

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] [*]

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

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

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

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].

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.

You can set your user identifier for logged users. More details are available following this .

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 . If no cookie is available, the property user.tcId is used. More details are available following this .

Flagging this option will match your view_item event with Piano product.page_display event. See for more information on event mapping.

This enables autopromo events. See for more details.

When 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 .

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 or 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 .

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 for more details on the standard field names by event. You can also freely set custom fields: there are no boundaries.

events are supported by .

[*] 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 ) maps your view_item with Piano product.page_display , otherwise your event will be matched with Piano product.display .

[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 thesection), 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".

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

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 for more details.

Events reference
Piano Analytics video/audio
our event model
page_view
Piano Analytics
Collection API
events
Collection API
Piano Analytics
compatibility table
Events reference
Piano Analytics' one
item
Piano Analytics
_pcid
pa_vid
atuserid
Autopromo events
Configuration
Configuration
LINK
LINK
items
product
LINK
Destination setup
Quick reference
Autopromo events
Destination setup