Bring Your Own Analytics Tool to Monitor Adoption

The C3 AI UI Framework allows you to bring your own analytics tool to monitor application usage and adoption. Additionally, the C3 AI UI Framework also provides Google Tag Manager as an out-of-the-box analytics tool. To enable Google Tag Manager in your application, please see Enable Google Tag Manager.

How to bring your own analytics tool

For each analytics tool, you need to do the following steps. We will use Heap Analytics as an example here For reference, this is what your package structure should look like:

Text

heapAnalytics
├── heapAnalytics.c3pkg.json
├── config
│   └── HeapAnalyticsConfig
│       └── HeapAnalyticsConfig.json
├── metadata
│   └── UiSdlPageWrapper
│       └── SDL.DefaultPageWrapper.(js|json)
├── src
│   └── HeapAnalyticsConfig.c3typ
└── ui
    └── c3
        └── src
            └── customInstances
                └── HA.HeapAnalyticsInjector.tsx

Create a new package heapAnalytics and its corresponding heapAnalytics.c3pkg.json.
Create a configuration type HeapAnalyticsConfig.

Type

type HeapAnalyticsConfig mixes Config, Singleton {
  identifierField: string
}

Set the config through HeapAnalyticsConfig.identifierField to make sure it points to your instance of your analytics tool.
Create a custom component HA.HeapAnalyticsInjector.tsx to inject the script tag and render children.

Make sure to sanitize your HTML content to avoid XSS attack. OWASP recommends DOMPurify for HTML sanitization. For more detailed guidance on how to implement this securely, you can refer to this OWASP documentation.

TypeScript

import React from 'react';
import { useConfig } from '@c3/ui/UiSdlUseConfig';

const Script = ({ sanitizedHTML }) => {
  useEffect(() => {
    // Inject desired code snippet to the innerHTML of script tag.
  }, [sanitizedHTML]);
  return null;
};

const HeapAnalyticsInjector = (props) => {
  const { children } = props;
  const configValue = useConfig('HeapAnalyticsConfig', 'identifierField');
  const sanitizedHTML = ...; // sanitize your HTML here
  return configValue ? (
    <>
      <Script innerHTML={sanitizedHTML} />
      {children}
    </>
  ) : (
    children
  );
};
export default HeapAnalyticsInjector;

Update the default page wrapper.

If you only need to add new analytics tools, you can create SDL.DefaultPageWrapper.json.

JSON

{
  "type": "UiSdlPageWrapper",
  "id": "SDL.DefaultPageWrapper",
  "containers": ["HA.HeapAnalyticsInjector"]
}

If you also need to disable any analytics tool that is already being used in the current package hierarchy, you can create SDL.DefaultPageWrapper.js.

JavaScript

(src) => {
  let containers = src.containers;

  const idxToRemove = containers.indexOfAny((container) => container.id === 'GTM.GoogleTagManagerInjector');
  containers = containers.removeAt(idxToRemove);

  containers = containers.with('HA.HeapAnalyticsInjector.tsx');

  src = src.withFieldAtPath('containers', containers);
  return src;
};

Add this analytics tool package to your c3pkg.json as a dependency.

JSON

//examplePackage.c3pkg.json
{
  "name": "examplePackage",
  "dependencies": {
    // Make sure you use the corresponding version of your analytics package
    "heapAnalytics": "8.5.0"
  }
}

You're reading the C3 AI UI Developer Guide. The full Table of Contents is here.

Copy link to this sectionHow to bring your own analytics tool

How to bring your own analytics tool