Event data

Event data, e.g., information about when a page view event occurs, is submitted to the Piano platform using one of two supported mechanisms:

• A HTTP API: A specially crafted HTTP request is submitted to Piano to trigger a statistics update.

• A JavaScript API: The Piano platform gets automatically notified by the browser when a statistics update should take place.

The JavaScript API makes use of the HTTP API, and is the recommended mechanism for passing in event data. Interacting with the HTTP API directly might be relevant in custom applications and in settings where JavaScript cannot be executed.

JavaScript API

The JavaScript snippet to include on a given site's web pages will be automatically generated for you by the Piano Insight application when you register a new site, and might look something like shown below. The details around account and site identifiers will vary, of course.

<script type="text/javascript">
  var cX = cX || {}; cX.callQueue = cX.callQueue || [];
  cX.callQueue.push(['setSiteId', '1234']);  // <-- Insert the correct site identifier here!
  cX.callQueue.push(['sendPageViewEvent']);
</script>
<script type="text/javascript">
  (function(d,s,e,t){e=d.createElement(s);e.type='text/java'+s;e.async='async';
  e.src='https://cdn.cxense.com/cx.js';
  t=d.getElementsByTagName(s)[0];t.parentNode.insertBefore(e,t);})(document,'script');
</script>

Note the following:

• The JavaScript snippet you place on the page is really a shim or thin wrapper around the "real" script which is named cx.js.

• The cx.js script is loaded asynchronously by the client, hence there is no adverse performance impact perceived by the client when loading the page.

• The cx.js script is empowering some of the highest traffic web-pages worldwide and we have continuously optimized our approach since 2010.

• The cx.js script will usually always be served from the browser cache (no network traffic) and periodically an update request is sent but no content is transferred (HTML code 304 “Not Modified”), which keeps the network traffic and impact, especially for mobile browsers, at a minimum.

• The cx.js script resides on a content delivery network (CDN) in order to ensure low latency delivery globally.

• The cx.js script sets 1st and 3rd party cookies in order to do anonymous user identity management, to be able to tell the Piano platform not only which page was viewed but by whom.

• The cx.js script does not work on webpages that include prototype.js v1.6. Upgrade to v1.7 (or later) or even v1.5 (or earlier) to make it work.

• The cx.js script supports almost all browsers: IE5 and up, all Chrome, Safari and FireFox versions. It also supports embedded browsers in older mobile phones (Symbian, Blackberrty), gaming devices (Xbox, Playstation etc.), Smart TVs, in-stream converters like Opera Mini etc.

Alternative script placement

The Piano Insight tag should be placed within the section as this is the optimal position. If, for some reason, it is not possible to add the tag in the section, the tag can also be added to the element.

Asynchronous calls and synchronous calls

All functions in the JavaScript API can be invoked asynchronously or synchronously. The two example calls below are functionally equal and only differ on timing.

// Asynchronous example
var cX = cX || {}; cX.callQueue = cX.callQueue || [];
cX.callQueue.push(['setSiteId', '12345']);

// Synchronous example
cX.setSiteId('12345');

Note the following:

• When making asynchronous calls, cx.js can be loaded at any time, either before or after the call is added to the call queue.

• When making synchronous calls, cx.js must have been loaded before the call is executed.

AJAX web applications

In AJAX applications the content is typically loaded dynamically and the browser isn't running its normal page load sequence when new pages are loaded. Pages loaded this way can still be tracked with the JavaScript API, as long as initializePage and sendPageViewEvent are invoked for each logical page load. The AJAX application should have a scheme where the currently loaded content is read and set from a hash argument, as shown in the example below.

<!DOCTYPE html>
<html>
<head>
    <title>Sample AJAX application with Cxense Insight tracking</title>

    <!-- This example uses jQuery, but the method can be used with any AJAX library. -->
    <script type="text/javascript" src="https://ajax.googleapis.com/ajax/libs/jquery/1.9.0/jquery.min.js"></script>
    <script type="text/javascript" src="https://cdn.cxense.com/cx.js"></script>
