# Piano Analytics Developers Documentation
> Everything you need to know to master your data
This file contains all documentation content in a single document following the llmstxt.org standard.
## Consent rules by Consent Mode
## opt-in
Details
| Storage | Events | Properties | | :------ | :----- | :--------- | | All | All | All |
## essential
Details
| Storage | Events | Properties |
| ------- | ---------------- | ---------------------------- |
| _pcid | click.action | app_crash |
| _pctx | click.download | app_crash_class |
| _pprv | click.exit | app_crash_screen |
| | click.navigation | app_version |
| | page.display | browser |
| | | browser_cookie_acceptance |
| | | browser_group |
| | | browser_version |
| | | ch_ua\* |
| | | click |
| | | click_chapter1 |
| | | click_chapter2 |
| | | click_chapter3 |
| | | click_full_name |
| | | connection_monitor |
| | | connection_organisation |
| | | connection_type |
| | | date |
| | | date_day |
| | | date_daynumber |
| | | date_month |
| | | date_monthnumber |
| | | date_week |
| | | date_year |
| | | date_yearofweek |
| | | device_brand |
| | | device_display_height |
| | | device_display_width |
| | | device_name |
| | | device_name_tech |
| | | device_screen_diagonal |
| | | device_screen_height |
| | | device_screen_width |
| | | device_timestamp_utc |
| | | device_type |
| | | event_collection_platform |
| | | event_collection_version |
| | | event_hour |
| | | event_id |
| | | event_minute |
| | | event_name |
| | | event_position |
| | | event_second |
| | | event_time |
| | | event_time_utc |
| | | event_url |
| | | event_url_domain |
| | | event_url_full |
| | | exclusion_cause |
| | | exclusion_type |
| | | geo_city |
| | | geo_continent |
| | | geo_country |
| | | geo_metro |
| | | geo_region |
| | | hit_time_utc |
| | | os |
| | | os_group |
| | | os_version |
| | | os_version_name |
| | | page |
| | | page_chapter1 |
| | | page_chapter2 |
| | | page_chapter3 |
| | | page_duration |
| | | page_full_name |
| | | page_position |
| | | page_title_html |
| | | page_url |
| | | pageview_id |
| | | privacy_status |
| | | site |
| | | site_env |
| | | site_id |
| | | site_platform |
| | | src |
| | | src_detail |
| | | src_direct_access |
| | | src_organic |
| | | src_organic_detail |
| | | src_portal_domain |
| | | src_portal_site |
| | | src_portal_site_id |
| | | src_portal_url |
| | | src_referrer_site_domain |
| | | src_referrer_site_url |
| | | src_referrer_url |
| | | src_se |
| | | src_se_category |
| | | src_se_country |
| | | src_type |
| | | src_url |
| | | src_url_domain |
| | | src_webmail |
| | | visit_bounce |
| | | visit_duration |
| | | visit_entrypage |
| | | visit_entrypage_chapter1 |
| | | visit_entrypage_chapter2 |
| | | visit_entrypage_chapter3 |
| | | visit_entrypage_full_name |
| | | visit_exitpage |
| | | visit_exitpage_chapter1 |
| | | visit_exitpage_chapter2 |
| | | visit_exitpage_chapter3 |
| | | visit_exitpage_full_name |
| | | visit_hour |
| | | visit_id |
| | | visit_minute |
| | | visit_page_views |
| | | visit_second |
| | | visit_time |
| | | visitor_privacy_consent |
| | | visitor_privacy_mode |
## extended-optout
Details
| Storage | Events | Properties |
| -------- | ------ | ---------- |
| _pprv | All | All |
| _pcid\* | | |
| _pctx\* | | |
> note:
>
> \*: If you specify [using Analytics only](/analytics/data-collection/how-to-send-events/consent/#configure-the-default-consent-mode) (`window.pdl.consent.products = ['PA'];`), this cookie won't be deposited
## opt-out
Details
| Storage | Events | Properties |
| -------- | ---------------- | ------------------------- |
| _pprv | click.action | ch_ua\* |
| _pcid\* | click.download | connection_type |
| _pctx\* | click.exit | device_timestamp_utc |
| | click.navigation | visitor_privacy_consent |
| | page.display | visitor_privacy_mode |
> note:
>
> \*: If you specify [using Analytics only](/analytics/data-collection/how-to-send-events/consent/#configure-the-default-consent-mode) (`window.pdl.consent.products = ['PA'];`), this cookie won't be deposited
## custom
By default, the `custom` mode will take the same rules as the `opt-in` mode.
---
## Collection methods
Once you have chosen to implement Piano Analytics via our SDKs, our collection API or a TMS, thanks to our [dedicated article](/analytics/data-collection/general/implementation-methods/), you can choose the collection method that suits you best.
## Piano collection endpoint
The Piano collection endpoint is the "standard" collection you usually start with.
It is simple and works without any configuration on your side.

To find your collection domain, you can go directly to our [Collection Domains](https://analytics.piano.io/datacollection/#/collection-domains) tool:

You can pick any of the collection domains, they are dedicated to your organization and only your sites can collect data on them.
Please note that the example here is based on a SDK implementation. The same applies to a Collection API implementation. Check the [dedicated article](/analytics/data-collection/general/implementation-methods/) to understand the difference.
## Custom Domain Data Collection
To guarantee data collection in the best conditions, we provide the ability to send events to our servers with a CNAME from one of your subdomains.
By using a custom domain, you keep your events, and collect more while keeping our SLAs.

Please note that the example here is based on a SDK implementation. The same applies to a Collection API implementation. Check the [dedicated article](/analytics/data-collection/general/implementation-methods/) to understand the difference.
If you want more information related to our Custom Domain Data Collection method, don't hesitate to consult the [dedicated article](https://analytics-docs.piano.io/en/analytics/v1/custom-domain-data-collection-cddc) in our Help Center.
If you want to reach the CDDC configuration interface, please follow this [link](https://analytics.piano.io/datacollection/#/collection-domains).
You can find the documentation for [renewing process here](/analytics/data-collection/collection-domains/custom/renew-certificate/).
## Proxify your collection
In order to maximize your data collection, you can set up a proxy between your visitors and our collection servers. This is usually done through your CDN, but it can be achieved with any proxy configured accordingly.

To set this up, please follow these requirements:
- Headers
- Highly recommended: forward full initial request, cleaned from headers you need to (sensitive cookies, …).
- If not possible, following headers are required:
- `Host`: Origin address and not the Client CDN address (The TLS certificate submitted by the Origin will match the Piano Analytics collection domain)
- `X-Forwarded-For`: IP address of the user must be propagated
- `User-Agent`, `Client Hints` (`Sec-Ch-Ua*`), `Accept-Language`, `Referer`
- Necessary cookies for analytical collection should be transmitted: `atid`, `atidx` and `idrxvr` *(please note that these values are subject to change)*
- No forwarding to Custom Domains (CDDC), use your `pa-cd.com` domain.
- Whatever path is set on the Client CDN side (e.g. `www.client.com/analy/tics`), it must be returned to a non-empty top-level path on the Piano Analytics API:
- `xxx.pa-cd.com/event` is correct
- `xxx.pa-cd.com/analy/tics` is **not** correct
- `xxx.pa-cd.com/` is **not** correct
- The entire querystring must be embedded in the request sent to the Origin, and the HTTP method must be the same as the initial request (`GET` or `POST`)
- No caching mechanism configured, all requests received by the CDN/Proxy Client should be forwarded to the Piano Analytics collection domain
Most CDNs already handle the constraints described below:
- The DNS lifetime (TTL) of the Origin must be followed (60 seconds). The IP addresses of the Origin are dynamic and therefore subject to change over time and geographic location.
- The Origin is exposed through multiple IP addresses for a single geographic location. Load balancing should be done across all Origin's IP addresses, not just one for a given period of time.
- For example: for a traffic of 1000 requests/s, if the DNS resolution of the Origin domain responds with 4 IPs, we must make sure to send 250 requests/s on each IP.
---
## How Piano Analytics Works
Piano Analytics uses a simple yet powerful **event-driven data model** that makes it easy to track user behavior across websites, mobile apps, and server-side applications.
## Core Concepts
At the heart of Piano Analytics are two fundamental building blocks:
### Events
[**Events**](https://analytics-docs.piano.io/en/analytics/v1/events) represent specific user interactions or system occurrences you want to measure:
- **Page views** (`page.display`) - When users visit pages
- **Clicks** (`click.navigation`) - When users interact with elements
- **Purchases** (`transaction.confirmation`) - When users complete transactions
- **Video plays** (`av.play`) - When users engage with media
- **Custom events** \- Any business-specific interactions you define
### Properties
[**Properties**](https://analytics-docs.piano.io/en/analytics/v1/properties) provide context and details about each event:
- **Page information** (`page`, `page_chapter1`) - Where the event happened
- **Content details** (`article_title`, `product_name`) - What was involved
- **User attributes** (`user_id`, `user_category`) - Who performed the action
- **Technical data** (`device_type`, `browser`) - How the event occurred
**Example:** A page view event might include properties like page name, category, publication date, and user status.
## Data Model Flexibility
### Standard Properties (450+ available)
Piano Analytics provides an extensive library of pre-defined events and properties covering common analytics scenarios:
- **Web analytics** \- Page views, navigation, search
- **E-commerce** \- Product views, cart actions, purchases
- **Media** \- Video/audio playback, engagement metrics
- **Mobile apps** \- Screen views, app lifecycle events
[→ View standard events documentation](/analytics/data-collection/how-to-send-events/standard-events/)
### Custom Properties
For unique business requirements, create custom events and properties to capture specific interactions:
```javascript
// Custom event example
pa.sendEvent("newsletter.signup", {
newsletter_type: "weekly",
signup_source: "homepage_banner",
user_segment: "premium",
});
```
### Property Processing Types
Piano Analytics handles two types of properties:
- **Processed Properties**: Sent directly in your tracking code and immediately available in reports
- **Calculated Properties**: Computed during data processing (e.g., session duration, bounce rate)
The [data model documentation](https://analytics-docs.piano.io/en/analytics/v1/properties) specifies which properties to include in your tracking implementation.
## Getting Started: Your First Events
The best way to understand Piano Analytics is through practical examples. Let's walk through implementing basic tracking for your website or application.
### Quick Start with Instant Tracking
≥ 6.16.0 **For websites:** The fastest way to start collecting data is with [Instant Tracking](/analytics/data-collection/how-to-send-events/instant-tracking/). Add one script to automatically track page views and basic interactions:
**Benefits:**
- ✅ Immediate data collection with zero configuration
- ✅ Automatic page view tracking
- ✅ Built-in privacy controls
- ✅ Minimal code required
```html
My Page
...
```
### Example 1: Tracking Page Views
The foundation of web analytics is measuring when users view pages. Here's how to send a `page.display` event with contextual properties:
### JavaScript
```html
My Page
...
```
Before 6.16.0
```html
My Page
...
```
### Android (3.3.0+)
```java
pa.setConfiguration(new Configuration.Builder()
.withCollectDomain(".pa-cd.com")
.withSite(123456789)
.build()
);
...
pa.sendEvent(new Event("page.display", new HashMap() {{ // Event name
put("page", "page name"); // Event properties
put("page_chapter1", "level 1");
put("page_chapter2", "level 2");
put("page_chapter3", "level 3");
}}));
```
### Android
```kotlin
import io.piano.android.analytics.Configuration
import io.piano.android.analytics.PianoAnalytics
...
val configuration = Configuration.Builder(
collectDomain = ".pa-cd.com",
site = 123456789
).build()
PianoAnalytics.init(applicationContext, configuration)
...
PianoAnalytics.getInstance().sendEvents(
Event.Builder("page.display")
.properties(
Property(PropertyName("page"), "page name"),
Property(PropertyName("page_chapter1"), "level 1"),
Property(PropertyName("page_chapter2"), "level 2"),
Property(PropertyName("page_chapter3"), "level 3"),
)
.build()
)
```
### Apple
```swift
pa.setConfiguration(ConfigurationBuilder()
.withCollectDomain(".pa-cd.com")
.withSite(123456789)
.build()
)
...
pa.sendEvent(Event("page.display", data: [ // Event name
"page": "page name", // Event properties
"page_chapter1": "level 1",
"page_chapter2": "level 2",
"page_chapter3": "level 3"
]))
```
### HTTP
```javascript
const site_id = `123456789`;
const visitor_id = ``;
const endpoint = `.pa-cd.com`;
fetch(`https://${endpoint}/?s=${site_id}&idclient=${visitor_id}`, {
method: "POST",
body: JSON.stringify({
events: [
{
name: "page.display",
data: {
page: "page name",
page_chapter1: "level 1",
page_chapter2: "level 2",
page_chapter3: "level 3",
},
},
],
}),
});
```
**What this tracking captures:**
| Component | Value | Purpose |
| -------------- | -------------------------------------- | --------------------------------- |
| **Event** | page.display | Identifies this as a page view |
| **Properties** | page: Page name | Primary page identifier |
| | page_chapter1-3: Navigation hierarchy | Page categorization for reporting |
**💡 Key insights from this data:**
- Most popular pages and content
- Navigation patterns and user flows
- Content performance by category
- Site structure effectiveness
For complete setup instructions, see the [JavaScript SDK guide](/analytics/data-collection/sdks/javascript/).
### Example 2: Tracking User Interactions
Beyond page views, you'll want to measure how users interact with your content. Here's how to track clicks with contextual information about where they occurred:
```html
My Page
```
```java
pa.sendEvent(new Event("click.navigation", new HashMap() {{ // Event name
put("click", "click name"); // Event properties
put("click_chapter1", "click level 1");
put("click_chapter2", "click level 2");
put("click_chapter3", "click level 3");
put("page", "page name");
}}));
```
```kotlin
PianoAnalytics.getInstance().sendEvents(
Event.Builder("click.navigation")
.properties(
Property(PropertyName("click"), "click name"),
Property(PropertyName("click_chapter1"), "click level 1"),
Property(PropertyName("click_chapter2"), "click level 2"),
Property(PropertyName("click_chapter3"), "click level 3"),
Property(PropertyName("page"), "page name"),
)
.build()
)
```
```swift
pa.sendEvent(Event("click.navigation", data: [ // Event name
"click": "click name", // Event properties
"click_chapter1": "click level 1",
"click_chapter2": "click level 2",
"click_chapter3": "click level 3",
"page": "page name"
]))
```
```javascript
const site_id = `123456789`;
const visitor_id = ``;
const endpoint = `.pa-cd.com`;
fetch(`https://${endpoint}/?s=${site_id}&idclient=${visitor_id}`, {
method: "POST",
body: JSON.stringify({
events: [
{
name: "click.navigation",
data: {
click: "click name", // Event properties
click_chapter1: "click level 1",
click_chapter2: "click level 2",
click_chapter3: "click level 3",
page: "page name",
},
},
],
}),
});
```
**What this tracking captures:**
| Component | Value | Purpose |
| -------------- | --------------------------------------- | ------------------------------------- |
| **Event** | click.navigation | Identifies this as a navigation click |
| **Properties** | click: Click name | What element was clicked |
| | click_chapter1-3: Click categorization | Classification of the click type |
| | page: Page context | Where the click occurred |
**💡 Key insights from this data:**
- Most engaged content and features
- User interface effectiveness
- Navigation patterns and preferences
- Conversion funnel optimization opportunities
---
## Implementation methods
Piano Analytics offers multiple integration methods to accommodate various technical environments and project requirements. This section outlines the available options, providing guidance to help you select the most suitable approach for your implementation.
## SDKs
Software Development Kits (SDKs) provide streamlined interfaces for integrating Piano Analytics into your applications. By incorporating a lightweight library into your platform, you can leverage predefined methods to dispatch analytics events efficiently.
Available SDKs include:
| SDK | Platforms |
| ----------------------------------------------------------------------------------- | ---------------------------------- |
| [JavaScript](/analytics/data-collection/sdks/javascript/) | Websites or Apps through browsers. |
| [iOS (Swift)](/analytics/data-collection/sdks/ios-swift/) | iOS native apps. |
| [Android (Kotlin)](/analytics/data-collection/sdks/android-kotlin/) | Android native apps. (Kotlin SDK) |
| [Flutter](/analytics/data-collection/sdks/flutter/) | Flutter mobile apps. |
| [JavaScript (browserless)](/analytics/data-collection/sdks/javascript-browserless/) | Any platform supporting JS. |
### Advantages
- Simplifies the tagging process.
- Facilitates the management and transmission of platform-specific data.
- Officially developed and maintained by Piano.
### Considerations
- Compatibility is limited to supported platforms.
If you want to send your first events using our SDKs, please use the [dedicated article](/analytics/data-collection/how-to-send-events/send-events-via-sdks/).
## Collection API
The Collection API enables direct transmission of analytics events via HTTPS POST requests, offering a high degree of flexibility for custom implementations. This method is particularly advantageous when SDK integration is not feasible due to technological constraints.
> tip:
>
> Server-side implementations can require implementations without SDKs, directly through the Collection API. This allows you to get rid of browsers and their limitations (client-side collection).
### Advantages
- Highly customizable to fit specific requirements.
- Operable across diverse platforms and environments.
### Considerations
- Requires manual construction of event payloads.
- Does not automatically capture native platform information.
If you want to send your first events using our Collection API, please use the [dedicated article](/analytics/data-collection/how-to-send-events/collection-api/).
## Tag Management Systems
Tag Management Systems offer a user-friendly interface for implementing and managing analytics tags across digital properties. They support both client-side and server-side tagging approaches.
| | GOOGLE TAG MANAGER | TEALIUM | COMMANDERS ACT |
| ----------- | ------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| Client-side | ✅[Documentation](https://github.com/at-internet/gtm-pa-tagging) | ✅[Documentation](https://docs.tealium.com/client-side-tags/at-internet-piano-analytics-tag/) | ✅ |
| Server-side | ✅[Documentation](https://github.com/optimize-matter/piano-analytics-s2s) | ✅[Documentation](https://docs.tealium.com/server-side-connectors/at-internet-piano-analytics-connector/) | ✅[Documentation](https://community.commandersact.com/platform-x/features/destinations/destinations-catalog/at-internet) |
### Advantages
- Centralized management of all tags.
- Utilization of a robust common data layer.
- Access to advanced features provided by TMS vendors.
### Considerations
- Potentially reduced control over individual tagging configurations.
## Selecting the Appropriate Method
### SDKs
Ideal for straightforward client-side integrations on supported platforms. Dedicated documentation for [JavaScript](/analytics/data-collection/sdks/javascript/), [iOS](/analytics/data-collection/sdks/ios-swift/), and [Android](/analytics/data-collection/sdks/android-kotlin/) SDKs.
### Collection API
Suitable for scenarios requiring extensive customization or when operating in environments where SDKs are unsupported. Can be done with the [js browserless](/analytics/data-collection/sdks/javascript-browserless/) SDK or the [collection API](/analytics/data-collection/how-to-send-events/collection-api/) directly.
### Tag Management Systems
Recommended if your organization already utilizes a TMS or seeks to leverage the additional features they offer.
Each implementation method is comprehensively documented to assist you throughout the integration process.
---
## Migrate from SmartTag
This guide outlines the process of transitioning from legacy SmartTag SDKs to the modern Piano Analytics SDKs, detailing differences in tagging methodologies, SDK lifecycles, and migration strategies.
## SDK and Tagging landscape
Since 2015, [SmartTag SDKs](https://developers.atinternet-solutions.com/piano-analytics-tagging-en/getting-started-piano-analytics-en/what-is-piano-analytics-tagging-en/) SDKs have been implemented using two primary tagging approaches:
- [AS2 Tagging](https://developers.atinternet-solutions.com/as2-tagging-en/javascript-en/getting-started-javascript-en/tracker-initialisation-javascript-en/) (2015) - Designed for the Analytics Suite 2, utilizing methods like `tag.page.set()` and tag.page.dispatch().
- [PA Tagging](https://developers.atinternet-solutions.com/piano-analytics-tagging-en/getting-started-piano-analytics-en/what-is-piano-analytics-tagging-en/) (Winter 2020) - Introduced to align with the Piano Analytics event-based model, employing `tag.event.send()` for event tracking.
As of April 2022, Piano Analytics SDKs are the standard for data collection, offering a streamlined, event-centric architecture. Support for SmartTag SDKs ceased in April 2023, with no further maintenance or feature updates.
## Before I start
> attention:
>
> "xtor" marketing campaigns syntax will not be recognized anymore. Please use ["at_"](/analytics/data-collection/how-to-send-events/marketing-campaigns/) instead.
## Marketing Campaigns Migration
### SmartTag
Smarttag previously relied on campaigns that had to be declared before it could be used. This configuration step, in addition to using predefined campaign types, allowed values sent in the URL to be transformed.
So for example, the `xtor=AL` was automatically transformed into the Campaign Type `"Affiliation and partners"`.
The ID of the campaign was then matched to its declared label in the configuration panel.
> tip:
>
> Learn more on the dedicated [migration page for marketing campaigns](/analytics/data-collection/how-to-send-events/marketing-campaigns/)
### Piano Analytics SDK
With the Piano Analytics SDK, the tag first approach is used instead, no matching is done and the data you send is the data you will later find in the different exploratory tools, without any need for prior configuration.
> note:
>
> When sending `#xtor=SEC-2-GOO`, the `GOO` part was automatically translated to `Google Adwords`. When using the Piano Analytics SDK, `src_sl_platform=GOO` will no longer translate the value. If you need consistency when migrating, please use `Google Adwords` as the value instead.
This tag first approach makes tracking marketing sources much more flexible, but it remains important to understand its core functioning for a proper migration from the Smarttag SDK.
Piano Analytics uses the Data Model to populate data into their respective properties, it also uses the `at_*` marketing campaign format.
> info:
>
> This `at_*` used for your different properties is going to be transformed into `src_*` by the tag directly.
1. When sending `at_type=gold`, you will populate the property Campaign/Organic, if you want to populate the Emailing/Affiliation/Campaign type, then please use the associated property in the data model.
2. When sending `at_medium=affiliate` & `at_aff_type=gold`. Will result in having `src_medium=affiliate` & `src_aff_type=gold` in the tag. Then using the data model you can see which property you'll have to use to find your data.
## Difference between tagging philosophies / SDKs
The functionalities of our SDKs have followed the evolution of our audience measurement solution.
Perfectly adapted to our legacy system, the SmartTag SDKs had to be adapted to the new Piano Analytics solution to allow you to send events and use your Data Model.
This is what was enabled with the PA Tagging philosophy during winter 2020, while still using the old SmartTag SDKs.
We then decided to start from scratch and redesign brand new SDKs that are based on our new Piano Analytics solution and event-based data model:
| SmartTag (AS2 Tagging) | SmartTag (PA Tagging) | Piano Analytics SDKs |
| ---------------------- | --------------------- | -------------------- |
|
```javascript
tag.page.set({
name: "My_page",
level2: "sub_level",
});
tag.setprops({
"d:article_date": 1646925124,
"b:article_premium": false,
});
tag.page.dispatch();
```
|
```javascript
tag.event.send('page.display', {
'page': 'My page'
'site_level2': 'sub level' ,
'article_date': 1646925124,
'article_premium': false
});
```
|
```javascript
pa.sendEvent('page.display', {
'page': 'My page'
'site_level2': 'sub level' ,
'article_date': 1646925124,
'article_premium': false
});
```
|
As you can see here, if you already tagged your perimeters with the SmartTag (PA Tagging) approach, migrating to Piano Analytics SDKs will not be heavy.
It is the same event-based approach, with easier tagging methods and configurations.
Piano Analytics SDKs come with:
- A redesigned and easier tagging
- A JS Browserless SDK to collect data in new environments
- A new "Privacy by design" approach, the most advanced on the market
- Dozens of improvements and new features
## Can I use both SDKs?
You can.
But both SDKs don't communicate, so Privacy configuration and users' ID are not shared.
More information in the [dedicated article](/analytics/data-collection/general/cookie-storage/#legacy-cookie-management).
## Complete tagging example
### SmartTag - AS2 Tagging (2015)
[documentation](https://developers.atinternet-solutions.com/as2-tagging-en/javascript-en/getting-started-javascript-en/tracker-initialisation-javascript-en/)
```html
My Page
...
```
### SmartTag - PA Tagging (Winter 2020)
[documentation](https://developers.atinternet-solutions.com/piano-analytics-tagging-en/getting-started-piano-analytics-en/what-is-piano-analytics-tagging-en/)
```html
My Page
...
```
### Piano Analytics SDKs (April 2022)
```html
My Page
...
```
---
## Cookies & storage
## Client Side Cookies (JS SDK)
| Name | Lifetime | Description | Is flag secure | Is flag SameSite | If deleted |
| -------- | --------------------------------------- | ------------------------ | -------------- | ---------------- | ------------------------------------------------------------------------------------------ |
| _pcid | 13 months by default, can be configured | Visitor ID | ✅ | SameSite=lax | New cookie set, new visitor ID assigned |
| _pctx | 13 months by default, can be configured | Piano context storage | ✅ | SameSite=lax | No persistence of contextual information between Piano SDKs |
| _pprv | 13 months by default, can be configured | Consent Mode persistence | ✅ | SameSite=lax | No persistence of Consent Mode, window.pdl.consent.defaultPreset.PA configuration assigned |
| pa_user | 13 months by default, can be configured | Stored user information | ✅ | SameSite=lax | No persistence of user information information in events |
Before 6.8.0
| Name | Lifetime | Description | Is flag secure | Is flag SameSite | If deleted |
| ----------- | --------------------------------------- | ------------------------ | -------------- | ---------------- | ------------------------------------------------------------------------- |
| pa_vid | 13 months by default, can be configured | Visitor ID | ✅ | SameSite=lax | New cookie set, new visitor ID assigned |
| pa_user | 13 months by default, can be configured | Stored user information | ✅ | SameSite=lax | No persistence of user information information in events |
| pa_privacy | 13 months by default, can be configured | Privacy Mode persistence | ✅ | SameSite=lax | No persistence of Privacy Mode, privacyDefaultMode configuration assigned |
### `_pcid` format
The `_pcid` cookie may trigger OWASP security rules due to its structure: it contains a JSON object with special characters (quotes, colons, pipes) that are URL-encoded, which can be flagged by security scanners.
The cookie value is URL-encoded and follows this pattern:
`%7B%22browserId%22%3A%22mg0j6i6ct4vxgjb9%22%2C%22_t%22%3A%22mwj35h8y%7Cmgum2u4y%22%7D`
When URL-decoded and formatted, the cookie contains a JSON object:
```json
{
"browserId": "mg0j6i6ct4vxgjb9", // Unique visitor identifier (random alphanumeric value)
"_t": "mwj35h8y|mgum2u4y" // Encoded timestamp for cookie duration manipulation
}
```
This cookie uses a JSON structure to allow end-users to easily retrieve their identifier for GDPR compliance purposes. Storing this data in a cookie allows it to naturally expire after the configured lifetime (13 months by default).
## Server Side Cookies
| Name | Lifetime | Description | Secure flag | SameSite flag | HTTPOnly flag | If deleted |
| ------ | --------- | ----------------------------- | ----------- | ------------- | ------------- | --------------------------------------- |
| idrxvr | 13 months | Legacy Server Side Visitor ID | ❌ | ❌ | ✅ | New cookie set, new visitor ID assigned |
| atidx | 13 months | Server Side Visitor ID | ✅ | ❌ | ✅ | New cookie set, new visitor ID assigned |
| atid | 13 months | Main Server Side Visitor ID | ✅ | SameSite=none | ✅ | New cookie set, new visitor ID assigned |
## Piano Analytics Mobile SDKs
### Android
| Storage key | Lifetime | Description |
| ------------- | --------------------------------------- | ------------------------ |
| pa_vid | 13 months by default, can be configured | Visitor ID |
| pa_uid | 13 months by default, can be configured | Stored user information |
| pa_privacy | 13 months by default, can be configured | Privacy Mode persistence |
| pa_crash | Until app relaunch | Crash information |
| pa_lifecycle | No expiration | Application lifecycle |
### Apple
| Storage key | Lifetime | Description |
| ------------- | --------------------------------------- | ------------------------ |
| pa_vid | 13 months by default, can be configured | Visitor ID |
| pa_uid | 13 months by default, can be configured | Stored user information |
| pa_privacy | 13 months by default, can be configured | Privacy Mode persistence |
| pa_crash | Until app relaunch | Crash information |
| pa_lifecycle | No expiration | Application lifecycle |
## Piano Cookies
This page covers the Piano Analytics cookies, you can also find the cookies used for the other Piano products [here](https://docs.piano.io/track/piano-cookie-descriptions/#menu40630)
## Legacy cookie management
If you're migrating from SmartTag SDKs to Piano Analytics SDKs, we still use the `atuserid` cookie (visitor identification) so as not to cause a break in the detection of the visitor. As soon as this `atuserid` cookie is deleted, we replace it with `_pcid` cookie. Same applies to `pa_vid` (legacy value of PA SDK visitor cookie ID).
The `atauthority` cookie (Privacy) is not used anymore. Please implement [Consent methods](/analytics/data-collection/how-to-send-events/consent/) to deposit the new `_pprv` cookie instead (or [Privacy methods](/analytics/data-collection/how-to-send-events/privacy/) if your use mobile SDKs).
Same applies for legacy `atidvisitor` cookie ("identified visitor" detection, now "user"). Please implement [Users methods](/analytics/data-collection/how-to-send-events/users/) to deposit the new `pa_user` cookie instead.
---
## Activation Insights
Activation Insights offers analysis dedicated to your Activation performance. This article will present you how it works and how to get the best out of your implementation.
## How it works
Activation Insights merge data from various Piano products into Piano Analytics data model. To provide a comprehensive understanding of how Activation Insights work, let's break down the process step-by-step:
1. Piano SDKs implemented on the application (web, mobile, ...) send events to Piano backends. These events include user interactions and other relevant data points that help track the activation journey. All those events share 2 key IDs allowing us to correlate them across different systems:
1. Browser ID: also called Visitor ID, represents a unique ID linked to a specific browser. (`idclient` querystring property)
2. Pageview ID: this unique ID is generated for each pageview or screen view within an application and links all events that occur on the same page or screen. (`pageview_id` event property)
2. Activation backends process these events, enrich them and send them to Piano Analytics.
3. These events are then processed by Piano Analytics, which uses advanced algorithms to analyze patterns, user journeys, and interactions.
## Implementation
### JavaScript
JavaScript SDKs automatically share Pageview ID (`pageview_id`) and Browser ID (`idclient`) since version 6.7.0.
### Android (3.3.0+)
- Browser ID: you need to set the same browser ID for both Composer SDK and Analytics SDK:
- Set:
- `Composer.getInstance().browserIdProvider { "" }`
- `PianoAnalytics.getInstance().customVisitorId = ""` ([documentation](/analytics/data-collection/how-to-send-events/visitor-identification/#visitor-identification-management))
- Get:
- `val visitorId = PianoAnalytics.getInstance().visitorId` ([documentation](/analytics/data-collection/how-to-send-events/visitor-identification/#visitor-identification-management))
- Pageview ID: you need to retrieve the pageview ID generated by Composer SDK to push it in every events:
```kotlin
PianoAnalytics.getInstance().sendEvents(
Event.Builder(...)
.properties(
...
Property(PropertyName("pageview_id"), Composer.getInstance().pageViewId.orEmpty()),
)
.build()
)
```
### Apple
- Browser ID: you need to set the same browser ID and pageview ID for both Composer SDK and Analytics SDK:
- Composer:
```swift
PianoComposer(...)
...
.browserId("")
.pageViewId("")
.execute()
```
```text
- Analytics:
- Browser ID:
- Set: `pa.setVisitorId("")` ([documentation](/analytics/data-collection/how-to-send-events/visitor-identification.md#visitor-identification-management))
- Get: `pa.getVisitorId { visitorId in print(visitorId) }` ([documentation](/analytics/data-collection/how-to-send-events/visitor-identification.md#visitor-identification-management))
- Pageview ID:
```swift
PianoAnalytics.shared.sendEvent(
Event(
"...",
properties: [
Property("pageview_id", "")
]
)
)
```
---
## AV Insights (audio video)
AV Insights allows the collection of events related to media consumption. You will be able to follow the different interactions on your players and measure the performance of your content. The AV Insight tracker is designed to give you options on the level of information you want to measure.
## Media management
### Media instantiation
In order to be able to manipulate a media and measure its events, it is necessary to declare an object:
### JavaScript
```js
var myMedia = new pa.avInsights.Media([
heartbeatDuration,
bufferingHeartbeatDuration,
sessionId,
]);
```
| Parameter | Type | Description | Example |
| ------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------- |
| heartbeatDuration (optional) | int, object | Delay between two heartbeat during playback (minimum delay is 5sec).If the value is a int, this will be the delay for the whole playback.If the value is an object such as { 0:5, 1:10, 5:60 }, meaning the first minute will be 5sec delay, starting from minute 1, 10sec, and after the 5th minute, the delay will be 60sec.A value of 0 means no heartbeat. If set in an object format, heartbeats will stop for the rest of the video. | 5 or { 0:5, 1:10, 5:60, 120:0 } |
| bufferingHeartbeatDuration (optional) | int, object | Delay between two heartbeat during buffering (minimum delay is 1sec).If the value is a int, this will be the delay for the whole buffering.If the value is an object such as { 0:5, 1:10, 5:60 }, meaning the first minute will be 5sec delay, starting from minute 1, 10sec, and after the 5th minute, the delay will be 60sec.A value of 0 means no heartbeat. If set in an object format, heartbeats will stop for the rest of the buffering. | 5 or { 0:5, 1:10, 5:60, 10:0 } |
| sessionId (optional) | string | Session ID of the playback. This ID is automatically managed by the SDK, but you can override it if you know what you are doing. More details in the next section. | "97fb0ee6-7b86-4ffa-a69f-e32a04d40bbf" |
```js
var myMedia = new pa.avInsights.Media(5, 5);
// or
var myMedia = new pa.avInsights.Media({ 0: 5, 1: 10, 5: 60, 120: 0 }, 5);
```
> note:
>
> Two parameters are available, in order to activate the heartbeats. The first one enables playback tracking heartbeats and the second one enables buffering tracking heartbeats.
### Android (3.3.0+)
Declare your heartbeat delays and content ID thanks to `MediaHelper` class:
```kotlin
val heartbeat = SparseLongArray()
// first minute will be 5sec delay
heartbeat.put(0, 5)
// starting from minute 1, 10sec
heartbeat.put(1, 10)
// and after the 5th minute, the delay will be 60sec
heartbeat.put(5, 60)
val bufferHeartbeat = SparseLongArray()
bufferHeartbeat.put(0, 5)
val myMedia = PianoAnalytics.getInstance()
.mediaHelper("fg456") // Content ID
.setHeartbeat(heartbeat)
.setBufferHeartbeat(bufferHeartbeat)
```
### Android
```swift
var myMedia = AVMedia(pa: PianoAnalytics, sessionId: String? = nil)
```
| Parameter | Type | Description | Example |
| -------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------- |
| pa | PianoAnalytics | Tracker instance | pa |
| sessionId (optional) | String? | Session ID of the playback. This ID is automatically managed by the SDK, but you can override it if you know what you are doing. More details in the next section. | \- |
```swift
var myMedia = AVMedia(pa: pa)
```
To set up automatic heartbeat management, call the dedicated methods:
`myMedia.setHeartbeat(heartbeat: [Int: Int]?)`
| Parameter | Type | Description | Example |
| --------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- |
| heartbeat | \[Int: Int\]? | Delay between two heartbeat during playback (minimum delay is 5sec). You can set a map such as \[0:5, 1:10, 5:60\], meaning the first minute will be 5sec delay, starting from minute 1, 10sec, and after the 5th minute, the delay will be 60sec | \[0:5, 1:10, 5:60\] |
```swift
myMedia.setHeartbeat(heartbeat: [
0: 5,
1: 10,
5: 60
])
```
`myMedia.setBufferHeartbeat(bufferHeartbeat: [Int: Int]?)`
| Parameter | Type | Description | Example |
| --------------- | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- |
| bufferHeartbeat | \[Int: Int\]? | Delay between two heartbeat during buffering (minimum delay is 1sec). You can set a map such as \[0:5, 1:10, 5:60\], meaning the first minute will be 5sec delay, starting from minute 1, 10sec, and after the 5th minute, the delay will be 60sec | \[0:5, 1:10, 5:60\] |
```swift
myMedia.setBufferHeartbeat(bufferHeartbeat: [
0: 5,
1: 10,
5: 60
])
```
### Apple
Begin by importing `io.piano.analytics.avinsights.Media` into your file:
```java
import io.piano.analytics.avinsights.Media;
```
In order to be able to manipulate a media and measure its events, it is necessary to declare an object of type `Media` :
```java
Media myMedia = new Media(pa);
// or
Media myMedia = new Media(pa, sessionId);
```
| Parameter | Type | Description | Example |
| -------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------- |
| pa | PianoAnalytics | Tracker instance | pa |
| sessionId (optional) | String | Session ID of the playback. This ID is automatically managed by the SDK, but you can override it if you know what you are doing. More details in the next section. | \- |
To set up automatic heartbeat management, call the dedicated methods:
`myMedia.setHeartbeat(heartbeat)`
| Parameter | Type | Description | Example |
| --------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- |
| heartbeat | SparseIntArray | Delay between two heartbeat during playback (minimum delay is 5sec). You can set a map such as \[0:5, 1:10, 5:60\], meaning the first minute will be 5sec delay, starting from minute 1, 10sec, and after the 5th minute, the delay will be 60sec | \[0:5, 1:10, 5:60\] |
```java
myMedia.setHeartbeat(new SparseIntArray()
.append(0, 5)
.append(1, 10)
.append(5, 60)
);
```
`myMedia.setBufferHeartbeat(bufferHeartbeat)`
| Parameter | Type | Description | Example |
| --------------- | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- |
| bufferHeartbeat | SparseIntArray | Delay between two heartbeat during buffering (minimum delay is 1sec). You can set a map such as \[0:5, 1:10, 5:60\], meaning the first minute will be 5sec delay, starting from minute 1, 10sec, and after the 5th minute, the delay will be 60sec | \[0:5, 1:10, 5:60\] |
```java
myMedia.setBufferHeartbeat(new SparseIntArray()
.append(0, 5)
.append(1, 10)
.append(5, 60)
);
```
#### Session ID management
> warning:
>
> Please note that this setup should be used only in special cases, when you need to transfer sessions between different devices, for example.
An optional third parameter `sessionId` is available to override the common standard property `av_session_id` present in each event generated by AV Insights tags.
The parameter is automatically managed by the SDK for all standard cases.
```js
var myMedia = new pa.avInsights.Media(5, 5, "custom_session_id");
```
A function `getSessionID` can be used to retrieve the value of the parameter:
`getSessionID() ⇒ string | number`
*Retrieve the session ID.*
Example
```js
var sessionID = myMedia.getSessionID(); // 'custom_session_id' or 'xxxxxxxx-xxxx-4xxx-xxxx-xxxxxxxx'
```
An optional second parameter `mediaSessionId` is available to override the common standard property `av_session_id` present in each event generated by AV Insights tags.
The parameter is automatically managed by the SDK for all standard cases.
```kotlin
val myMedia = PianoAnalytics.getInstance().mediaHelper("contentId", "custom-session-id")
```
An optional second parameter `sessionId` is available to override the common standard property `av_session_id` present in each event generated by AV Insights tags.
The parameter is automatically managed by the SDK for all standard cases.
```java
Media myMedia = new Media(pa, "custom-session-id");
```
An optional second parameter `sessionId` is available to override the common standard property `av_session_id` present in each event generated by AV Insights tags.
The parameter is automatically managed by the SDK for all standard cases.
```swift
var myMedia = new AVMedia(pa: pa, sessionId: "custom-session-id")
```
### Media properties
Some rules must be observed regarding the format of the properties used for the configuration of a media :
- The `av_content_id` is a mandatory property that must be used for all media instances ([see complete tagging example section](#complete-tagging-example)).
- The duration of the media or the positions of the playback head must be expressed in *milliseconds*.
The SDK provides useful functions for the management of Media properties:
`set(propKey, propValue)`
*Declare a media property.*
| Parameter | Type | Description |
| --------- | -------------- | -------------------- |
| propKey | string | Media property key |
| propValue | string, number | Media property value |
Example
```js
myMedia.set("av_content_id", "fg456"); // mandatory
myMedia.set("av_content", "my_video");
```
`get(propKey) ⇒ string | number`
*Retrieve a media property.*
| Parameter | Type | Description |
| --------- | ------ | ------------------ |
| propKey | string | Media property key |
Example
```js
var content_id = myMedia.get("av_content_id"); // fg456
```
`del(propKey)`
*Delete a media property.*
| Parameter | Type | Description |
| --------- | ------ | ------------------ |
| propKey | string | Media property key |
Example
```js
myMedia.del("av_content_id");
```
`setProps(properties)`
*Declare multiple media properties.*
| Parameter | Type | Description |
| ---------- | ------ | ---------------- |
| properties | Object | Media properties |
Example
```js
myMedia.setProps({ av_content_id: "fg456", av_content: "My Content" });
```
`getProps() ⇒ Object`
*Retrieve all media properties.*
Example
```js
var props = myMedia.getProps(); // {'av_content_id': 'fg456', 'av_content': 'My Content'}
```
`delProps()`
*Delete all media properties.*
Example
```js
myMedia.delProps();
```
```kotlin
myMedia.setExtraProps(
Property(PropertyName("av_content"), "my_video")
Property(PropertyName("av_content_duration"), 2760000)
)
```
You need to manage your [media properties](#media-properties-list) to send them on every events, through the `extraProps` parameter of dedicated methods.
You need to manage your [media properties](#media-properties-list) to send them on every events, through the `extraProps` parameter of dedicated methods.
For automatic events (e.g. heartbeats), use the `setExtraProperties` method to set media properties:
```swift
myMedia.setExtraProperties([
"av_content": "my_video",
"av_content_duration": 2760000
])
```
## Events tracking
The SDK offers useful functions for measuring events related to your users’ interactions with your content:
### Media events
#### play
Event name : `av.play`
*Generate a play event (playback attempt).*
`play(cursorPosition[, callback, extraProps])`
| Parameter | Type | Description |
| --------------------- | -------- | ------------------------------------------- |
| cursorPosition | number | Current cursor position (ms) |
| callback (optional) | function | Callback function to execute after hit sent |
| extraProps (optional) | Object | Custom properties |
Example
```js
myMedia.play(
0,
function () {
console.log("Event av.play generated");
},
{ customProp: "customValue" }
);
```
| Parameter | Type | Description |
| ---------------------------- | -------- | ---------------------------- |
| cursorPosition | Int | Current cursor position (ms) |
| properties vararg (optional) | Property | Custom properties |
```kotlin
myMedia.play(
0,
Property(...),
Property(...)
)
```
`func Media.play(cursorPosition, extraProps)`
| Parameter | Type | Description |
| --------------------- | -------------------- | ---------------------------- |
| cursorPosition | Int | Current cursor position (ms) |
| extraProps (optional) | Map? | Custom properties |
Example
```java
myMedia.play(
0,
new HashMap() {{
put("av_content", "Content title");
...
}}
);
```
`myMedia.play(cursorPosition: Int, extraProps: [String: Any]?)`
| Parameter | Type | Description |
| --------------------- | ---------------- | ---------------------------- |
| cursorPosition | Int | Current cursor position (ms) |
| extraProps (optional) | \[String: Any\]? | Custom properties |
Example
```swift
myMedia.play(
cursorPosition: 0,
extraProps: [
"av_content": "Content title",
...
]
)
```
#### bufferStart
Event name : `av.buffer.start` or `av.rebuffer.start`
*Generate an event of buffering at the launch of a media or during the playing. The `buffering.heartbeat` is sent before the `av.start` while the `rebuffering.heartbeat` is sent after an `av.start` is recorded on the `av_session_id`.*
`bufferStart(cursorPosition[, callback, extraProps])`
A buffering flag will automatically generate `buffering.heartbeat` or `rebuffering.heartbeat` events depending on the context.
| Parameter | Type | Description |
| --------------------- | -------- | ------------------------------------------- |
| cursorPosition | number | Current cursor position (ms) |
| callback (optional) | function | Callback function to execute after hit sent |
| extraProps (optional) | Object | Custom properties |
Example
```js
myMedia.bufferStart(
0,
function () {
console.log(
"Event av.buffer.start or av.rebuffer.start generated depending on the playback launch"
);
},
{ customProp: "customValue" }
);
```
| Parameter | Type | Description |
| ---------------------------- | -------- | ---------------------------- |
| cursorPosition | Int | Current cursor position (ms) |
| properties vararg (optional) | Property | Custom properties |
```kotlin
myMedia.bufferStart(
0,
Property(...),
Property(...)
)
```
`func Media.bufferStart(cursorPosition, extraProps)`
A buffering flag will automatically generate `buffering.heartbeat` or `rebuffering.heartbeat` events depending on the context.
| Parameter | Type | Description |
| --------------------- | -------------------- | ---------------------------- |
| cursorPosition | Int | Current cursor position (ms) |
| extraProps (optional) | Map? | Custom properties |
Example
```java
myMedia.bufferStart(
0,
new HashMap() {{
put("av_content", "Content title");
...
}}
);
```
`myMedia.bufferStart(cursorPosition: Int, extraProps: [String: Any]?)`
A buffering flag will automatically generate `buffering.heartbeat` or `rebuffering.heartbeat` events depending on the context.
| Parameter | Type | Description |
| --------------------- | ---------------- | ---------------------------- |
| cursorPosition | Int | Current cursor position (ms) |
| extraProps (optional) | \[String: Any\]? | Custom properties |
Example
```swift
myMedia.bufferStart(
cursorPosition: 0,
extraProps: [
"av_content": "Content title",
...
]
)
```
#### playbackStart
Event name : `av.start`
*Generate a playback start event (first media frame). This allows the automatic `av.heartbeat` events (designed to accurately track the playback time) to be sent. These `av.heartbeat` events follow the media instance configuration.*
`playbackStart(cursorPosition[, callback, extraProps])`
| Parameter | Type | Description |
| --------------------- | -------- | ------------------------------------------- |
| cursorPosition | number | Current cursor position (ms) |
| callback (optional) | function | Callback function to execute after hit sent |
| extraProps (optional) | Object | Custom properties |
Example
```js
myMedia.playbackStart(
0,
function () {
console.log("Event av.start generated");
},
{ customProp: "customValue" }
);
```
| Parameter | Type | Description |
| ---------------------------- | -------- | ---------------------------- |
| cursorPosition | Int | Current cursor position (ms) |
| properties vararg (optional) | Property | Custom properties |
```kotlin
myMedia.playbackStart(
0,
Property(...),
Property(...)
)
```
`func Media.playbackStart(cursorPosition, extraProps)`
| Parameter | Type | Description |
| --------------------- | -------------------- | ---------------------------- |
| cursorPosition | Int | Current cursor position (ms) |
| extraProps (optional) | Map? | Custom properties |
Example
```java
myMedia.playbackStart(
0,
new HashMap() {{
put("av_content", "Content title");
...
}}
);
```
`myMedia.playbackStart(cursorPosition: Int, extraProps: [String: Any]?)`
| Parameter | Type | Description |
| --------------------- | ---------------- | ---------------------------- |
| cursorPosition | Int | Current cursor position (ms) |
| extraProps (optional) | \[String: Any\]? | Custom properties |
Example
```swift
myMedia.playbackStart(
cursorPosition: 0,
extraProps: [
"av_content": "Content title",
...
]
)
```
#### playbackPaused
Event name : `av.pause`
*Generate a pause event.*
`playbackPaused(cursorPosition[, callback, extraProps])`
| Parameter | Type | Description |
| --------------------- | -------- | ------------------------------------------- |
| cursorPosition | number | Current cursor position (ms) |
| callback (optional) | function | Callback function to execute after hit sent |
| extraProps (optional) | Object | Custom properties |
Example
```js
myMedia.playbackPaused(
1000,
function () {
console.log("Event av.pause generated");
},
{ customProp: "customValue" }
);
```
| Parameter | Type | Description |
| ---------------------------- | -------- | ---------------------------- |
| cursorPosition | Int | Current cursor position (ms) |
| properties vararg (optional) | Property | Custom properties |
```kotlin
myMedia.playbackPaused(
1000,
Property(...),
Property(...)
)
```
`func Media.playbackPaused(cursorPosition, extraProps)`
| Parameter | Type | Description |
| --------------------- | -------------------- | ---------------------------- |
| cursorPosition | Int | Current cursor position (ms) |
| extraProps (optional) | Map? | Custom properties |
Example
```java
myMedia.playbackPaused(
1000,
new HashMap() {{
put("av_content", "Content title");
...
}}
);
```
`myMedia.playbackPaused(cursorPosition: Int, extraProps: [String: Any]?)`
| Parameter | Type | Description |
| --------------------- | ---------------- | ---------------------------- |
| cursorPosition | Int | Current cursor position (ms) |
| extraProps (optional) | \[String: Any\]? | Custom properties |
Example
```swift
myMedia.playbackPaused(
cursorPosition: 1000,
extraProps: [
"av_content": "Content title",
...
]
)
```
#### playbackResumed
Event name : `av.resume`
*Generate a resume event, following a pause event.*
`playbackResumed(cursorPosition[, callback, extraProps])`
| Parameter | Type | Description |
| --------------------- | -------- | ------------------------------------------- |
| cursorPosition | number | Current cursor position (ms) |
| callback (optional) | function | Callback function to execute after hit sent |
| extraProps (optional) | Object | Custom properties |
Example
```js
myMedia.playbackResumed(
1000,
function () {
console.log("Event av.resume generated");
},
{ customProp: "customValue" }
);
```
| Parameter | Type | Description |
| ---------------------------- | -------- | ---------------------------- |
| cursorPosition | Int | Current cursor position (ms) |
| properties vararg (optional) | Property | Custom properties |
```kotlin
myMedia.playbackResumed(
1000,
Property(...),
Property(...)
)
```
`func Media.playbackResumed(cursorPosition, extraProps)`
| Parameter | Type | Description |
| --------------------- | -------------------- | ---------------------------- |
| cursorPosition | Int | Current cursor position (ms) |
| extraProps (optional) | Map? | Custom properties |
Example
```java
myMedia.playbackResumed(
1000,
new HashMap() {{
put("av_content", "Content title");
...
}}
);
```
`myMedia.playbackResumed(cursorPosition: Int, extraProps: [String: Any]?)`
| Parameter | Type | Description |
| --------------------- | ---------------- | ---------------------------- |
| cursorPosition | Int | Current cursor position (ms) |
| extraProps (optional) | \[String: Any\]? | Custom properties |
Example
```swift
myMedia.playbackResumed(
cursorPosition: 1000,
extraProps: [
"av_content": "Content title",
...
]
)
```
#### playbackStopped
Event name : `av.stop`
*Generate a stop event. Automatically changes the `av_session_id`.*
`playbackStopped(cursorPosition[, callback, extraProps])`
| Parameter | Type | Description |
| --------------------- | -------- | ------------------------------------------- |
| cursorPosition | number | Current cursor position (ms) |
| callback (optional) | function | Callback function to execute after hit sent |
| extraProps (optional) | Object | Custom properties |
Example
```js
myMedia.playbackStopped(
1000,
function () {
console.log("Event av.stop generated");
},
{ customProp: "customValue" }
);
```
| Parameter | Type | Description |
| ---------------------------- | -------- | ---------------------------- |
| cursorPosition | Int | Current cursor position (ms) |
| properties vararg (optional) | Property | Custom properties |
```kotlin
myMedia.playbackStopped(
1000,
Property(...),
Property(...)
)
```
`func Media.playbackStopped(cursorPosition, extraProps)`
| Parameter | Type | Description |
| --------------------- | -------------------- | ---------------------------- |
| cursorPosition | Int | Current cursor position (ms) |
| extraProps (optional) | Map? | Custom properties |
Example
```java
myMedia.playbackStopped(
1000,
new HashMap() {{
put("av_content", "Content title");
...
}}
);
```
`myMedia.playbackStopped(cursorPosition: Int, extraProps: [String: Any]?)`
| Parameter | Type | Description |
| --------------------- | ---------------- | ---------------------------- |
| cursorPosition | Int | Current cursor position (ms) |
| extraProps (optional) | \[String: Any\]? | Custom properties |
Example
```swift
myMedia.playbackStopped(
cursorPosition: 1000,
extraProps: [
"av_content": "Content title",
...
]
)
```
#### seek
Event name : `av.forward` or `av.backward`
*Generate a seek event. `av.backward` is sent whenever the user goes back to an already seen cursorPosition. `av.forward` whenever the user goes past the current cursorPosition.*
`seek(oldCursorPosition, newCursorPosition[, callback, extraProps])`
| Parameter | Type | Description |
| --------------------- | -------- | ------------------------------------------- |
| oldCursorPosition | number | Cursor position before seeking (ms) |
| newCursorPosition | number | Cursor position after seeking (ms) |
| callback (optional) | function | Callback function to execute after hit sent |
| extraProps (optional) | Object | Custom properties |
Example
```js
myMedia.seek(
1000,
2000,
function () {
console.log("Event av.forward generated");
},
{ customProp: "customValue" }
);
myMedia.seek(
2000,
1000,
function () {
console.log("Event av.backward generated");
},
{ customProp: "customValue" }
);
```
| Parameter | Type | Description |
| ---------------------------- | -------- | ----------------------------------- |
| oldCursorPosition | Int | Cursor position before seeking (ms) |
| newCursorPosition | Int | Cursor position after seeking (ms) |
| properties vararg (optional) | Property | Custom properties |
```kotlin
myMedia.seek(
1000,
2000,
Property(...),
Property(...)
)
myMedia.seek(
2000,
1000,
Property(...),
Property(...)
)
```
`func Media.seek(oldCursorPosition, newCursorPosition, extraProps)`
| Parameter | Type | Description |
| --------------------- | -------------------- | ----------------------------------- |
| oldCursorPosition | Int | Cursor position before seeking (ms) |
| newCursorPosition | Int | Cursor position after seeking (ms) |
| extraProps (optional) | Map? | Custom properties |
Example
```java
myMedia.seek(
1000,
2000,
new HashMap() {{
put("av_content", "Content title");
...
}}
);
myMedia.seek(
2000,
1000,
new HashMap() {{
put("av_content", "Content title");
...
}}
);
```
`myMedia.seek(oldCursorPosition: Int, newCursorPosition: Int, extraProps: [String: Any]?)`
| Parameter | Type | Description |
| --------------------- | ---------------- | ----------------------------------- |
| oldCursorPosition | Int | Cursor position before seeking (ms) |
| newCursorPosition | Int | Cursor position after seeking (ms) |
| extraProps (optional) | \[String: Any\]? | Custom properties |
Example
```swift
myMedia.seek(
oldCursorPosition: 1000,
newCursorPosition: 2000,
extraProps: [
"av_content": "Content title",
...
]
)
myMedia.seek(
oldCursorPosition: 2000,
newCursorPosition: 1000,
extraProps: [
"av_content": "Content title",
...
]
)
```
#### playbackKill
This method doesn't generate any events.
*It is intended to be used for very specific use cases. This method will kill the current playback session, including all timers for heartbeats, without generating any events. It should only be called when absolutely necessary: we highly recommend using `playbackStopped()` instead.*
`playbackKill()`
Example
```js
myMedia.playbackKill();
```
### Contextual events
The following list of events is not taken into account in the calculation of media consumption times. They are one-time contextual events.
#### Playback speed
When changing the playback speed you have to use the dedicated method specifying the new speed factor as a decimal number.
Method:
`setPlaybackSpeed(playbackSpeed)`
*Declare a change in playback speed.*
| Parameter | Type | Description |
| ------------- | ------ | --------------------- |
| playbackSpeed | number | Playback speed factor |
Example
```js
myMedia.setPlaybackSpeed(2); // Media playback speed increased by a factor of two
```
| Parameter | Type | Description |
| ------------- | ------ | --------------------- |
| playbackSpeed | Double | Playback speed factor |
```kotlin
myMedia.playbackSpeed = 2.0
```
`func Media.setPlaybackSpeed(playbackSpeed)`
*Declare a change in playback speed.*
| Parameter | Type | Description |
| ------------- | ------ | --------------------- |
| playbackSpeed | Double | Playback speed factor |
Example
```java
myMedia.setPlaybackSpeed(2.0); // Media playback speed increased by a factor of two
```
`myMedia.playbackSpeed: Double = playbackSpeed`
*Declare a change in playback speed.*
| Parameter | Type | Description |
| ------------- | ------ | --------------------- |
| playbackSpeed | Double | Playback speed factor |
Example
```swift
myMedia.playbackSpeed = 2.0 // Media playback speed increased by a factor of two
```
The new playback speed factor will be taken into account when calculating the cursor positions of automated `heartbeats` events during playback. If necessary, you can tag the event associated with this speed change by using the `speed()` method.
#### adClick
Event name : `av.ad.click`
*Generate an ad click event.*
`adClick([callback, extraProps])`
| Parameter | Type | Description |
| --------------------- | -------- | ------------------------------------------- |
| callback (optional) | function | Callback function to execute after hit sent |
| extraProps (optional) | Object | Custom properties |
Example
```js
myMedia.adClick(
function () {
console.log("Event av.ad.click generated");
},
{ customProp: "customValue" }
);
```
| Parameter | Type | Description |
| ---------------------------- | -------- | ----------------- |
| properties vararg (optional) | Property | Custom properties |
```kotlin
myMedia.adClick(
Property(...),
Property(...)
)
```
`func Media.adClick(extraProps)`
| Parameter | Type | Description |
| --------------------- | -------------------- | ----------------- |
| extraProps (optional) | Map? | Custom properties |
Example
```java
myMedia.adClick(
new HashMap() {{
put("av_content", "Content title");
...
}}
);
```
`myMedia.adClick(extraProps: [String: Any]?)`
| Parameter | Type | Description |
| --------------------- | ---------------- | ----------------- |
| extraProps (optional) | \[String: Any\]? | Custom properties |
Example
```swift
myMedia.adClick(
extraProps: [
"av_content": "Content title",
...
]
)
```
#### adSkip
Event name : `av.ad.skip`
*Generate an ad skip event.*
`adSkip([callback, extraProps])`
| Parameter | Type | Description |
| --------------------- | -------- | ------------------------------------------- |
| callback (optional) | function | Callback function to execute after hit sent |
| extraProps (optional) | Object | Custom properties |
Example
```js
myMedia.adSkip(
function () {
console.log("Event av.ad.skip generated");
},
{ customProp: "customValue" }
);
```
| Parameter | Type | Description |
| ---------------------------- | -------- | ----------------- |
| properties vararg (optional) | Property | Custom properties |
```kotlin
myMedia.adSkip(
Property(...),
Property(...)
)
```
`func Media.adSkip(extraProps)`
| Parameter | Type | Description |
| --------------------- | -------------------- | ----------------- |
| extraProps (optional) | Map? | Custom properties |
Example
```java
myMedia.adSkip(
new HashMap() {{
put("av_content", "Content title");
...
}}
);
```
`myMedia.adSkip(extraProps: [String: Any]?)`
| Parameter | Type | Description |
| --------------------- | ---------------- | ----------------- |
| extraProps (optional) | \[String: Any\]? | Custom properties |
Example
```swift
myMedia.adSkip(
extraProps: [
"av_content": "Content title",
...
]
)
```
#### close
Event name : `av.close`
*Measure a closing.*
`close([callback, extraProps])`
| Parameter | Type | Description |
| --------------------- | -------- | ------------------------------------------- |
| callback (optional) | function | Callback function to execute after hit sent |
| extraProps (optional) | Object | Custom properties |
Example
```js
myMedia.close(
function () {
console.log("Event av.close generated");
},
{ customProp: "customValue" }
);
```
| Parameter | Type | Description |
| ---------------------------- | -------- | ----------------- |
| properties vararg (optional) | Property | Custom properties |
```kotlin
myMedia.close(
Property(...),
Property(...)
)
```
`func Media.close(extraProps)`
| Parameter | Type | Description |
| --------------------- | -------------------- | ----------------- |
| extraProps (optional) | Map? | Custom properties |
Example
```java
myMedia.close(
new HashMap() {{
put("av_content", "Content title");
...
}}
);
```
`myMedia.close(extraProps: [String: Any]?)`
| Parameter | Type | Description |
| --------------------- | ---------------- | ----------------- |
| extraProps (optional) | \[String: Any\]? | Custom properties |
Example
```swift
myMedia.close(
extraProps: [
"av_content": "Content title",
...
]
)
```
#### display
Event name : `av.display`
*Measure a display.*
`display([callback, extraProps])`
| Parameter | Type | Description |
| --------------------- | -------- | ------------------------------------------- |
| callback (optional) | function | Callback function to execute after hit sent |
| extraProps (optional) | Object | Custom properties |
Example
```js
myMedia.display(
function () {
console.log("Event av.display generated");
},
{ customProp: "customValue" }
);
```
| Parameter | Type | Description |
| ---------------------------- | -------- | ----------------- |
| properties vararg (optional) | Property | Custom properties |
```kotlin
myMedia.display(
1000,
Property(...),
Property(...)
)
```
`func Media.display(extraProps)`
| Parameter | Type | Description |
| --------------------- | -------------------- | ----------------- |
| extraProps (optional) | Map? | Custom properties |
Example
```java
myMedia.display(
new HashMap() {{
put("av_content", "Content title");
...
}}
);
```
`myMedia.display(extraProps: [String: Any]?)`
| Parameter | Type | Description |
| --------------------- | ---------------- | ----------------- |
| extraProps (optional) | \[String: Any\]? | Custom properties |
Example
```swift
myMedia.display(
extraProps: [
"av_content": "Content title",
...
]
)
```
#### error
Event name : `av.error`
*Measure an error preventing playback.*
`error(message[, callback, extraProps])`
| Parameter | Type | Description |
| --------------------- | -------- | ------------------------------------------- |
| message | string | Error message |
| callback (optional) | function | Callback function to execute after hit sent |
| extraProps (optional) | Object | Custom properties |
Example
```js
myMedia.error(
"Error loading video",
function () {
console.log("Event av.error generated");
},
{ customProp: "customValue" }
);
```
| Parameter | Type | Description |
| ---------------------------- | -------- | ----------------- |
| message | String | Error message |
| properties vararg (optional) | Property | Custom properties |
```kotlin
myMedia.error(
"Error loading video",
Property(...),
Property(...)
)
```
`func Media.error(message, extraProps)`
| Parameter | Type | Description |
| --------------------- | -------------------- | ----------------- |
| message | String | Error message |
| extraProps (optional) | Map? | Custom properties |
Example
```java
myMedia.error(
"Error loading video",
new HashMap() {{
put("av_content", "Content title");
...
}}
);
```
`myMedia.error(message: String, extraProps: [String: Any]?)`
| Parameter | Type | Description |
| --------------------- | ---------------- | ----------------- |
| message | String | Error message |
| extraProps (optional) | \[String: Any\]? | Custom properties |
Example
```swift
myMedia.error(
"Error loading video",
extraProps: [
"av_content": "Content title",
...
]
)
```
#### fullscreenOff
Event name : `av.fullscreen.off`
*Measure full screen deactivation.*
`fullscreenOff([callback, extraProps])`
| Parameter | Type | Description |
| --------------------- | -------- | ------------------------------------------- |
| callback (optional) | function | Callback function to execute after hit sent |
| extraProps (optional) | Object | Custom properties |
Example
```js
myMedia.fullscreenOff(
function () {
console.log("Event av.fullscreen.off generated");
},
{ customProp: "customValue" }
);
```
| Parameter | Type | Description |
| ---------------------------- | -------- | ----------------- |
| properties vararg (optional) | Property | Custom properties |
```kotlin
myMedia.fullscreenOff(
Property(...),
Property(...)
)
```
`func Media.fullscreenOff(extraProps)`
| Parameter | Type | Description |
| --------------------- | -------------------- | ----------------- |
| extraProps (optional) | Map? | Custom properties |
Example
```java
myMedia.fullscreenOff(
new HashMap() {{
put("av_content", "Content title");
...
}}
);
```
`myMedia.fullscreenOff(extraProps: [String: Any]?)`
| Parameter | Type | Description |
| --------------------- | ---------------- | ----------------- |
| extraProps (optional) | \[String: Any\]? | Custom properties |
Example
```swift
myMedia.fullscreenOff(
extraProps: [
"av_content": "Content title",
...
]
)
```
#### fullscreenOn
Event name : `av.fullscreen.on`
*Measure full screen activation.*
`fullscreenOn([callback, extraProps])`
| Parameter | Type | Description |
| --------------------- | -------- | ------------------------------------------- |
| callback (optional) | function | Callback function to execute after hit sent |
| extraProps (optional) | Object | Custom properties |
Example
```js
myMedia.fullscreenOn(
function () {
console.log("Event av.fullscreen.on generated");
},
{ customProp: "customValue" }
);
```
| Parameter | Type | Description |
| ---------------------------- | -------- | ----------------- |
| properties vararg (optional) | Property | Custom properties |
```kotlin
myMedia.fullscreenOn(
1000,
Property(...),
Property(...)
)
```
`func Media.fullscreenOn(extraProps)`
| Parameter | Type | Description |
| --------------------- | -------------------- | ----------------- |
| extraProps (optional) | Map? | Custom properties |
Example
```java
myMedia.fullscreenOn(
new HashMap() {{
put("av_content", "Content title");
...
}}
);
```
`myMedia.fullscreenOn(extraProps: [String: Any]?)`
| Parameter | Type | Description |
| --------------------- | ---------------- | ----------------- |
| extraProps (optional) | \[String: Any\]? | Custom properties |
Example
```swift
myMedia.fullscreenOn(
extraProps: [
"av_content": "Content title",
...
]
)
```
#### quality
Event name : `av.quality`
*Measure a quality change.*
`quality([callback, extraProps])`
| Parameter | Type | Description |
| --------------------- | -------- | ------------------------------------------- |
| callback (optional) | function | Callback function to execute after hit sent |
| extraProps (optional) | Object | Custom properties |
Example
```js
myMedia.quality(
function () {
console.log("Event av.quality generated");
},
{ customProp: "customValue" }
);
```
| Parameter | Type | Description |
| ---------------------------- | -------- | ----------------- |
| properties vararg (optional) | Property | Custom properties |
```kotlin
myMedia.quality(
Property(...),
Property(...)
)
```
`func Media.quality(extraProps)`
| Parameter | Type | Description |
| --------------------- | -------------------- | ----------------- |
| extraProps (optional) | Map? | Custom properties |
Example
```java
myMedia.quality(
new HashMap() {{
put("av_content", "Content title");
...
}}
);
```
`myMedia.quality(extraProps: [String: Any]?)`
| Parameter | Type | Description |
| --------------------- | ---------------- | ----------------- |
| extraProps (optional) | \[String: Any\]? | Custom properties |
Example
```swift
myMedia.quality(
extraProps: [
"av_content": "Content title",
...
]
)
```
#### share
Event name : `av.share`
*Measure a sharing.*
`share([callback, extraProps])`
| Parameter | Type | Description |
| --------------------- | -------- | ------------------------------------------- |
| callback (optional) | function | Callback function to execute after hit sent |
| extraProps (optional) | Object | Custom properties |
Example
```js
myMedia.share(
function () {
console.log("Event av.share generated");
},
{ customProp: "customValue" }
);
```
| Parameter | Type | Description |
| ---------------------------- | -------- | ----------------- |
| properties vararg (optional) | Property | Custom properties |
```kotlin
myMedia.share(
Property(...),
Property(...)
)
```
`func Media.share(extraProps)`
| Parameter | Type | Description |
| --------------------- | -------------------- | ----------------- |
| extraProps (optional) | Map? | Custom properties |
Example
```java
myMedia.share(
new HashMap() {{
put("av_content", "Content title");
...
}}
);
```
`myMedia.share(extraProps: [String: Any]?)`
| Parameter | Type | Description |
| --------------------- | ---------------- | ----------------- |
| extraProps (optional) | \[String: Any\]? | Custom properties |
Example
```swift
myMedia.share(
extraProps: [
"av_content": "Content title",
...
]
)
```
#### speed
Event name : `av.speed`
*Measure a speed change.*
`speed([callback, extraProps])`
| Parameter | Type | Description |
| --------------------- | -------- | ------------------------------------------- |
| callback (optional) | function | Callback function to execute after hit sent |
| extraProps (optional) | Object | Custom properties |
Example
```js
myMedia.speed(
function () {
console.log("Event av.speed generated");
},
{ customProp: "customValue" }
);
```
| Parameter | Type | Description |
| ---------------------------- | -------- | ----------------- |
| properties vararg (optional) | Property | Custom properties |
```kotlin
myMedia.speed(
Property(...),
Property(...)
)
```
`func Media.speed(extraProps)`
| Parameter | Type | Description |
| --------------------- | -------------------- | ----------------- |
| extraProps (optional) | Map? | Custom properties |
Example
```java
myMedia.speed(
new HashMap() {{
put("av_content", "Content title");
...
}}
);
```
`myMedia.speed(extraProps: [String: Any]?)`
| Parameter | Type | Description |
| --------------------- | ---------------- | ----------------- |
| extraProps (optional) | \[String: Any\]? | Custom properties |
Example
```swift
myMedia.speed(
extraProps: [
"av_content": "Content title",
...
]
)
```
#### subtitleOff
Event name : `av.subtitle.off`
*Measure subtitles deactivation*
`subtitleOff([callback, extraProps])`
| Parameter | Type | Description |
| --------------------- | -------- | ------------------------------------------- |
| callback (optional) | function | Callback function to execute after hit sent |
| extraProps (optional) | Object | Custom properties |
Example
```js
myMedia.subtitleOff(
function () {
console.log("Event av.subtitle.off generated");
},
{ customProp: "customValue" }
);
```
| Parameter | Type | Description |
| ---------------------------- | -------- | ----------------- |
| properties vararg (optional) | Property | Custom properties |
```kotlin
myMedia.subtitleOff(
Property(...),
Property(...)
)
```
`func Media.subtitleOff(extraProps)`
| Parameter | Type | Description |
| --------------------- | -------------------- | ----------------- |
| extraProps (optional) | Map? | Custom properties |
Example
```java
myMedia.subtitleOff(
new HashMap() {{
put("av_content", "Content title");
...
}}
);
```
`myMedia.subtitleOff(extraProps: [String: Any]?)`
| Parameter | Type | Description |
| --------------------- | ---------------- | ----------------- |
| extraProps (optional) | \[String: Any\]? | Custom properties |
Example
```swift
myMedia.subtitleOff(
extraProps: [
"av_content": "Content title",
...
]
)
```
#### subtitleOn
Event name : `av.subtitle.on`
*Measure subtitles activation.*
`subtitleOn([callback, extraProps])`
| Parameter | Type | Description |
| --------------------- | -------- | ------------------------------------------- |
| callback (optional) | function | Callback function to execute after hit sent |
| extraProps (optional) | Object | Custom properties |
Example
```js
myMedia.subtitleOn(
function () {
console.log("Event av.subtitle.on generated");
},
{ customProp: "customValue" }
);
```
| Parameter | Type | Description |
| ---------------------------- | -------- | ----------------- |
| properties vararg (optional) | Property | Custom properties |
```kotlin
myMedia.subtitleOn(
Property(...),
Property(...)
)
```
`func Media.subtitleOn(extraProps)`
| Parameter | Type | Description |
| --------------------- | -------------------- | ----------------- |
| extraProps (optional) | Map? | Custom properties |
Example
```java
myMedia.subtitleOn(
new HashMap() {{
put("av_content", "Content title");
...
}}
);
```
`myMedia.subtitleOn(extraProps: [String: Any]?)`
| Parameter | Type | Description |
| --------------------- | ---------------- | ----------------- |
| extraProps (optional) | \[String: Any\]? | Custom properties |
Example
```swift
myMedia.subtitleOn(
extraProps: [
"av_content": "Content title",
...
]
)
```
#### volume
Event name : `av.volume`
*Measure sound volume change.*
`volume([callback, extraProps])`
| Parameter | Type | Description |
| --------------------- | -------- | ------------------------------------------- |
| callback (optional) | function | Callback function to execute after hit sent |
| extraProps (optional) | Object | Custom properties |
Example
```js
myMedia.volume(
function () {
console.log("Event av.volume generated");
},
{ customProp: "customValue" }
);
```
| Parameter | Type | Description |
| ---------------------------- | -------- | ----------------- |
| properties vararg (optional) | Property | Custom properties |
```kotlin
myMedia.volume(
Property(...),
Property(...)
)
```
`func Media.volume(extraProps)`
| Parameter | Type | Description |
| --------------------- | -------------------- | ----------------- |
| extraProps (optional) | Map? | Custom properties |
Example
```java
myMedia.volume(
new HashMap() {{
put("av_content", "Content title");
...
}}
);
```
`myMedia.volume(extraProps: [String: Any]?)`
| Parameter | Type | Description |
| --------------------- | ---------------- | ----------------- |
| extraProps (optional) | \[String: Any\]? | Custom properties |
Example
```swift
myMedia.volume(
extraProps: [
"av_content": "Content title",
...
]
)
```
### Technical events
The following events are automatically generated by the Tracker. You can, however, call up the associated public marking methods if you need spot marking. Should the implementation be done without the SDK *(server-side)*, you would have to generate the following events manually.
#### bufferHeartbeat
Event name : `av.buffer.heartbeat`
*Generate a buffering heartbeat before the playback starts event.*
`bufferHeartbeat([callback, extraProps])`
| Parameter | Type | Description |
| --------------------- | -------- | ------------------------------------------- |
| callback (optional) | function | Callback function to execute after hit sent |
| extraProps (optional) | Object | Custom properties |
Example
```js
myMedia.bufferHeartbeat(
function () {
console.log("Event av.buffer.heartbeat generated");
},
{ customProp: "customValue" }
);
```
| Parameter | Type | Description |
| ---------------------------- | -------- | ----------------- |
| properties vararg (optional) | Property | Custom properties |
```kotlin
myMedia.bufferHeartbeat(
Property(...),
Property(...)
)
```
`func Media.bufferHeartbeat(extraProps)`
| Parameter | Type | Description |
| --------------------- | -------------------- | ----------------- |
| extraProps (optional) | Map? | Custom properties |
Example
```java
myMedia.bufferHeartbeat(
new HashMap() {{
put("av_content", "Content title");
...
}}
);
```
`myMedia.bufferHeartbeat(extraProps: [String: Any]?)`
| Parameter | Type | Description |
| --------------------- | ---------------- | ----------------- |
| extraProps (optional) | \[String: Any\]? | Custom properties |
Example
```swift
myMedia.bufferHeartbeat(
extraProps: [
"av_content": "Content title",
...
]
)
```
#### heartbeat
Event name: `av.heartbeat`
*Generate an heartbeat event. Event used to accurately track the playback time preferably sent at regular intervals when the content is actively playing.*
`heartbeat([cursorPosition, callback, extraProps])`
| Parameter | Type | Description |
| ------------------------- | -------- | ------------------------------------------- |
| cursorPosition (optional) | number | Current cursor position (ms) |
| callback (optional) | function | Callback function to execute after hit sent |
| extraProps (optional) | Object | Custom properties |
Example
```js
myMedia.heartbeat(
45,
function () {
console.log("Event av.heartbeat generated");
},
{ customProp: "customValue" }
);
```
| Parameter | Type | Description |
| ---------------------------- | -------- | ----------------- |
| properties vararg (optional) | Property | Custom properties |
```kotlin
myMedia.heartbeat(
Property(...),
Property(...)
)
```
`func Media.heartbeat(cursorPosition, extraProps)`
| Parameter | Type | Description |
| ------------------------- | -------------------- | ---------------------------- |
| cursorPosition (optional) | number | Current cursor position (ms) |
| extraProps (optional) | Map? | Custom properties |
Example
```java
myMedia.heartbeat(
45,
new HashMap() {{
put("av_content", "Content title");
...
}}
);
```
`myMedia.heartbeat(cursorPosition: Int, extraProps: [String: Any]?)`
| Parameter | Type | Description |
| ------------------------- | ---------------- | ---------------------------- |
| cursorPosition (optional) | number | Current cursor position (ms) |
| extraProps (optional) | \[String: Any\]? | Custom properties |
Example
```swift
myMedia.heartbeat(
cursorPosition: 45,
extraProps: [
"av_content": "Content title",
...
]
)
```
> note:
>
> The cursor position is not mandatory for tagging a `heartbeat` event. Without any value, it will be automatically calculated according to the context (playback speed factor, cursor position of the previous event).
#### rebufferHeartbeat
Event name : `av.rebuffer.heartbeat`
*Generate a buffering heartbeat after the playback starts event.*
`rebufferHeartbeat([callback, extraProps])`
| Parameter | Type | Description |
| --------------------- | -------- | ------------------------------------------- |
| callback (optional) | function | Callback function to execute after hit sent |
| extraProps (optional) | Object | Custom properties |
Example
```js
myMedia.rebufferHeartbeat(
function () {
console.log("Event av.rebuffer.heartbeat generated");
},
{ customProp: "customValue" }
);
```
| Parameter | Type | Description |
| ---------------------------- | -------- | ----------------- |
| properties vararg (optional) | Property | Custom properties |
```kotlin
myMedia.rebufferHeartbeat(
Property(...),
Property(...)
)
```
`func Media.rebufferHeartbeat(extraProps)`
| Parameter | Type | Description |
| --------------------- | -------------------- | ----------------- |
| extraProps (optional) | Map? | Custom properties |
Example
```java
myMedia.rebufferHeartbeat(
new HashMap() {{
put("av_content", "Content title");
...
}}
);
```
`myMedia.rebufferHeartbeat(extraProps: [String: Any]?)`
| Parameter | Type | Description |
| --------------------- | ---------------- | ----------------- |
| extraProps (optional) | \[String: Any\]? | Custom properties |
Example
```swift
myMedia.rebufferHeartbeat(
extraProps: [
"av_content": "Content title",
...
]
)
```
#### seekStart
Event name : `av.seek.start`
*Generate a beginning of seeking event.*
`seekStart(oldCursorPosition, [callback, extraProps])`
> note:
>
> This event is automatically raised when calling the `seek()`, `seekBackward()` or `seekForward()` methods.
| Parameter | Type | Description |
| --------------------- | -------- | ------------------------------------------- |
| oldCursorPosition | number | Cursor position before seeking (ms) |
| callback (optional) | function | Callback function to execute after hit sent |
| extraProps (optional) | Object | Custom properties |
Example
```js
myMedia.seekStart(
1000,
function () {
console.log("Event av.seek.start generated");
},
{ customProp: "customValue" }
);
```
| Parameter | Type | Description |
| ---------------------------- | -------- | ---------------------------- |
| oldCursorPosition | Int | Current cursor position (ms) |
| properties vararg (optional) | Property | Custom properties |
```kotlin
myMedia.seekStart(
1000,
Property(...),
Property(...)
)
```
`func Media.seekStart(oldCursorPosition, extraProps)`
| Parameter | Type | Description |
| --------------------- | -------------------- | ----------------------------------- |
| oldCursorPosition | Int | Cursor position before seeking (ms) |
| extraProps (optional) | Map? | Custom properties |
Example
```java
myMedia.seekStart(
1000,
new HashMap() {{
put("av_content", "Content title");
...
}}
);
```
`myMedia.seekStart(oldCursorPosition: Int, extraProps: [String: Any]?)`
| Parameter | Type | Description |
| --------------------- | ---------------- | ----------------------------------- |
| oldCursorPosition | Int | Cursor position before seeking (ms) |
| extraProps (optional) | \[String: Any\]? | Custom properties |
Example
```swift
myMedia.seekStart(
oldCursorPosition: 1000,
extraProps: [
"av_content": "Content title",
...
]
)
```
#### seekBackward
Event name : `av.backward`
*Generate a backward seeking event.*
`seekBackward(oldCursorPosition, newCursorPosition, [callback, extraProps])`
| Parameter | Type | Description |
| --------------------- | -------- | ------------------------------------------- |
| oldCursorPosition | number | Cursor position before seeking (ms) |
| newCursorPosition | number | Cursor position after seeking (ms) |
| callback (optional) | function | Callback function to execute after hit sent |
| extraProps (optional) | Object | Custom properties |
Example
```js
myMedia.seekBackward(
2000,
1000,
function () {
console.log("Event av.backward generated");
},
{ customProp: "customValue" }
);
```
| Parameter | Type | Description |
| ---------------------------- | -------- | ----------------------------------- |
| oldCursorPosition | Int | Cursor position before seeking (ms) |
| newCursorPosition | Int | Cursor position after seeking (ms) |
| properties vararg (optional) | Property | Custom properties |
```kotlin
myMedia.seekBackward(
2000,
1000,
Property(...),
Property(...)
)
```
`func Media.seekBackward(oldCursorPosition, newCursorPosition, extraProps)`
| Parameter | Type | Description |
| --------------------- | -------------------- | ----------------------------------- |
| oldCursorPosition | Int | Cursor position before seeking (ms) |
| newCursorPosition | Int | Cursor position after seeking (ms) |
| extraProps (optional) | Map? | Custom properties |
Example
```java
myMedia.seekBackward(
2000,
1000,
new HashMap() {{
put("av_content", "Content title");
...
}}
);
```
`myMedia.seekBackward(oldCursorPosition: Int, newCursorPosition: Int, extraProps: [String: Any]?)`
| Parameter | Type | Description |
| --------------------- | ---------------- | ----------------------------------- |
| oldCursorPosition | Int | Cursor position before seeking (ms) |
| newCursorPosition | Int | Cursor position after seeking (ms) |
| extraProps (optional) | \[String: Any\]? | Custom properties |
Example
```swift
myMedia.seekBackward(
oldCursorPosition: 2000,
newCursorPosition: 1000,
extraProps: [
"av_content": "Content title",
...
]
)
```
#### seekForward
Event name : `av.forward`
*Generate a forward seeking event.*
`seekForward(oldCursorPosition, newCursorPosition, [callback, extraProps])`
| Parameter | Type | Description |
| --------------------- | -------- | ------------------------------------------- |
| oldCursorPosition | number | Cursor position before seeking (ms) |
| newCursorPosition | number | Cursor position after seeking (ms) |
| callback (optional) | function | Callback function to execute after hit sent |
| extraProps (optional) | Object | Custom properties |
Example
```js
myMedia.seekForward(
1000,
2000,
function () {
console.log("Event av.forward generated");
},
{ customProp: "customValue" }
);
```
| Parameter | Type | Description |
| ---------------------------- | -------- | ----------------------------------- |
| oldCursorPosition | Int | Cursor position before seeking (ms) |
| newCursorPosition | Int | Cursor position after seeking (ms) |
| properties vararg (optional) | Property | Custom properties |
```kotlin
myMedia.seekForward(
1000,
2000,
Property(...),
Property(...)
)
```
`func Media.seekForward(oldCursorPosition, newCursorPosition, extraProps)`
| Parameter | Type | Description |
| --------------------- | -------------------- | ----------------------------------- |
| oldCursorPosition | Int | Cursor position before seeking (ms) |
| newCursorPosition | Int | Cursor position after seeking (ms) |
| extraProps (optional) | Map? | Custom properties |
Example
```java
myMedia.seekForward(
1000,
2000,
new HashMap() {{
put("av_content", "Content title");
...
}}
);
```
`myMedia.seekForward(oldCursorPosition: Int, newCursorPosition: Int, extraProps: [String: Any]?)`
| Parameter | Type | Description |
| --------------------- | ---------------- | ----------------------------------- |
| oldCursorPosition | Int | Cursor position before seeking (ms) |
| newCursorPosition | Int | Cursor position after seeking (ms) |
| extraProps (optional) | \[String: Any\]? | Custom properties |
Example
```swift
myMedia.seekForward(
oldCursorPosition: 1000,
newCursorPosition: 2000,
extraProps: [
"av_content": "Content title",
...
]
)
```
## Complete tagging example
```js
var myMedia = new pa.avInsights.Media({ 0: 5, 1: 10, 5: 60, 120: 0 }, 5); // Set heartbeats value
var properties = {
av_content_id: "fge234", //mandatory
av_content: "myContent",
av_content_type: "Video",
av_content_duration: 10000,
av_content_genre: ["entertainment"],
av_content_version: "short",
av_player: "HTML5_V123",
av_player_version: "1b",
av_player_position: "top",
av_broadcasting_type: "On Demand",
av_publication_date: 1562055880,
av_show: "The gist of the game",
av_show_season: "Season 1",
av_episode_id: "3134",
av_channel: "INFO",
av_author: "Piano",
av_broadcaster: "Direction 123",
av_language: "EN",
av_subtitles: "FR",
av_launch_reason: "Auto",
};
// Set media properties
myMedia.setProps(properties);
// Play attempt (cursor position 0 second)
myMedia.play(0);
// Buffering before playback start (cursor position 0 second)
myMedia.bufferStart(0);
// Playback start (cursor position 0 second)
myMedia.playbackStart(0);
// Buffering after 5 seconds of playback
myMedia.bufferStart(5000);
// Seek action (backward from cursor position 5 seconds to cursor position 3 seconds)
myMedia.seek(5000, 3000);
// Playback resume (cursor position 3 seconds)
myMedia.playbackResumed(3000);
// Playback pause (cursor position 9 seconds)
myMedia.playbackPaused(9000);
// Playback resume (cursor position 9 seconds)
myMedia.playbackResumed(9000);
// Playback stop (cursor position 15 seconds)
myMedia.playbackStopped(15000);
```
```kotlin
val heartbeat = SparseLongArray()
// first minute will be 5sec delay
heartbeat.put(0, 5)
// starting from minute 1, 10sec
heartbeat.put(1, 10)
// and after the 5th minute, the delay will be 60sec
heartbeat.put(5, 60)
val bufferHeartbeat = SparseLongArray()
bufferHeartbeat.put(0, 5)
val myMedia = PianoAnalytics.getInstance()
.mediaHelper("fge234")
.setHeartbeat(heartbeat)
.setBufferHeartbeat(bufferHeartbeat)
val properties = arrayOf(
Property(PropertyName("av_content"), "myContent"),
Property(PropertyName("av_content_type"), "Video"),
Property(PropertyName("av_content_duration"), 10000),
Property(PropertyName("av_content_genre"), arrayOf("entertainment")),
Property(PropertyName("av_content_version"), "short"),
Property(PropertyName("av_player"), "HTML5_V123"),
Property(PropertyName("av_player_version"), "1b"),
Property(PropertyName("av_player_position"), "top"),
Property(PropertyName("av_broadcasting_type"), "On Demand"),
Property(PropertyName("av_publication_date"), 1562055880),
Property(PropertyName("av_show"), "The gist of the game"),
Property(PropertyName("av_show_season"), "Season 1"),
Property(PropertyName("av_episode_id"), "3134"),
Property(PropertyName("av_channel"), "INFO"),
Property(PropertyName("av_author"), "Piano"),
Property(PropertyName("av_broadcaster"), "Direction 123"),
Property(PropertyName("av_language"), "EN"),
Property(PropertyName("av_subtitles"), "FR"),
Property(PropertyName("av_launch_reason"), "Auto"),
)
myMedia.setExtraProps(*properties)
// Play attempt (cursor position 0 second)
myMedia.play(0, *properties)
// Buffering before playback start (cursor position 0 second)
myMedia.bufferStart(0, *properties)
// Playback start (cursor position 0 second)
myMedia.playbackStart(0, *properties)
// Buffering after 5 seconds of playback
myMedia.bufferStart(5000, *properties)
// Seek action (backward from cursor position 5 seconds to cursor position 3 seconds)
myMedia.seek(5000, 3000, *properties)
// Playback resume (cursor position 3 seconds)
myMedia.playbackResumed(3000, *properties)
// Playback pause (cursor position 9 seconds)
myMedia.playbackPaused(9000, *properties)
// Playback resume (cursor position 9 seconds)
myMedia.playbackResumed(9000, *properties)
// Playback stop (cursor position 15 seconds)
myMedia.playbackStopped(15000, *properties)
```
```java
Media myMedia = new Media(pa);
HashMap properties = new HashMap() {{
put("av_content_id", "fge234"); //mandatory
put("av_content", "myContent");
put("av_content_type", "Video");
put("av_content_duration", 10000);
put("av_content_genre", new String[]{"entertainment"});
put("av_content_version", "short");
put("av_player", "HTML5_V123");
put("av_player_version", "1b");
put("av_player_position", "top");
put("av_broadcasting_type", "On Demand");
put("av_publication_date", 1562055880);
put("av_show", "The gist of the game");
put("av_show_season", "Season 1");
put("av_episode_id", "3134");
put("av_channel", "INFO");
put("av_author", "Piano");
put("av_broadcaster", "Direction 123");
put("av_language", "EN");
put("av_subtitles", "FR");
put("av_launch_reason", "Auto");
}};
// Play attempt (cursor position 0 second)
myMedia.play(0, properties);
// Buffering before playback start (cursor position 0 second)
myMedia.bufferStart(0, properties);
// Playback start (cursor position 0 second)
myMedia.playbackStart(0, properties);
// Buffering after 5 seconds of playback
myMedia.bufferStart(5000, properties);
// Seek action (backward from cursor position 5 seconds to cursor position 3 seconds)
myMedia.seek(5000, 3000, properties);
// Playback resume (cursor position 3 seconds)
myMedia.playbackResumed(3000, properties);
// Playback pause (cursor position 9 seconds)
myMedia.playbackPaused(9000, properties);
// Playback resume (cursor position 9 seconds)
myMedia.playbackResumed(9000, properties);
// Playback stop (cursor position 15 seconds)
myMedia.playbackStopped(15000, properties);
```
```swift
var myMedia = AVMedia(pa: pa)
myMedia.setHeartbeat(heartbeat: [
0: 5,
1: 10,
5: 60
])
myMedia.setBufferHeartbeat(bufferingHeartbeat: [
0: 5,
1: 10,
5: 60
])
var properties = [
"av_content_id": "fge234", //mandatory
"av_content": "myContent",
"av_content_type": "Video",
"av_content_duration": 10000,
"av_content_genre": ["entertainment"],
"av_content_version": "short",
"av_player": "HTML5_V123",
"av_player_version": "1b",
"av_player_position": "top",
"av_broadcasting_type": "On Demand",
"av_publication_date": 1562055880,
"av_show": "The gist of the game",
"av_show_season": "Season 1",
"av_episode_id": "3134",
"av_channel": "INFO",
"av_author": "Piano",
"av_broadcaster": "Direction 123",
"av_language": "EN",
"av_subtitles": "FR",
"av_launch_reason": "Auto"
]
myMedia.setExtraProperties(properties)
// Play attempt (cursor position 0 second)
myMedia.play(cursorPosition: 0, extraProps: properties)
// Buffering before playback start (cursor position 0 second)
myMedia.bufferStart(cursorPosition: 0, extraProps: properties)
// Playback start (cursor position 0 second)
myMedia.playbackStart(cursorPosition: 0, extraProps: properties)
// Buffering after 5 seconds of playback
myMedia.bufferStart(cursorPosition: 5000, extraProps: properties)
// Seek action (backward from cursor position 5 seconds to cursor position 3 seconds)
myMedia.seek(oldCursorPosition: 5000, newCursorPosition: 3000, extraProps: properties)
// Playback resume (cursor position 3 seconds)
myMedia.playbackResumed(cursorPosition: 3000, extraProps: properties)
// Playback pause (cursor position 9 seconds)
myMedia.playbackPaused(cursorPosition: 9000, extraProps: properties)
// Playback resume (cursor position 9 seconds)
myMedia.playbackResumed(cursorPosition: 9000, extraProps: properties)
// Playback stop (cursor position 15 seconds)
myMedia.playbackStopped(cursorPosition: 15000, extraProps: properties)
```
## Custom events tracking method
### track
The AV Insights `track()` method allows standard or custom events to be tracked.
Event name : `event` value
*Track standard or custom actions.*
`track(event, [options, callback, extraProps])`
| Parameter | Type | Description |
| --------------------- | -------- | ----------------------------------------------------------------------------- |
| event | string | Event to be generated (see list of standard events at the bottom of the page) |
| options (optional) | Object | Options depending on the event (see list of available options) |
| callback (optional) | function | Callback function to execute after hit sent |
| extraProps (optional) | Object | Custom properties |
Example
```js
var myMedia = new pa.avInsights.Media(5, 5);
// Buffer tagging
myMedia.track(
"av.buffer.start",
{ av_position: 0 },
function () {
console.log('Event "av.buffer.start" generated');
},
null
);
// Re-buffer tagging
myMedia.track(
"av.rebuffer.start",
{ av_position: 10 },
function () {
console.log('Event "av.rebuffer.start" generated');
},
null
);
// Play tagging
myMedia.track(
"av.play",
{ av_position: 0 },
function () {
console.log('Event "av.play" generated');
},
null
);
// Playback start tagging
myMedia.track(
"av.start",
{ av_position: 0 },
function () {
console.log('Event "av.start" generated');
},
null
);
// Playback pause tagging
myMedia.track(
"av.pause",
{ av_position: 10 },
function () {
console.log('Event "av.pause" generated');
},
null
);
// Playback resume tagging
myMedia.track(
"av.resume",
{ av_position: 10 },
function () {
console.log('Event "av.resume" generated');
},
null
);
// Playback stop tagging
myMedia.track(
"av.stop",
{ av_position: 20 },
function () {
console.log('Event "av.stop" generated');
},
null
);
// Seek forward tagging
myMedia.track(
"av.forward",
{ av_previous_position: 10, av_position: 20 },
function () {
console.log('Event "av.forward" generated');
},
null
);
// Seek backward tagging
myMedia.track(
"av.backward",
{ av_previous_position: 20, av_position: 10 },
function () {
console.log('Event "av.backward" generated');
},
null
);
// Ad click tagging
myMedia.track(
"av.ad.click",
null,
function () {
console.log('Event "av.ad.click" generated');
},
null
);
// Ad skip tagging
myMedia.track(
"av.ad.skip",
null,
function () {
console.log('Event "av.ad.skip" generated');
},
null
);
// Error tagging
myMedia.track(
"av.error",
{ av_player_error: "Player error" },
function () {
console.log('Event "av.error" generated');
},
null
);
// Display tagging
myMedia.track(
"av.display",
null,
function () {
console.log('Event "av.display" generated');
},
null
);
// Close tagging
myMedia.track(
"av.close",
null,
function () {
console.log('Event "av.close" generated');
},
null
);
// Volume tagging
myMedia.track(
"av.volume",
null,
function () {
console.log('Event "av.volume" generated');
},
null
);
// Subtitle on tagging
myMedia.track(
"av.subtitle.on",
null,
function () {
console.log('Event "av.subtitle.on" generated');
},
null
);
// Subtitle off tagging
myMedia.track(
"av.subtitle.off",
null,
function () {
console.log('Event "av.subtitle.off" generated');
},
null
);
// Full screen on tagging
myMedia.track(
"av.fullscreen.on",
null,
function () {
console.log('Event "av.fullscreen.on" generated');
},
null
);
// Full screen off tagging
myMedia.track(
"av.fullscreen.off",
null,
function () {
console.log('Event "av.fullscreen.off" generated');
},
null
);
// Quality tagging
myMedia.track(
"av.quality",
null,
function () {
console.log('Event "av.quality" generated');
},
null
);
// Speed tagging
myMedia.track(
"av.speed",
null,
function () {
console.log('Event "av.speed" generated');
},
null
);
// Share tagging
myMedia.track(
"av.share",
null,
function () {
console.log('Event "av.share" generated');
},
null
);
// Custom tagging
myMedia.track("custom", null, null, { customParam: "customValue" });
```
`func Media.track(event, options, extraProps)`
| Parameter | Type | Description |
| ---------- | -------------------- | ---------------------------------------------------------------------------------------- |
| event | String | Event to be generated (see list of standard events at the bottom of the page) |
| options | Map? | Options depending on the event (see list of available options at the bottom of the page) |
| extraProps | Map? | Custom properties |
Example
```java
myMedia.setHeartbeat(new SparseIntArray()
.append(0, 5)
.append(1, 10)
.append(5, 60)
);
myMedia.setBufferHeartbeat(new SparseIntArray()
.append(0, 5)
.append(1, 10)
.append(5, 60)
);
// Buffer tagging
myMedia.track(
"av.buffer.start",
new HashMap() {{
put("av_position", 0);
}},
new HashMap() {{
put("av_content", "Content title");
...
}}
);
// Re-buffer tagging
myMedia.track(
"av.rebuffer.start",
new HashMap() {{
put("av_position", 10);
}},
new HashMap() {{
put("av_content", "Content title");
...
}}
);
// Play tagging
myMedia.track(
"av.play",
new HashMap() {{
put("av_position", 0);
}},
new HashMap() {{
put("av_content", "Content title");
...
}}
);
...
// Custom tagging
myMedia.track(event: "av.custom", options: nil, extraProps: ["av_content": "Content title", ...]);
```
`myMedia.track(event: String, options: [String: Any]?, extraProps: [String: Any]?)`
| Parameter | Type | Description |
| --------------------- | ---------------- | ---------------------------------------------------------------------------------------- |
| event | String | Event to be generated (see list of standard events at the bottom of the page) |
| options (optional) | \[String: Any\]? | Options depending on the event (see list of available options at the bottom of the page) |
| extraProps (optional) | \[String: Any\]? | Custom properties |
Example
```swift
myMedia.setHeartbeat(heartbeat: [
0: 5,
1: 10,
5: 60
])
myMedia.setBufferHeartbeat(bufferHeartbeat: [
0: 5,
1: 10,
5: 60
])
// Buffer tagging
myMedia.track(event: "av.buffer.start", options: ["av_position": 0], extraProps: ["av_content": "Content title", ...])
// Re-buffer tagging
myMedia.track(event: "av.rebuffer.start", options: ["av_position": 10], extraProps: ["av_content": "Content title", ...])
// Play tagging
myMedia.track(event: "av.play", options: ["av_position": 0], extraProps: ["av_content": "Content title", ...])
...
// Custom tagging
myMedia.track(event: "av.custom", options: nil, extraProps: ["av_content": "Content title", ...])
```
### List of available options
| Option | Description |
| ---------------------- | ------------------------------------------ |
| av_position | Current cursor position (in milliseconds) |
| av_previous_position | Previous cursor position (in milliseconds) |
| av_player_error | Error preventing playback |
## Annexes
### Media sequence example
*This represents the ideal sequence for a media playback. As this does not include ads, there will be adjustments needed to cover this scenario.*

### Seek sequence example

### Media properties list
> note:
>
> Please note that the Piano Analytics SDK automatically adds properties to your AV events. You will need to exempt these properties too for proper AV tracking.
| Property | Description | Type | Mandatory | Example |
| ---------------------------- | ----------------------------------------------------------------------- | --------------- | --------- | -------------------------------------- |
| av_content_id | Content ID | string | Yes | 'bc35' |
| av_session_id | Session ID (generated by the SDK) | uuid\* | Yes | '799d9f3b-7307-5113-a260-2e1371e35fe6' |
| av_duration | Inter-event duration (in milliseconds) (generated by the SDK) | int | | 5000 |
| av_position | Cursor position (in milliseconds) (generated by the SDK for heartbeats) | int | | 5000 |
| av_previous_event | Previous event (generated by the SDK) | string | | 'av.start' |
| av_previous_position | Previous cursor position (in milliseconds) (generated by the SDK) | int | | 2000 |
| av_content | Content Label | string | | 'Broadchurch 3.5' |
| av_content_type | Content Type | string | | 'TV Show' |
| av_content_duration | Content Duration (in milliseconds) | int | | 2760000 |
| av_content_linked | Linked Content Label | string | | 'myLinkedContent' |
| av_publication_date | Publication Date (timestamp) | date | | 1501065673 |
| av_content_genre | Content genre(s) | array of string | | \["Crime","Drama","Mystery"\] |
| av_show | Show Label | string | | 'Broadchurch' |
| av_show_season | Show Season Label | string | | '3' |
| av_episode_id | Episode ID | string | | '5' |
| av_episode | Episode Label | string | | 'Episode #3.5' |
| av_channel | Channel Label | string | | 'ITV' |
| av_author | Author Name | string | | 'Chris Chibnall' |
| av_content_version | Content Version (full length, …) | string | | 'Full length' |
| av_content_duration_range | Duration range | string | | '0-10' |
| av_broadcasting_type | Broadcasting Type | string | | 'Live' |
| av_broadcaster | Broadcaster Name | string | | 'ITV' |
| av_ad_type | Ad Type | string | | 'Mid-roll' |
| av_player | Player Label | string | | 'Main' |
| av_player_version | Player Version | string | | '1.55' |
| av_player_position | Player Position | string | | 'Homepage' |
| av_auto_mode | Auto play mode | boolean | | true |
| av_language | Media language | string | | 'fr' |
| av_subtitles | Subtitles | string | | 'en' |
| av_launch_reason | Launch reason | string | | 'auto' |
### List of standard events
| Event | Type |
| --------------------- | --------- |
| av.play | Manual |
| av.buffer.start | Manual |
| av.buffer.heartbeat | Automatic |
| av.start | Manual |
| av.heartbeat | Automatic |
| av.pause | Manual |
| av.rebuffer.start | Manual |
| av.rebuffer.heartbeat | Automatic |
| av.resume | Manual |
| av.stop | Manual |
| av.seek.start | Manual |
| av.forward | Manual |
| av.backward | Manual |
| av.ad.click | Manual |
| av.ad.skip | Manual |
| av.error | Manual |
| av.display | Manual |
| av.close | Manual |
| av.volume | Manual |
| av.subtitle.on | Manual |
| av.subtitle.off | Manual |
| av.fullscreen.on | Manual |
| av.fullscreen.off | Manual |
| av.quality | Manual |
| av.speed | Manual |
| av.share | Manual |
---
## Collection API
The Piano Analytics Collection API enables direct transmission of analytics events via HTTP requests, offering a flexible solution for environments where SDK integration is not feasible.
## Pattern
### Event object
The event object is composed of two properties, while `name` represents the event, `data` is another object containing different the properties and values attached to the event.
```json
{
"name": "event.name",
"data": {
"property": "value",
"property2": "value"
}
}
```
> note:
>
> Please note that in HTTP requests, an array of events is required.
### POST
> important:
>
> Please note that we highly recommend using POST requests.
#### Endpoint
```http
https:///?s=&idclient=
```
| Header | Value |
| ------------ | ---------- |
| Content-Type | text/plain |
#### Body
```json
{
"events":
}
```
| Variable | Description | Example |
| ----------------- | ----------------------------------------- | --------------------------------------------------------------------------------- |
| collection-domain | Collection endpoint for your organization | your.collection.domain |
| path | Collection path | event |
| site-id | ID of the site the data belongs | 123456789 |
| visitor-id | Unique identifier of the visitor | 9e8d6d5f-143a-4a21-a7d5-7348b56e130d |
| events-array | Array of events objects | \[{"name": "event.name", "data": { "property": "value", "property2": "value" }}\] |
> note:
>
> Don't hesitate to read our [collection methods article](/analytics/data-collection/general/collection-methods/) to find the collection domain that has been assigned to you.
>
> You can also use a custom domain thanks to our [CDDC](/analytics/data-collection/general/collection-methods/#custom-domain-data-collection).
#### Example
Endpoint:
```http
https://your.collection.domain/event?s=123456789&idclient=9e8d6d5f-143a-4a21-a7d5-7348b56e130d
```
Body:
```json
{
"events": [
{
"name": "event.name",
"data": {
"property": "value",
"property2": "value"
}
}
]
}
```
#### Programming Examples
### JavaScript
```javascript
async function sendPianoAnalyticsEvent(events, siteId, visitorId, collectionDomain) {
const endpoint = `https://${collectionDomain}/event`;
const params = new URLSearchParams({
s: siteId,
idclient: visitorId,
});
try {
const response = await fetch(`${endpoint}?${params}`, {
method: "POST",
headers: {
"Content-Type": "text/plain",
},
body: JSON.stringify({ events }),
});
if (!response.ok) {
throw new Error(`HTTP error! status: ${response.status}`);
}
console.log("Events sent successfully");
return await response.text();
} catch (error) {
console.error("Failed to send events:", error);
// Implement retry logic or fallback here
throw error;
}
}
// Usage
sendPianoAnalyticsEvent(
[
{
name: "page.display",
data: {
page: "Homepage",
page_chapter1: "Main",
},
},
],
"123456789",
"9e8d6d5f-143a-4a21-a7d5-7348b56e130d",
"your.collection.domain"
);
```
### Python
```python
import requests
import json
import logging
def send_piano_analytics_event(events, site_id, visitor_id, collection_domain):
endpoint = f"https://{collection_domain}/event"
params = {
's': site_id,
'idclient': visitor_id
}
payload = {'events': events}
try:
response = requests.post(
endpoint,
params=params,
headers={'Content-Type': 'text/plain'},
data=json.dumps(payload),
timeout=30
)
response.raise_for_status()
logging.info("Events sent successfully")
return response.text
except requests.exceptions.RequestException as e:
logging.error(f"Failed to send events: {e}")
# Implement retry logic or fallback here
raise
# Usage
send_piano_analytics_event(
events=[{
"name": "page.display",
"data": {
"page": "Homepage",
"page_chapter1": "Main"
}
}],
site_id="123456789",
visitor_id="9e8d6d5f-143a-4a21-a7d5-7348b56e130d",
collection_domain="your.collection.domain"
)
```
### Go
```go
package main
import (
"bytes"
"encoding/json"
"fmt"
"net/http"
"net/url"
)
func sendPianoAnalyticsEvent(events []map[string]interface{}, siteID, visitorID, collectionDomain string) error {
endpoint := fmt.Sprintf("https://%s/event", collectionDomain)
params := url.Values{}
params.Set("s", siteID)
params.Set("idclient", visitorID)
payload := map[string]interface{}{
"events": events,
}
jsonData, err := json.Marshal(payload)
if err != nil {
return fmt.Errorf("failed to marshal payload: %w", err)
}
req, err := http.NewRequest("POST", endpoint+"?"+params.Encode(), bytes.NewBuffer(jsonData))
if err != nil {
return fmt.Errorf("failed to create request: %w", err)
}
req.Header.Set("Content-Type", "text/plain")
client := &http.Client{}
resp, err := client.Do(req)
if err != nil {
return fmt.Errorf("failed to send request: %w", err)
}
defer resp.Body.Close()
if resp.StatusCode != http.StatusOK {
return fmt.Errorf("HTTP error! status: %d", resp.StatusCode)
}
fmt.Println("Events sent successfully")
return nil
}
// Usage
func main() {
events := []map[string]interface{}{
{
"name": "page.display",
"data": map[string]interface{}{
"page": "Homepage",
"page_chapter1": "Main",
},
},
}
err := sendPianoAnalyticsEvent(
events,
"123456789",
"9e8d6d5f-143a-4a21-a7d5-7348b56e130d",
"your.collection.domain",
)
if err != nil {
fmt.Printf("Failed to send events: %v\n", err)
// Implement retry logic or fallback here
}
}
```
### Java
```java
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.URLEncoder;
import java.nio.charset.StandardCharsets;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;
import com.fasterxml.jackson.databind.ObjectMapper;
public class PianoAnalytics {
public static void sendPianoAnalyticsEvent(
List