1. Developing with Oracle Content Management As a Headless CMS
  2. Instrumenting Headless Sites with Consumption Analytics

6 Instrumenting Headless Sites with Consumption Analytics

Oracle Content Management provides consumption analytics features that enable you to track the usage and popularity of assets on sites.

The following sections describe how ‘headless’ sites (that is, created and managed outside of Oracle Content Management) can be instrumented with data collection capabilities to integrate with the consumption analytics feature:

The data collection for consumption analytics happens in JavaScript, typically running in client browsers. This is especially important for headless sites, which are manufactured server-side. Data collection will happen at the point of consumption in the browser through HTTP requests initiated from JavaScript.

Analytics Script

Include the following analytics script in the pages of the headless site:

<script type="text/javascript" src="//<instance>.ocecdn.oraclecloud.com/_sitesclouddelivery/analytics/ocm-asset-analytics.js?channelId=<channel-id>" async></script>

Please note the following:

  • This ocm-asset-analytics.js script will be served with a caching duration of two hours.
  • When loaded, this will add a global variable, SCSAnalytics, to the window namespace.

The ocm-asset-analytics.js library delivered from the your Oracle Content Management instance has the serviceId and accountId parameters embedded in it. The only parameter you need to supply is channelId.

Asset Events

Four events are currently supported and recorded for assets used on site pages. The following table describes these events:

Page Instrumentation

There are two methods of instrumenting pages for use with consumption analytics: you can augment the rendered asset markup on the page, or manually produce asset events with direct JavaScript calls.

To automatically record asset consumption events, you can add a special "data" attribute to the rendered assets markup on the page:
data-asset-operation
This attribute instructs the ocm-asset-analytics.js library to automatically produce analytic events.

The value syntax for the data-asset-operation attribute is "<page-event>:<asset-id>:<asset-event>". Multiple asset operations can be specified, separated by semicolons (;).

The following table lists the data-asset-operation parameters:

For example, the final markup of a simple content item might look like this:

<div data-asset-operation="view:COREBE60D5159507409B97E9B5CD27937B82:view">
    Hello World!
</div>

On the first line, note the data-asset-operation attribute. The ocm-asset-analytics.js library will automatically generate a "load" event for the asset when this markup appears on the page. Additionally, when the item is scrolled into view in the browser viewport, a "view" analytic event will be recorded.

The recordAssetOperation call will return a Boolean value indicating if the call was accepted and will be recorded in the analytics provider. The value false will be returned for all other conditions, including invalid parameters.

Component Attributes

To automatically record asset consumption events, you can add a special "data" attribute to the rendered assets markup on the page.

The following table describes parameters for the data-asset-operation attribute.

For example, the final markup of a simple content item might look like this:

<div data-asset-operation="view:COREBE60D5159507409B97E9B5CD27937B82:view">    
   Hello World!
</div>

JavaScript API Calls

Site JavaScript can make calls to the ocm-asset-analytics.js library to record asset events. The SCSAnalytics object exposes a single function to record asset events.

SCSAnalytics.recordAssetOperation( assetId, assetEvent, options ) → {Boolean}

Configuration Options

JavaScript within the site page can define the SCSAnalytics.config object before loading the ocm-asset-analytics.js library. Parameters can be supplied to the library without adding to its URL query string.

You can supply the following config parameters:

The following example shows how the ocm-asset-analytics.js library can be parameterized:

<script type="application/javascript">
window.SCSAnalytics = {    
    config: {        
        enableAnalytics: true,        
        serviceId: "<service-id>",        
        channelId: "<channel-id>",        
        accountId: "<account-id>",        
        useObservers: true,        
        loadProvider: true,        
        ready: [            
            function() {                
                console.log("The asset analytics library is ready.");
           }
       ]
    }
};
</script>
<script type="text/javascript" src="//<instance>.ocecdn.oraclecloud.com/_sitesclouddelivery/analytics/ocm-asset-analytics.js" async></script>

Add data-asset-operation Markup for Digital Assets

To add data-asset-operation markup for digital assets, add the following HTML code:

<img data-asset-operation="view:CONTBE5A53457DAE412B872C21DDC05FED5D" src="https://samples.mycontentdemo.com/content/published/api/v1.1/assets/CONTBE5A53457DAE412B872C21DDC05FED5D/Medium/Blog400px.jpg?channelToken=47c9fb78774d4485bc7090bf7b955632">

Add data-asset-operation Markup for Referenced Field Types

To add data-asset-operation markup for referenced field types, add the following HTML code:

<ul data-asset-operation="view:COREBE60D5159507409B97E9B5CD27937B82:view">

  <li>Name: Joe Bloggs</li>
 
  <li>Age: 39</li>
 
  <li>Photo: <img data-asset-operation="view:CONTBE5A53457DAE412B872C21DDC05FED5D:view" src="https://samples.mycontentdemo.com/content/published/api/v1.1/assets/CONTBE5A53457DAE412B872C21DDC05FED5D/Medium/Blog400px.jpg?channelToken=47c9fb78774d4485bc7090bf7b955632"></li>
 
  <li>Video: <video data-asset-operation="view:CONTBE5A53457DAE412B872C21DDC05FED5D:view;play:CONTBE5A53457DAE412B872C21DDC05FED5D:play" src="https://samples.mycontentdemo.com/content/published/api/v1.1/assets/CONTBE5A53457DAE412B872C21DDC05FED5D/Medium/Blog400px.jpg?channelToken=47c9fb78774d4485bc7090bf7b955632"></video></li>
 
</ul>

Use a Site-Specific Oracle Infinity Account

The account-id parameter can be used to configure the ocm-asset-analytics.js library to record asset operations in a specific Oracle Infinity account. In the script tag that includes the ocm-asset-analytics.js library, specify which account ID to use. 

<script type="text/javascript "src="//<instance>.ocecdn.oraclecloud.com/_sitesclouddelivery/analytics/ocm-asset-analytics.js?channelId=<channel-id>&accountId=<account-id>" async></script>

When recording to your own Oracle Infinity account, ensure that an Infinity tag named ocm_asset_analytics is defined and enabled for production use.

Use Your Own Oracle Infinity Tag

The ocm-asset-analytics.js library can be configured to work with an existing Infinity tag loaded on the headless site page.

Use the loadProvider configuration value (false) to avoid loading the default Infinity script. 

<!-- Include Oracle Infinity analytics -->
<script type="text/javascript" async src="//c.oracleinfinity.io/acs/account/<infinity-account-id>/js/<infinity-tag>/odc.js"></script>
 
<!-- Include the ocm-asset-analytics.js library, preventing it from loading its own copy of Infinity -->
<script type="text/javascript" src="//<instance>.ocecdn.oraclecloud.com/_sitesclouddelivery/analytics/ocm-asset-analytics.js?channelId=<channel-id>&loadProvider=false" async></script>