How do I implement the Piano Analytics SDK?

This guide covers the setup of the Piano Analytics JavaScript SDK on a new site.

Prerequisite

You must have already created your site in the Data Collection Portal and retrieved your site_id and collection domain (see How do I add a new site in Piano Analytics?).

Step 1 — Load the SDK

Add the SDK script to your page, ideally in the <head>:

<script src="https://tag.aticdn.net/piano-analytics.js"></script>

Step 2 — Configure

Call pa.setConfigurations() with your site ID and collection domain (both required):

CODE

pa.setConfigurations({
  site: 123456,
  collectDomain: "your-collect-domain.com"
});

Full configuration reference: https://developers.piano.io/analytics/data-collection/how-to-send-events/send-events-via-sdks/

Step 3 — Send events

CODE

pa.sendEvent('page.display', {
  'page': 'homepage',
  'page_chapter1': 'main'
});

Load order matters: the SDK must be loaded and configured before any tracking call. If pa.sendEvent() fires before pa.setConfigurations(), events will not be collected.

When to Expect Data

Tags fire immediately after implementation. Reports populate the following day (e.g. tagging live on December 24 → first metrics on December 25). Data is not retroactive.

Troubleshooting

No data collected: verify the SDK script loads before pa.setConfigurations(). Confirm site matches your 6-digit site ID and collectDomain is correct. Check that firewalls/ad blockers are not blocking requests to the collection domain. If using a TMS, verify tag execution order.
Data under the wrong site: retrieve the correct site ID from the Data Collection Portal and compare it to the value in your configuration.
Requests failing or blocked: verify collectDomain, check for cross-origin issues, and confirm no content security policies are blocking the collection domain.
No data after 24 hours: use browser developer tools to confirm the SDK loads and requests return HTTP 200. Contact Piano Support with your organization name, site ID, and SDK version.