</head>
<body>

    <!-- Page links. -->
    <div>
        <a href="#page=page1.html">Page1</a> |
        <a href="#page=page2.html">Page2</a> |
        <a href="#page=page3.html">Page3</a>
    </div>

    <!-- This div holds the page content for the individual pages. -->
    <div id="pageContent" style="border: 1px solid black; margin-top: 15px; padding: 5px;">
    </div>

    <script type="text/javascript">

        function loadPage() {
            var hashArgs = cX.parseHashArgs();
            $.ajax({
                url: hashArgs.page,
                success: function(pageContent, textStatus, jqXHR) {
                    document.getElementById('pageContent').innerHTML = pageContent;

                    // Initialize the tracking for this new page
                    cX.initializePage();

                    // Send a pageview event for this new page:
                    cX.setSiteId('0'); // <- Replace with correct site id
                    cX.sendPageViewEvent();
                }
            });
        }

        // Load a new page every time the hash changes
        $(window).on('hashchange', loadPage);


        // Initial page load
        var hashArgs = cX.parseHashArgs();
        if (!hashArgs.page) {
            location.hash = '#page=page1.html';
        } else {
            // onHashChange will not fire in this case, so we need to invoke loadPage() explicitly
            loadPage();
        }

    </script>

</body>
</html>

If you need to report a Content recommendations click at the same time, that can be done with the user of the helper function

• cX.sendSpaRecsClick(, []);

<!DOCTYPE html>
<html>
<head lang="en">
    <meta charset="UTF-8">
    <title></title>
</head>
<script type="text/javascript" src="https://cdn.cxense.com/cx.js"></script>
<body xmlns:tmp="javascript:">
    <div id="spaTemplate" class="template">
        <div class="headline">
            <h2>Single Page Instrumentation Example</h2>
        </div>
        <!--%
        var items = data.response.items;
        for (var i = 0; i < items.length; i++) {
          var item = items[i];
          var clickUrl = item.click_url + '?cx_test=spaTest';
          %-->
        <div class="item" onclick="openArticlePage('{{item.url}}','{{clickUrl}}');">
            <!--%
             cX.renderContainedImage({
                 container: { width: 290, height:172},
                 image: {
                     src: item['dominantthumbnail'],
                     dimensions: 'dominantthumbnaildimensions'
                 },
                 tooWideStrategy: 'zoom',
                 tooTallStrategy: 'zoom',
                 tooWideFocusPoint: 0.5,
                 tooTallFocusPoint:0.5,
                 horizontalAlign: 'center',
                 verticalAlign: 'center',
                 scaleFactorMax: 2.0,
                 scaleFactorMin: 0.8
             });
           %-->
            <h3>{{item.title}}</h3>
        </div>
        <!--%
      }
      %-->
    </div>
    <div id="spaTarget"></div>
    <script type="text/javascript">
        cX.setSiteId('1234567890');
        cX.sendPageViewEvent();
        function openArticlePage(loc, clickUrl) {
            // First report the click url before leaving the current page
            cX.sendSpaRecsClick(clickUrl);
            // ..
            //  Do navigational logic loading up new page, history.pushState(..), etc
            // ..
            // Report the analytics event as normal
            cX.initializePage();
            cX.sendPageViewEvent();
        }
        cX.insertWidget({
            widgetId : '70ee1cb56fa19asdasda061ed7fdea6fd',
            templateElementId : 'spaTemplate',
            targetElementId : 'spaTarget'
        } );
    </script>
</body>
</html></pre>
<pre>

Reporting from within mobile applications

Sending events from within mobile applications is done in a few different ways depending on how the mobile application itself is constructed. There are four main approaches:

1. Mobile web application, i.e., the app runs inside a standard browser on the mobile device. Integration in the mobile web application is then no different from integration with a normal web site: The Piano Insight JavaScript tag can be used out-of-the-box, and user profiles and content profiles are created automatically.

2. Native app wrapper for mobile web application, i.e., the app is native but is really just a thin wrapper around a browser embedded in the app. As above, all Piano JavaScript tag can be used out-of-the-box, and user and content profiling will happen automatically. Simple integration technologies that build both native iPhone and Android application wrappers are available, e.g., PhoneGap.

