Skip to main content

Bold Penguin SDK Analytics

The Bold Penguin SDK provides integration hooks for common analytics providers like Google Analytics and HubSpot.

Initialization​

Analytics is an optional set of configuration parameters you can pass when you call the init() function from @boldpenguin/sdk.

When initializing the Bold Penguin SDK with analytics integration your init() call should look like this example:

import { init } from "@boldpenguin/sdk";
import googleAnalytics from "@analytics/google-analytics";

init({
  clientId: environment.clientId,
  env: environment.environmentFlag,
  analytics: {
    app: "Your App Name Here",
    plugins: [
      // See section about plugins below
      googleAnalytics({
        trackingId: process.env.REACT_APP_GOOGLE_ANALYTICS_ID,
      }),
    ],
    customVariables: {
      foo: "bar",
    },
  },
});

You will also want to include the Bold Penguin SDK analytics container towards the top of your DOM tree in order to consume your events as shown below.

<div>
  <bp-sdk-root>
    <bp-sdk-analytics-container>
      <bp-sdk-message-container>
      <bp-sdk-question-set-navigation-container />
      <bp-sdk-question-set-container />
      <bp-sdk-quote-request-container />
    </bp-sdk-analytics-container>
  </bp-sdk-root>
</div>

Plugins​

The Bold Penguin SDK uses getanalytics.io as the analytics integration library. Many of the most popular analytics services already have plugins available for this library (https://getanalytics.io/plugins). If your analytics service does not already have an integration there is documentation for creating your own (https://getanalytics.io/plugins/writing-plugins/).

Emitting Analytics Events​

Once you have initialized the analytics integration in the Bold Penguin SDK you have two options for how to emit analytics events back to your provider.

Option One: Direct API integration​

You can use the window.BpSdk.analytics global object to directly interface with the core analytics API (https://getanalytics.io/api/). This gives you full control over when you send all of your pageview, tracking, and other events as well as letting you retrieve information from the underlying library.

Option Two: External component integration​

In the Bold Penguin SDK you can optionally mount the <bp-sdk-analytics-container> component which will start listening for specific DOM events that you can bubble up from your external components and will integrate with the analytics API for you. Below are the shapes of the objects that should be emitted by your components to be picked up by the SDK components.

Custom Variables​

These custom variables will be sent with all of your analytics track events after initializing them. You can add them when initializing the Bold Penguin SDK as shown in the initialization section above.

import { IAnalyticsVariables } from "@boldpenguin/sdk";

const analyticsVariables: IAnalyticsVariables = {
  foo: "bar",
};

const event = new CustomEvent("BPAnalyticsVariables", {
  detail: analyticsVariables,
});

yourElement.dispatch(event);

Page Load​

import { IAnalyticsPageEventDetail } from '@boldpenguin/sdk';

const analyticsPageDetail: IAnalyticsPageEventDetail = {
  pageData: {
    title?: '',
    url?: '',
    path:?: '',
    search?: '',
    width?: '',
    height?: ''
  }
};

const event = new CustomEvent('BPAnalyticsPage', { detail: analyticsPageDetail });

yourElement.dispatch(event);

Identify​

import { IAnalyticsIdentifyEventDetail } from '@boldpenguin/sdk';

const analyticsIdentifyDetail: IAnalyticsIdentifyEventDetail = {
  userId: '',
  traits?: {},
  options?: {}
};

const event = new CustomEvent('BPAnalyticsIdentify', { detail: analyticsIdentifyDetail });

yourElement.dispatch(event);

Track​

import { IAnalyticsTrackEventDetail } from '@boldpenguin/sdk';

const analyticsTrackDetail: IAnalyticsTrackEventDetail = {
  eventName: '',
  eventPayload?: {},
  eventOptions?: {}
};

const event = new CustomEvent('BPAnalyticsTrack', { detail: analyticsTrackDetail });

yourElement.dispatch(event);