Integrate Consumption Analytics with Headless Samples in Oracle Content Management

Introduction

Oracle Content Management provides consumption analytics features that enable you to track the usage and popularity of assets on sites. Enabling consumption analytics for headless sites is a simple operation that requires only a few easy changes to your application source code.

In this tutorial, we’ll add consumption analytics to the headless React blog sample site and view the analytics in Oracle Content Management.

This tutorial focuses on React, but you can use a similar approach for other web technologies including Angular, Gatsby, Next.js, Svelte, and Vue.js.

The tutorial consists of three steps:

  1. Enable consumption analytics in Oracle Content Management
  2. Modify the sample code
  3. View the analytics

Prerequisites

Before proceeding with this tutorial, we recommend that you read the following information first:

To follow this tutorial, you’ll need:

Task 1: Enable Consumption Analytics in Oracle Content Management

If you don’t already have an Oracle Content Management instance, see Quick Start to learn how to register for Oracle Cloud, provision an Oracle Content Management instance, and configure Oracle Content Management as a headless CMS.

Once set up, you’ll need to configure the system to enable consumption analytics:

  1. Log in to the Oracle Content Management web interface as an administrator.

  2. Click System in the left navigation menu and choose Analytics in the dropdown list.

    This image shows the system settings.

  3. Enable Asset Consumption Analytics under Consumption Analytics. Optionally, you may enable your own Infinity service, which may be helpful if the analytics provided are too limited. You can then purchase an additional Infinity license and connect it to Oracle Content Management. Normally, this isn’t necessary to get started with analytics, and this tutorial won’t cover this.

  4. Click Save when you’re done. This is all we need to tell Oracle Content Management to start collecting basic analytics such as load and view events on specific channels, access by region and country, and which browsers and operating systems view assets.

Task 2: Modify the Sample Code

In this tutorial, we’ll obtain analytics for a React blog sample whenever a user views any of the subpages on the main page, such as the Drinks page. After consumption analytics have been configured, we’ll be able to view these analytics within the Oracle Content Management web interface.

This image shows the blog main page.

Add the Analytics Script

The following is the generic version of the analytics script we need to inject into the HTML code for the page that we want to collect analytics for:

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

For the React Blog sample, the following is the analytics script we’ll be adding to the HTML code:

<script type="text/javascript" src={`//${process.env.SERVER_URL.replace(/^https?:\/\//,'')}/_sitesclouddelivery/analytics/ocm-asset-analytics.js?channelId=${process.env.CHANNEL_ID}`} async> </script>

This will be added in the TopicsListPage.jsx file in the rendered component section under the TopicsListContainer div.

Notice that the instance is the server URL, which is hosted on https://samples.mycontentdemo.com for the samples that are available for Oracle Content Management. For the analytics script, we want to remove the https:// part from the server URL listed in the environment (.env) file, which is why we include .replace(/^https?:\/\//, '').

The analytics script is hosted at the server URL + /_sitesclouddelivery/analytics/ocm-asset-analytics.js, so we can see the script that analyzes the events at https://samples.mycontentdemo.com/_sitesclouddelivery/analytics/ocm-asset-analytics.js. Notice that analytics were enabled in Oracle Content Management (enableAnalytics is true), and that the service ID and account ID are embedded into the script instance here. We don’t need to deal with the service ID or account ID.

Obtain the Channel ID

We also need to obtain the channel ID for the content channel. Note that the channel ID and the channel token are two separate identifiers.

To find the channel ID:

  1. Log in to the Oracle Content Management web interface as an administrator.

  2. Click Content in the left navigation menu and choose Publishing Channels in the dropdown list.

  3. Select the appropriate channel (OCEGettingStartedChannel for the blog content).

  4. Click Edit and then open side panel.

  5. Open the Properties panel and then the API tab to view both the channel ID and channel token. Be careful not to refresh the channel token if you have that hardcoded in other places like the environment file.

This image shows the channel ID steps.

We need to set this in the environment (.env) file by adding the following to the bottom of the file:

CHANNEL_ID=RCHANNELA57XXXXXXXXXXXXXXXXXXXXXXXXXXXX

In addition, for the React Blog sample, we’ll need to add the following to the new webpack.DefinePlugin section of the plugin section of the webpack.base.config.js file:

'process.env.CHANNEL_ID': JSON.stringify(process.env.CHANNEL_ID),

Add the Page Instrumentation

To automatically record asset consumption events, we need to add a special “data” attribute to the rendered assets markup on the page. The data-asset-operation attribute instructs the ocm-asset-analytics.js library to automatically produce analytic events.

Details on what values to put into the data attribute can be found in the Oracle Content Management documentation.

For the React Blog sample, since we want to obtain analytics whenever a user views any of the subpages on the main page, such as the Drinks page, we’ll want the data-asset-operation attribute to be as follows:

<div data-asset-operation={`view:${topic.id}:view`} />

This will be placed in the HTML code next to every TopicListItem. The data-asset-operation attribute here indicates that when a user clicks on a subpage from the top-level topics list page, a log is sent through the network tab on a view of the relevant page asset.

Summary of All Code Changes to React Blog Sample

Here is what the TopicsListPage code looks like after the analytics script and data-asset-operation attribute are injected:

return (
<div data-testid="TopicsListContainer">
   <script type="text/javascript" src={`//${process.env.SERVER_URL.replace(/^https?:\/\//, '')}/_sitesclouddelivery/analytics/ocm-asset-analytics.js?channelId=${process.env.CHANNEL_ID}`} async> </script>
   <Header
      companyTitle={companyTitle}
      companyThumbnailRenditionUrls={companyThumbnailRenditionUrls}
      aboutUrl={aboutUrl}
      contactUrl={contactUrl}
   />
   {topics && (
   <div id="topics">
      {topics.map(
      (topic) => (
         <><div data-asset-operation={`view:${topic.id}:view`} /><TopicsListItem topic={topic} key={topic.id} /></>
      ),
      )}
   </div>
   )}
</div>
);

In addition, we had to obtain the channel ID, add the CHANNEL_ID parameter in the .env file, and update the webpack.base.config.js file plugin section to indicate this addition of the environment variable.

Task 3: View the Analytics

Now, we should be able to analyze the events. Let’s look at the HTML code on the blog home page:

This image shows the blog home page HTML.

Notice how the analytics script and data-asset-operation attribute are now added to the HTML code. This sends analytics data to an Oracle-owned Infinity analytics instance. The network event names that begin with ‘dcs.gif?’ are all the analytics being processed and sent over in the Request URL, which is analyzed in the analytics script.

This image shows the network tab.

The analytics data is queried daily from Infinity and displayed in the Oracle Content Management web interface. Note that it will take some time for the analytics to show up, and the data is usually delayed by about a day. To view the analytics, click on the asset, navigate to the menu icon in the top right to open the side bar, and select Analytics in the dropdown menu. Note that the bottom right corner shows when the data was last updated.

This image shows the analytics.

Conclusion and Next Steps

In this tutorial, we enabled consumption analytics and modified the headless React blog sample to provide those analytics to an Infinity analytics instance. Finally, we viewed those analytics directly within Oracle Content Management.

An additional next step for advanced features could be setting up your personal Infinity Analytics account and configuring Oracle Content Management to use that account.