3. Native app wrapper with HTML rendering, i.e., the app is native but the UI is rendered using HTML possibly served from local resources. The Piano JavaScript tag can be used, but there are two things the application developer needs to consider:

   1. The native app does not have a URL for a page. This can be addressed by creating synthetic URLs and passing these to Piano using the location override mechanism.

   2. The Piano crawler cannot access the content of an application page, and thus cannot create a content profile or user profiles. The content must be made available to Piano in some other way, e.g., by serving the content on a webserver (in parallel to the app) and having the synthetic URLs reference this, or by pushing the content to Piano.

4. Native app with native UI and rendering, i.e., the app is fully native and does not run JavaScript. With this approach the Piano JavaScript tag cannot be used, but the application will have to be instrumented to call the relevant Piano APIs. Also, like above, the content is not accessible to Piano so it must be made available to Piano in some way if it is to be used for building user and content profiles. For the availability of native SDKs for various mobile platforms, please contact Piano support.

Disabling the auto-refresh check

cx.js has a check to prevent reporting of automatic page refreshes. In some cases, for example in AJAX applications where the URL does not change, you might want to disable this protection.

You can do that with the useAutoRefreshCheck parameter to the sendPageViewEvent function to disable this check:

// Asynchronous
cX.callQueue.push(['sendPageViewEvent', { useAutoRefreshCheck: false }]);

// Synchronous
cX.sendPageViewEvent( { useAutoRefreshCheck: false } );

Overriding the reported location URL

The sendPageViewEvent function will automatically report the current URL of the window from which the call is executed, i.e., the value of window.location.href. In certain cases there might be a need to override this default behavior, and that can be done by adding a location parameter to the sendPageViewEvent call, as shown below.

// Asynchronous
cX.callQueue.push(['sendPageViewEvent', { 'location': 'https://www.corp.com/artId123.html' }]);

// Synchronous
cX.sendPageViewEvent({ 'location': 'https://www.corp.com/artId123.html' });

Let's take for example the canonical URL of https://www.interesting.com/example-page.html.

Maintain all traffic to the canonical URL, and incorporate the use of a "channel" parameter e.g.:

cX.callQueue.push(['setCustomParameters', { 'cx_channel': '[platform_name]' }]);

to enable break-outs of the platform-specific traffic data:

1. Web Page Views: 50 - (optional inclusion of a ‘web’ channel, though as web is often the ‘default’, a lack of a specific channel is usual for this case.)

2. AMP Page Views: 23 - 'cx_channel': 'amp'

3. FIA Page Viewss: 10 - 'cx_channel': 'fia'

4. iOS Page Views: 12 - 'cx_channel': 'ios'

5. Android Page Views: 5 - 'cx_channel': 'android'

6. Total Page Views: 100 ("All Channels!")

This way each platform owner can analyze the value of an individual URL as above, whilst the product owner maintains a holistic, unified view of the value the single URL generated.

Further, platform owners can use the same filter (filter: cx_channel=[platform]) to identify only their platform’s traffic. Similarly, the Product owner - responsible for all channels - can include a total view (no filter), or any combination of platform filters to split out each platform if/as required.

filter: cx_channel=[platform1], [platform2], [platform3]

filter: cx_channel != [platform5]

Including all platform values removes web traffic (as it usually has no channel specification), or alternatively you can incorporate a platform value on web traffic as well, then use a 'not web' filter instead.

Overriding the reported referrer URL

The sendPageViewEvent function will automatically report the current referrer URL of the document from which the call is executed, i.e., the value of document.referrer. In certain cases, there might be a need to override this default behavior, and that can be done by adding a referrer parameter to the sendPageViewEvent call, as shown below.

// Asynchronous
cX.callQueue.push(['sendPageViewEvent', { 'referrer': 'https://www.corp.com/artId123.html' }]);

// Synchronous
cX.sendPageViewEvent({ 'referrer': 'https://www.corp.com/artId123.html' });

External user identifiers

