Understanding Piano Analytics Data Collection

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

Custom Properties

For unique business requirements, create custom events and properties to capture specific interactions:

// 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 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. 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>
  <head lang="en">
    <meta charset="UTF-8" />
    <title>My Page</title>
    <script>
      (function (_config) {
        var script = document.createElement("script");
        script.src = "https://tag.aticdn.net/piano-analytics.js";
        script.async = true;
        script.crossorigin = "anonymous";
        script.dataset.config = JSON.stringify(_config);
        document.head.appendChild(script);
      })({
        site: 123456789,
        collectDomain: "https://xxxxxxx.pa-cd.com",
        instantTracking: true,
      });
    </script>
  </head>
  <body>
    ...
  </body>
</html>

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
Android (3.3.0+)
Android
Apple
HTTP

<html>
  <head lang="en">
    <meta charset="UTF-8" />
    <title>My Page</title>
    <script>
      (function (_config) {
        var script = document.createElement("script");
        script.src = "https://tag.aticdn.net/piano-analytics.js";
        script.async = true;
        script.crossorigin = "anonymous";
        script.dataset.config = JSON.stringify(_config);
        document.head.appendChild(script);
      })({
        site: 123456789,
        collectDomain: "https://xxxxxxx.pa-cd.com",
      });
    </script>
  </head>
  <body>
    ...
    <script type="text/javascript">
      pa.sendEvent(
        "page.display", // Event name
        {
          page: "page name", // Event properties
          page_chapter1: "level 1",
          page_chapter2: "level 2",
          page_chapter3: "level 3",
        }
      );
    </script>
  </body>
</html>

Before 6.16.0

<html>
  <head lang="en">
    <meta charset="UTF-8" />
    <title>My Page</title>
    <script
      type="text/javascript"
      crossorigin="anonymous"
      src="https://tag.aticdn.net/piano-analytics.js"
    ></script>
    <script type="text/javascript">
      pa.setConfigurations({
        // Basic configuration to send events
        site: 123456789,
        collectDomain: "https://<xxxxxxx>.pa-cd.com",
      });
    </script>
  </head>
  <body>
    ...
    <script type="text/javascript">
      pa.sendEvent(
        "page.display", // Event name
        {
          page: "page name", // Event properties
          page_chapter1: "level 1",
          page_chapter2: "level 2",
          page_chapter3: "level 3",
        }
      );
    </script>
  </body>
</html>

pa.setConfiguration(new Configuration.Builder()
  .withCollectDomain("<xxxxxxx>.pa-cd.com")
  .withSite(123456789)
  .build()
);
	...
pa.sendEvent(new Event("page.display", new HashMap<String, Object>() {{ // Event name
  put("page", "page name"); // Event properties
  put("page_chapter1", "level 1");
  put("page_chapter2", "level 2");
  put("page_chapter3", "level 3");
}}));

import io.piano.android.analytics.Configuration
import io.piano.android.analytics.PianoAnalytics

...

val configuration = Configuration.Builder(
    collectDomain = "<xxxxxxx>.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()
)

pa.setConfiguration(ConfigurationBuilder()
  .withCollectDomain("<xxxxxxx>.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"
]))

const site_id = `123456789`;
const visitor_id = `<visitor_id>`;
const endpoint = `<xxxxxxx>.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.

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:

Javascript
Android (3.3.0+)
Android
Apple
HTTP

<html>
  <head lang="en">
    <meta charset="UTF-8" />
    <title>My Page</title>
    <script>
      (function (_config) {
        var script = document.createElement("script");
        script.src = "https://tag.aticdn.net/piano-analytics.js";
        script.async = true;
        script.crossorigin = "anonymous";
        script.dataset.config = JSON.stringify(_config);
        document.head.appendChild(script);
      })({
        site: 123456789,
        collectDomain: "https://xxxxxxx.pa-cd.com",
      });
    </script>
  </head>
  <body>
    <button>My button</button>

    <script type="text/javascript">
      const button = document.querySelector("button");

      button.addEventListener("click", (event) => {
        pa.sendEvent(
          "click.navigation", // 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",
          }
        );
      });
    </script>
  </body>
</html>

pa.sendEvent(new Event("click.navigation", new HashMap<String, Object>() {{ // 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");
}}));

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()
)

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"
]))

const site_id = `123456789`;
const visitor_id = `<visitor_id>`;
const endpoint = `<xxxxxxx>.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

Core Concepts​

Events​

Properties​

Data Model Flexibility​

Standard Properties (450+ available)​

Custom Properties​

Property Processing Types​

Getting Started: Your First Events​

Quick Start with Instant Tracking​

Example 1: Tracking Page Views​

Example 2: Tracking User Interactions​