# 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 <mark style="color:blue;">**`xtidc`**</mark> cookie in this priority order.
{% endhint %}

### Configuration

<table><thead><tr><th width="283">Settings</th><th>Description</th></tr></thead><tbody><tr><td><code>Side Id</code></td><td><em><strong><code>Required</code></strong></em><br>The identifier of the site the data belongs to (E.g. <code>628087</code>). This can be found in the Piano Analytics interface following <img src="/files/BDAmaFmpwaeuVzkVgrwK" alt=""> ➜ <code>SETTINGS</code> ➜ <code>Data Collection Portal</code> ➜ <code>Tools</code> ➜ <code>Site Management</code> and selecting your site. This setting supports dynamic values <strong>[1].</strong></td></tr><tr><td><code>Secured Collection Domain</code></td><td><em><strong><code>Required</code></strong></em><br>The SSL Domain on which information is collected (E.g. <code>logs1412.xiti.com</code>). This can be found in Piano Analytics interface following <img src="/files/BDAmaFmpwaeuVzkVgrwK" alt=""> ➜ <code>SETTINGS</code><br><code>Data Collection Portal</code> ➜ <code>Tools</code> ➜ <code>Site Management</code> and selecting your site.</td></tr><tr><td><code>User Identifier</code></td><td>You can set your user identifier for logged users. More details are available following this <a href="https://developers.atinternet-solutions.com/piano-analytics/data-collection/how-to-send-events/collection-api#users">LINK</a>.</td></tr><tr><td><code>Custom Property</code></td><td>When selecting "[Custom Property]" as value for the above <code>User Identifier</code>, this field will show up so you can specify a custom field holding the value for the user identifier <strong>[2]</strong>.</td></tr><tr><td><code>Client Identifier</code></td><td>You can set a specific client identifier as our <code>context.device.sdk_id</code> 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 <a href="#destination-setup">Destination setup</a>. If no cookie is available, the property <code>user.tcId</code> is used. More details are available following this <a href="https://developers.atinternet-solutions.com/piano-analytics/data-collection/how-to-send-events/collection-api#pattern-1">LINK</a>.</td></tr><tr><td><code>Custom Property</code></td><td>When selecting "[Custom Property]" as value for the above <code>Client Identifier</code>, this field will show up so you can specify a custom field holding the value for the client identifier <strong>[2]</strong>.</td></tr><tr><td><code>Custom Event Mapping:</code><br><code>"view_item" matched</code><br><code>with Piano</code><br><code>"product.page_display"</code></td><td>Flagging this option will match your <code>view_item</code> event with Piano <code>product.page_display</code> event. See <a href="#quick-reference">Quick reference</a> for more information on event mapping.</td></tr><tr><td><code>Send Autopromo Events</code></td><td>This enables autopromo events. See <a href="#autopromo-events">Autopromo events</a> for more details.</td></tr><tr><td><code>Send All Properties</code></td><td>When activating this option all properties included in the root of your events are also sent, <strong>without any modification</strong>, to Piano Analytics in the <mark style="color:blue;"><code>data</code></mark> object. More details are available following this <a href="https://developers.atinternet-solutions.com/piano-analytics/data-collection/how-to-send-events/collection-api#event-object">LINK</a>.</td></tr><tr><td><code>Do Not Overwrites</code></td><td>When <code>Send All Properties</code> is checked, you can avoid overwriting properties already set/present.</td></tr><tr><td><code>Custom Event Properties</code></td><td><p>Map your custom event properties by setting their field names in <code>Piano Analytics property name</code> and adding the field name holding the value in <code>Your event property</code> . E.g. if you input <code>size</code> in the <code>Piano Analytics property name</code> and <code>items.0.product.size</code> in <code>Your event property</code> , you'll have a custom event property in Piano Analytics called <code>size</code> with a value based on the content of the field <code>items.0.product.size</code> <strong>[2]</strong>.</p><p>In the column <code>Your event property path</code> you should keep the default value <code>Default (root)</code> as it better fits most scenarios. In case you select either <code>In "items" {items.X}</code> or <code>In "product" {items.X.product}</code> this destination will look for the input event property starting from the <a href="https://community.commandersact.com/platform-x/developers/tracking/events-reference#item">items </a>or <a href="https://community.commandersact.com/platform-x/developers/tracking/events-reference#product">product </a>level respectively and add its values as a custom item property.</p><p><br>To ensure that custom event properties are picked up by Piano Analytics, you need to create them first by following <img src="/files/BDAmaFmpwaeuVzkVgrwK" alt=""> ➜ <code>SETTINGS</code> ➜ <code>Data Management</code> ➜ <code>Data Model</code> ➜ <code>Properties</code> .</p></td></tr><tr><td><code>Custom User Properties</code></td><td><p>Map your custom user properties by setting their field names in <code>User property name</code> and adding the field name holding the value in <code>Commanders Act event property or static value</code> .<br>E.g. if you input <code>customer_zipcode</code> in <code>User property name</code> and <code>user.zipcode</code> <strong>[2]</strong> in <code>Commanders Act event property or static value</code> , you will have a custom user property in Piano Analytics called <code>customer_zipcode</code> with a value based on the content of the field <code>user.zipcode</code> . You also have the option to set a static string/numeric value in <code>Commanders Act event property or static value</code> .<br></p><p>To ensure that custom user properties are picked up by Piano Analytics, you need to create them first by following <img src="/files/BDAmaFmpwaeuVzkVgrwK" alt=""> ➜ <code>SETTINGS</code> ➜ <code>Data Management</code> ➜ <code>Data Model</code> ➜ <code>Properties</code> .</p></td></tr></tbody></table>