As mentioned above, the cx.js script does basic anonymous user identity management, which allows each event to be associated with a user. However, in some use cases, it is beneficial to be able to link a customer-specific way of referencing a user with how Piano references the same user. For example, perhaps your site has a login mechanism and you want to be able to use your own way of referring to users in relevant API methods or want to augment the Piano platform with data you have about such users, or want to be able to track those logged-in users across different devices to build truly cross-device unique user profiles!

The JavaScript API exposes the addExternalId method to allow you to augment the event with information about which user (using whatever identity management scheme you prefer) that generated the event. The external user identifiers you specify are then consolidated on the server side with the user identifier that cx.js uses.

This functionality is also available using a server-side authenticated API: /profile/user/external/link/update

External user identifiers can take many forms, some typical examples include, for e.g.:

• Application-specific login identifiers (i.e. CRM, eCommerce, newsletter database)

• Apple identifiers for advertisers (IFA)

• Facebook identifiers (as a hash thereof)

• Google identifiers (as a hash thereof)

• Email address (as a hash thereof)

According to our data-philosophy:

• None of the information we aggregate should be based on PII (Personal Identifiable Information), thus the application of a hash-function (Wiki link) is recommended.

An example invocation of addExternalId is shown below.

// Asynchronous
cX.callQueue.push(['addExternalId', { 'id': 'subscriber14', 'type': 'xyz'}]);

// Synchronous
cX.addExternalId({ 'id': 'subscriber14', 'type': 'xyz'});

A complete tag might look like this:

(Specifying an external user identifier (complete example))

<!-- Cxense script begin -->
<script type="text/javascript">
  var cX = cX || {}; cX.callQueue = cX.callQueue || [];
  cX.callQueue.push(['addExternalId', { 'id': 'subscriber14', 'type': 'xyz'}]);
  cX.callQueue.push(['setSiteId', '1234']); // <-- Insert the correct site identifier here!
  cX.callQueue.push(['sendPageViewEvent']);
</script>
<script type="text/javascript">
  (function(d,s,e,t){e=d.createElement(s);e.type='text/java'+s;e.async='async';
  e.src='https://cdn.cxense.com/cx.js';
  t=d.getElementsByTagName(s)[0];t.parentNode.insertBefore(e,t);})(document,'script');
</script>
<!-- Cxense script end -->

Note that specifying external user identifiers does not have to happen on every page view event. E.g., it might just happen on the page the user accesses after having logged in. As long as the linking between the external user identifier and the internal user identifier used by cx.js happens at least once, this is remembered server-side. The linking information is lost, however, if the server-side mapping is cleared (e.g., for capacity reasons users for which no activity has been observed for a very long time might have their mappings purged). The linking operation should happen at least once a month, preferably more often (this ensures that the server-side correctly distinguishes between active an in-active identities.

HTTP API

The cx.js script mentioned above collects various pieces of data, builds up a URL that encodes this information, and sends this back to the Piano platform by making a standard HTTP request to the Piano servers. This HTTP API can also be invoked directly by clients. The URL currently encodes the following parameters:

The HTTP headers that are received as part of the HTTP request for the URL also carry important information that is used by the Piano platform:

GET /Repo/rep.html?ver=1&typ=pgv&sid=1234&loc=http%3A//example.com/app%3Fa%3Db%26c%3Dd&ref=&ckp=user1234567891011&cks=session1234567891011 HTTP/1.0
Host: comcluster.cxense.com
X-Forwarded-For: 173.203.85.136
User-Agent: ExampleBrowser v1.0

Sending requests over HTTPS instead of HTTP is also supported, but then the hostname is scomcluster.cxense.com instead of comcluster.cxense.com.

The response can be HTML, as in the above example, or it can be a GIF pixel image. To use the GIF pixel image type response, just replace rep.html with rep.gif as shown in the example below.

Minimal HTTP GET request with GIF pixel image response:

GET /Repo/rep.gif?ver=1&typ=pgv&sid=1234&loc=http%3A//example.com/app%3Fa%3Db%26c%3Dd&ref=&ckp=user1234567891011&cks=session1234567891011&rnd=0 HTTP/1.0
Host: comcluster.cxense.com
X-Forwarded-For: 173.203.85.136
User-Agent: ExampleBrowser v1.0

Last updated: July 07, 2026