{% 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` **\[\*]**                                                                                                 |
| <p><code>video\_ad\_complete</code></p><p><code>video\_ad\_stop</code></p><p><code>video\_complete</code></p><p><code>video\_content\_complete</code></p>                           | `av.stop`                                                                                                                |
| `video_ad_click`                                                                                                                                                                    | `av.ad.click`                                                                                                            |
| <p><code>video\_ad\_playing</code></p><p><code>video\_content\_playing</code></p><p><code>video\_ad\_break\_complete</code></p><p><code>video\_content\_quarter\_reached</code></p> | `av.heartbeat`                                                                                                           |
| <p><code>video\_content\_start</code></p><p><code>video\_ad\_start</code></p><p><code>video\_ad\_break\_start</code></p>                                                            | `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`                                                                                                                                                                         | <p><code>product.display</code> <strong>\[3]</strong></p><p><code>product.page\_display</code> <strong>\[3]</strong></p> |
| `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 ![](/files/BDAmaFmpwaeuVzkVgrwK) ➜ `SETTINGS` ➜ `Data Management` ➜ `Data Model` ➜`Events`.\
> **1.** If <mark style="color:blue;">`page_type`</mark> is equal to <mark style="color:blue;">`product`</mark> then <mark style="color:blue;">`product.page_display`</mark> is sent, otherwise, <mark style="color:blue;">`page.display`</mark> .\
> **2.** A <mark style="color:blue;">`product.purchased`</mark> will be sent for each product being purchased.\
> **3.** Flagging <mark style="color:blue;">`Custom Event Mapping: "view_item" matched with Piano "product.page_display"`</mark> (See [Destination setup](#destination-setup)) maps your <mark style="color:blue;">`view_item`</mark> with Piano <mark style="color:blue;">`product.page_display`</mark> , otherwise your event will be matched with Piano <mark style="color:blue;">`product.display`</mark> .
> {% endhint %}

## Field mappings

| Commanders Act Properties                                                                                                                                                 | Piano Analytics Properties                                                                                          |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| `event_timestamp`                                                                                                                                                         | `device_timestamp_utc` **\[1]**                                                                                     |
| `context.page.referrer`                                                                                                                                                   | `previous_url`                                                                                                      |
| `page_name`                                                                                                                                                               | `page`                                                                                                              |
| `value`                                                                                                                                                                   | <p><code>generate\_lead\_value</code></p><p><code>cart\_turnovertaxincluded</code></p>                              |
| `currency`                                                                                                                                                                | <p><code>generate\_lead\_currency</code></p><p><code>cart\_currency</code></p>                                      |
| `id`                                                                                                                                                                      | <p><code>transaction\_id</code></p><p><code>generate\_lead\_id</code></p>                                           |
| `item_list_name`                                                                                                                                                          | `view_item_list_name`                                                                                               |
| `method`                                                                                                                                                                  | <p><code>login\_method</code></p><p><code>sign\_up\_method</code></p>                                               |
| `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`                                                                                                                                                        | <p><code>product\_quantity</code> <strong>\[2]</strong></p><p><code>cart\_quantity</code> <strong>\[4]</strong></p> |
| `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`                                                                                            |
| <p><code>user.id</code></p><p><code>user.email</code></p><p><code>user.email\_md5</code></p><p><code>user.email\_sha256</code></p><p><code>\[custom\_property]</code></p> | `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`                                                                                                  |
| <p><code>content\_pod\_id</code></p><p><code>ad\_pod\_id</code></p>                                                                                                       | `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.\
> **2.** Field included for the following events: <mark style="color:blue;">`add_to_cart`</mark> , <mark style="color:blue;">`page_view (product.page_display)`</mark> , <mark style="color:blue;">`view_item`</mark> , <mark style="color:blue;">`purchase (product.purchased)`</mark> , <mark style="color:blue;">`remove_from_cart`</mark> , <mark style="color:blue;">`add_to_wishlist`</mark> , and <mark style="color:blue;">`select_item`</mark> .\
> **3.** Boolean value: <mark style="color:blue;">`true`</mark> or <mark style="color:blue;">`false`</mark> .\
> **4.** Sum all <mark style="color:blue;">`items.X.quantity`</mark> .\
> **5.** Depending on the drop-down selection (See <mark style="color:blue;">`User Identifier`</mark> in the[<mark style="color:blue;">`Configuration`</mark>](#configuration)section), a specific Commanders Act property is used.\
> **6.** Field converted to string.\
> **7.** Parsed from the <mark style="color:blue;">`utm_medium`</mark> parameter in the provided url.\
> **8.** Parsed from the <mark style="color:blue;">`utm_campaign`</mark> parameter in the provided url.\
> **9.** Parsed from the <mark style="color:blue;">`utm_content`</mark> parameter in the provided url.\
> **10.** Parsed from the <mark style="color:blue;">`utm_creative_format`</mark> parameter in the provided url.\
> **11.** This is either "Live" or "Recorded Broadcast".
> {% endhint %}

#### Headers parameters

| Commanders Act Properties                                          | Piano Analytics Fields |
| ------------------------------------------------------------------ | ---------------------- |
| `device.user_agent`                                                | `User-Agent`           |
| <p><code>page.url</code></p><p><code>page.location.href</code></p> | `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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://doc.commandersact.com/features/destinations/destinations-catalog/piano-analytics/at-internet.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
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 events are also sent, without any modification, to Piano Analytics in the `data` object. More details are available following this LINK.
`Do Not Overwrites`	When `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` .