Google Analytics

You can send Javascript impressions and events to Google Analytics and send Google analytics hit data to Split as events. With this integration you can use the event data you already collect via Google Analytics to power analytics and experimentation within Split.

Google Analytics 4 (GA4)

GA4 is the only official way to interact with Google Analytics starting Jul 1, 2023 after the decommissioning of Universal Analytics. Split offers a few different approaches for sending data to GA4 and receiving data from GA4.

Sending Split impressions to GA4

Split’s impression listener capability can be used to send impressions across to GA4 for tracking. This will allow you to send impressions from Split to GA. This capability works with UA and will continue to work with GA4.

Below you can see a standard event call using GA4’s gtag.js library

gtag('event', 'screen_view', {
  'app_name': 'myAppName',
  'screen_name': 'Home'
});

If you are using a gtag.js tracker and want to track feature flag impressions as events on your page, you can use an impressions listener to send events to GA every time the Split SDK's getTreatment method is called. Note that there is no impression deduplication at the listener level, so counts of events sent to GA is not necessarily identical to the count of impressions in Split's backend.

An impression listener for tracking GA4 events may look like the following. This assumes you are using Google tags (gtag.js) to track events into GA4 on the page and also uses a custom split_impression event in Google Analytics.

function logImpression(impressionData) {
  // 
  // Impression Data has the following fields:
  // {
  //   "impression":{
  //     "feature":"Demo_TL",
  //     "keyName":"key",
  //     "treatment":"off",
  //     "time":1681158925738,
  //     "label":"default rule",
  //     "changeNumber":1665436973467
  //   },
  //   "ip":false,
  //   "hostname":false,
  //   "sdkLanguageVersion":"javascript-10.20.0"
  // }
  gtag('event', 'split_impression', {
    'split_name': impressionData.impression.feature,
    'split_treatment': impressionData.impression.treatment,
    'split_label': impressionData.impression.label,
    'split_changeno': impressionData.impression.changeNumber
    // can add additional properties here as well
  });
}

You can enrich the listener with other data of interest to send back to Google Analytics as well, such as additional custom attributes that are not included in the Split impression. Additionally, if you're on a page not implemented with Google Analytics or a non-web platform, it's possible to use Google's GA4 Measurement Protocol which allows you to send events to GA4 using HTTP Requests. Refer to the following example of an impression listener that uses the measurement protocol API:

function logImpression(impressionData) {
  // 
  // Impression Data has the following fields:
  // {
  //   "impression":{
  //     "feature":"Demo_TL",
  //     "keyName":"key",
  //     "treatment":"off",
  //     "time":1681158925738,
  //     "label":"default rule",
  //     "changeNumber":1665436973467
  //   },
  //   "ip":false,
  //   "hostname":false,
  //   "sdkLanguageVersion":"javascript-10.20.0"
  // }
  // if these are defined elsewhere, they can be passed in here
  const measurement_id = `G-XXXXXXXXXX`;
  const api_secret = `<secret_value>`;

  fetch(`https://www.google-analytics.com/mp/collect?measurement_id=${measurementId}&api_secret=${apiSecret}`, {
    method: "POST",
    body: JSON.stringify({
      "client_id": impressionData.impression.keyName,
      "events": [{
        "name": "split_impression",
        "params": {
          'split_name': impressionData.impression.feature,
          'split_treatment': impressionData.impression.treatment,
          'split_label': impressionData.impression.label,
          'split_changeno': impressionData.impression.changeNumber,
        }
      }]
    })
  });
}

The example above is using the JavaScript fetch API to call the GA4 Measurement Protocol API. But all of Split's SDKs have impression listeners so all are capable of sending data to GA4 using this method. This can be done with backend and frontend SDKs.

Sending GA4 events to Split

There might be instances where you are already tracking events in GA4 and want to send them to Split without adding new event instrumentation for Split across all your apps.
There are two approaches to this; either use BigQuery as the data source, or wrap the track call.

Using BigQuery to send GA4 Events to Split

You can link Google Analytics data to BigQuery tables which can be used as a source to send data to Split.

To get started, follow Google's instructions on how to get GA4 events into BigQuery. Once GA4 data is in BigQuery, it can be queried and exported as events to Split using Split's events API. For example, this can be a job that runs on a schedule to ingest data into Split to allow for experimentation and further analysis with Split's metrics and metric dashboard.

The following is an example of a script that queries a BigQuery table and sends events to Split which uses the ga4_obfuscated_sample_ecommerce events table that all BigQuery users have access to. This example data helps you test and debug your pipeline to ensure that you are sending data correctly. Once you're satisfied with your data flow, adjust the query to handle the data that is appropriate to your needs. This can be a scheduled job that runs on a regular basis to push events from GA4 to BigQuery to Split.

from google.cloud import bigquery
import requests

client = bigquery.Client()

# Construct a SELECT statement that retrieves the records you want to process
# If you uncomment the where clause, this gets all new records within the last hour. 
# The event_timestamp restriction can be updated to whatever frequency you determine is proper for uploading events to Split. 
# The limit is there to quickly return results for testing. In production it should be removed
# For reference, 3600000000 microseconds is 1 hour.

# flattening the event hierarchy is done easiest in the query itself rather than python

query = """
SELECT
  event_timestamp, 
  user_id, 
  user_pseudo_id, 
  event_name, 
  device.category as device_category, 
  device.mobile_model_name as device_mobile_model_name
FROM `bigquery-public-data.ga4_obfuscated_sample_ecommerce.events_*`
--where event_timestamp > (UNIX_MICROS(current_timestamp()) - 3600000000)
limit 1000
"""

# Execute the query and retrieve the results
query_job = client.query(query)
results = query_job.result()

headers = {
    "content-type": "application/json",
    "Authorization": "Bearer API_KEY" # set your SDK API Key here
}
payload = []
# Process each record
for row in results:
    timestamp = row['event_timestamp']
    name = row['event_name']
    if(row['user_id'] is None):
        trafficType ='anonymous' 
        identifier = row['user_pseudo_id']
    else:
        trafficType ='user' 
        identifier = row['user_id']


    payload.append({
        'eventTypeId': name,
        'trafficTypeName': trafficType,
        'key': identifier,
        'timestamp': timestamp,
       # 'value': , # this is commented out but can be used if needed
        "properties" : {
            'device':row['device_category'],
            'device_mobile_model_name':row['device_mobile_model_name']
            # other properties can be passed in here too
        }
    })


max_size = 1000 # Split supports API calls of up to 100MB in size. Adjust this larger or smaller depending on your needs

# this breaks the events payload into batches for sending to Split
event_batches = [payload[i:i+max_size] for i in range(0, len(payload), max_size)]

for batch in event_batches:
    # Make the API call using requests library to pass events arrays
    response = requests.post('https://events.split.io/api/events/bulk', headers=headers, json=batch)


    # Handle the API response
    if response.status_code == 202:
        print(f"batch processed successfully")
    else:
        print(f"Error processing bulk records: {response.text}")

print('finished processing records')

An AWS Lambda function written in NodeJS can also be used, such as this one from Split community author David Martin: https://github.com/splitio/ga4toSplit_nodejs/

Wrapping the track call

With some flexibility in code style, another approach is to wrap the gtag function of Google Analytics to call Split's track method. This way you can continue to instrument your site with gtag while being able to use Split's powerful metric calculation and alerting abilities at the same time.

Sample Code:

var originalGtag = window.gtag;
window.gtag = function() {
  var args = Array.prototype.slice.call(arguments);
  originalGtag.apply(this, args);
  // Intercept only event commands
  if (args[0] === 'event') {
    var eventName = args[1];
    var eventParams = args[2];
    client.track('user', eventName, 0, eventParams)
    client.track('anonymous', eventName, 0, eventParams)
    //... add any other traffic types as needed
  }
};

Put this code after your instantiation of Split and Google Analytics so that it can take advantage of a Split Client and gtag. Alternatively, you can use the Split Events API to send events, removing the need for the Split SDK.

Google Universal Analytics (UA)

Language support

This integration works with the Universal Analytics (analytics.js) library, whether it's set up with the classic Google Analytics tag, a tag manager like Google Tag Manager, or Global Site Tags (gtag.js). It doesn't support the new Google Analytics 4 properties.

This integration is currently supported in Split's JavaScript client side SDK version 10.11.1 and above. Learn more about how to configure the integration in the Split's SDK documentation.

Requirements

This integration requires the Google analytics.js library to be running on the web. Learn more about analytics.js here.

Google Analytics to Split

Automatically capture Google Analytics hits as Split events. This removes the need to instrument Split's client.track() and leverage the event data already captured in Google Analytics.

To connect Split's SDK with the Google Analytics library, use Split's plugin available under the name 'splitTracker'. Note that Split's SDK does not detect any hits that were queued before the 'require' command, but by requiring plugins early in the process, the asynchronicity is automatically handled. Read more about using plugins.

<script>
  // The analytics initialization snippet;
  (function (i, s, o, g, r, a, m) {
    i['GoogleAnalyticsObject'] = r; i[r] = i[r] || function () {
      (i[r].q = i[r].q || []).push(arguments)
    }, i[r].l = 1 * new Date(); a = s.createElement(o),
      m = s.getElementsByTagName(o)[0]; a.async = 1; a.src = g; m.parentNode.insertBefore(a, m)
  })(window, document, 'script', 'https://www.google-analytics.com/analytics.js', 'ga');

  ga('create', 'UA-XXXXX-Y', 'auto');

  // BAD: This GA pageview hit would not be picked up by the integration.
  ga('send', 'pageview', '/index');

  // Require the 'splitTracker' plugin before sending any hits you want us to track. You can require it in as many trackers as you'd like. 
  ga('require', 'splitTracker'); // Require for use with the default tracker
  ga('myTracker.require', 'splitTracker'); // Require for use with a tracker named "myTracker"

  // GOOD: This GA pageview hit will be picked up by the integration.
  ga('send', 'pageview', '/index');
</script>

The constant type for this integration is GOOGLE_ANALYTICS_TO_SPLIT. By default all impressions and events are tracked for the key and trafficType provided in the configuration settings.

The default prefix "ga." is used for the event types. Event types are based on the hit data with some constraints to comply with the event type rules. For example, if tracking a pageview hit using ga('send', 'pageview', '/myPagePath'), the eventType is 'ga.pageview' in Split.

var factory = SplitFactory({
  core: {
    authorizationKey: 'YOUR_BROWSER_API_KEY',
    // key and traffic type for the resulting Split events will be taken from the factory config.
    key: 'CUSTOMER_ID',
    trafficType: 'user'
  },
  integrations: [{
    type: 'GOOGLE_ANALYTICS_TO_SPLIT'
  }]
});

const factory = SplitFactory({
  core: {
    authorizationKey: 'YOUR_BROWSER_API_KEY',
    // key and traffic type for the resulting Split events will be taken from the factory config.
    key: 'CUSTOMER_ID',
    trafficType: 'user'
  },
  integrations: [{
    type: 'GOOGLE_ANALYTICS_TO_SPLIT'
  } as SplitIO.IGoogleAnalyticsToSplitConfig]
});

Configurations

The integration has a number of knobs for configuring how the integration should work.

Filter

The filter is an optional predicate to define which hits are tracked. The signature of the function is below.

function filter(model: UniversalAnalytics.Model): boolean;

For example, to track hits of hitType event that are not of a certain category, write the following filter function shown below.

function customFilter(model: UniversalAnalytics.Model): boolean {
  return model.get('hitType') === 'event' && model.get(eventCategory) !== UNWANTED_CATEGORY;
}

If a hit is filtered, it won't reach the mapping step.

Mapper

Learn more about Split events and their structure in the Track section of the JavaScript SDK. The events basic structure is shown below.

type EventData = {
  eventTypeId: string;
  value?: number;
  properties?: Properties;
  trafficTypeName?: string;
  key?: string;
  timestamp?: number;
};

The default mapping gets the key and trafficType from the configuration of the factory or the identities as explained below. These will NOT be part of the object you'll receive.

The timestamp is generated as usual.

The eventType field in Split is mapped as shown below.

1. If the hitType equals 'event', the field eventAction is used.
2. If the hitType equals 'social' instead, the field socialAction is used.
3. If the hitType does not match the previous ones (like pageview), the actual hitType is used.

The value field in Split is mapped as shown below.

1. If the hitType equals 'event', the field eventValue is used.
2. If the hitType equals 'timing', the field timingValue is used.
3. If the hitType does not match the previous ones (like pageview), null is used as the default value (same as calling track without one).

The properties field in Split is mapped as shown below.

1. If the hitType equals 'pageview', the field page is tracked as a property.
2. If the hitType equals 'screenview', the field screenName is tracked as a property.
3. If the hitType equals 'event', the fields eventCategory and eventLabel is tracked as properties.
4. If the hitType equals 'social', the fields socialNetwork and socialTarget is tracked as properties.
5. If the hitType equals 'timing', the fields timingCategory, timingVar and timingLabel is tracked as properties.
6. If the hitType equals 'exception', the fields exDescription and exFatal is tracked as properties.

Any other fields are not tracked as event properties by default. Define a custom mapper to track additional fields and update how fields should be mapped. The signature of the mapper function is shown below:

function mapper(model: UnrsalAnalytics.Model, defaultMapping: SplitIO.EventData): SplitIO.EventData;

For example, to track the user location as an event property or conditionally add a value to the event, modify the received default mapped event and return it as shown below:

function mapper(model: UnrsalAnalytics.Model, defaultMapping: SplitIO.EventData): SplitIO.EventData {
  // Of course you can apply any rules you'd like as long as you return a valid Split event from the function.
  // The received object is a copy, so it's safe to modify and return afterwards avoiding the need for always defining a new object.
  defaultMapping.properties.location = userLocation;

  if (defaultMapping.eventTypeId.includes('playVideo')) defaultMapping.value = videoInstance.playedTime;

  return defaultMapping;
};

Identities

Use this option if the trafficType is not defined in the factory or to track the same hits for multiple traffic types. Each identity only defines two properties as shown below:

type Identity = {
  key: string;
  trafficType: string;
};

For example, track the same hits as events at the user level and at the account level as shown below:

const userId = 'CUSTOMER_ID';
const accountId = 'ACCOUNT_ID';

const factory = SplitFactory({
  core: {
    authorizationKey: 'YOUR_BROWSER_API_KEY',
    // No need to define a traffic type at least for the integration, as it's provided via the identities array. 
    key: userId
  },
  integrations: [{
    type: 'GOOGLE_ANALYTICS_TO_SPLIT',
    identities: [{
      key: userId, trafficType: 'user'
    }, {
      key: accountId, trafficType: 'account'
    }]
  } as SplitIO.IGoogleAnalyticsToSplitConfig]
});

It is important to note that the identity assignment is done AFTER the mapping. By defining the key and trafficType on the mapper, the identities provided is ignored and events won't be generated for multiple identities.

Full interface definition

See the full interface of the GOOGLE_ANALYTICS_TO_SPLIT integration object defined below:

interface IGoogleAnalyticsToSplitConfig {
  /**
    * Type constant.
    */
  type: 'GOOGLE_ANALYTICS_TO_SPLIT',
  /**
    * Optional flag to filter GA hits from being tracked as Split events.
    * @default true
    */
  hits?: boolean,
  /**
    * Optional predicate used to define a custom filter for tracking GA hits as Split events.
    */
  filter?: (model: UniversalAnalytics.Model) => boolean,
  /**
    * Optional function useful when you need to modify the Split event before tracking it.
    * This function is invoked with two arguments:
    * 1. the GA model object representing the hit.
    * 2. the default format of the mapped Split event instance.
    * The return value must be a Split event, that can be the second argument or a new object.
    */
  mapper?: (model: UniversalAnalytics.Model, defaultMapping: SplitIO.EventData) => SplitIO.EventData,
  /**
    * Optional prefix for EventTypeId, to prevent any kind of data collision between events.
    * @default 'ga'
    */
  prefix?: string,
  /**
    * List of Split identities (key & traffic type pairs) used to track events.
    * If not provided, events are sent using the key and traffic type provided at SDK config
    */
  identities?: Identity[]
}

Set up with Google Tag Manager and gtag.js

When you use Google Tag Manager (GTM) or Global Site Tag (gtag.js) to set up your Universal Analytics configuration, trackers are created with dynamic names.

To learn more about how to configure this integration in this scenario, refer to the Google Tag Manager guide.

Split to Google Analytics

Automatically capture Split impressions and events as hits into Google Analytics' dashboard. This removes the need to manually connect Split to Google Analytics.

The constant type for this integration is SPLIT_TO_GOOGLE_ANALYTICS and by default, all impressions and events are tracked using the hitType event but with two different eventCategory values, 'split-impression' and 'split-event'.

var factory = SplitFactory({
  core: {
    authorizationKey: 'YOUR_BROWSER_API_KEY',
    key: 'CUSTOMER_ID'
  },
  integrations: [{
    type: 'SPLIT_TO_GOOGLE_ANALYTICS'
  }]
});

const factory = SplitFactory({
  core: {
    authorizationKey: 'YOUR_BROWSER_API_KEY',
    key: 'CUSTOMER_ID'
  },
  integrations: [{
    type: 'SPLIT_TO_GOOGLE_ANALYTICS'
  } as SplitIO.ISplitToGoogleAnalyticsConfig]
});

Configurations

The integration has a number of knobs for configuring how the integration should work.

Filter

The filter is an optional predicate used to define which impressions or events are tracked. The signature of the function is shown below:

function filter(data: SplitIO.IntegrationData): boolean;

IntegrationData and the payload options are shown below.

  type IntegrationData = { type: 'IMPRESSION', payload: SplitIO.ImpressionData } | { type: 'EVENT', payload: SplitIO.EventData };

  type ImpressionData = {
    impression: {
      feature: string,
      keyName: string,
      treatment: string,
      time: number,
      bucketingKey?: string,
      label: string,
      changeNumber: number
    },
    // these are the attributes you provided on the getTreatment call, in case you want to send any to Google Analytics tied to the impression.
    attributes?: SplitIO.Attributes,
    ip: string,
    hostname: string,
    sdkLanguageVersion: string
  };

  type EventData = {
    eventTypeId: string;
    value?: number;
    properties?: Properties;
    trafficTypeName?: string;
    key?: string;
    timestamp?: number;
  };

For example, to only track impressions for a particular feature flag along with all the events, write the following filter function:

function customFilter(data: SplitIO.IntegrationData): boolean {
  if (data.type !== 'IMPRESSION') return true;

  const evaluatedFeature = data.payload.impression.feature;

  return evaluatedFeature === 'SPLIT_TO_TRACK_EVALUATIONS_AS_HITS';
}

If a hit is filtered, it won't reach the mapping step.

Mapper

Learn more about Google Analytics and which rules are neccessary to comply with in the guide sending data to Google Analytics. For quick reference, all hits MUST have a hitType. Split's SDK validates this automatically.

The default mapping for impressions would generate hits as shown below:

// Based on the data object you'll receive on the mapper:
{
  hitType: 'event',
  eventCategory: 'split-impression',
  eventAction: 'Evaluate ' + data.payload.impression.feature,
  eventLabel: 'Treatment: ' + data.payload.impression.treatment + '. Targeting rule ' + data.payload.impression.label,
  nonInteraction: true
}

// For example, the generated object for a Split called my_feature could be:

{
  hitType: 'event',
  eventCategory: 'split-impression',
  eventAction: 'Evaluate my_feature',
  eventLabel: 'Treatment: on. Targeting rule: default rule.',
  nonInteraction: true
}

The default mapping for events would generate hits as shown below:

// Based on the data object you'll receive on the mapper:
{
  hitType: 'event',
  eventCategory: 'split-event',
  eventAction: payload.eventTypeId,
  eventValue: payload.value,
  nonInteraction: true
}

// For example, the generated object for an event generated with client.track('user', 'cart_checkout', 2000)

{
  hitType: 'event',
  eventCategory: 'split-event',
  eventAction: 'cart_checkout',
  eventValue: 2000,
  nonInteraction: true
}

Split doesn't automatically add any extra fields or dimensions to the data. Easily define a custom mapper and change or add values. The signature of the mapper function is shown below:

function mapper(data: SplitIO.IntegrationData, defaultMapping: UniversalAnalytics.FieldsObject): UniversalAnalytics.FieldsObject;

For example, add a dimension to a Split Event derived hits based on the trafficType and keep impressions derived hits as they are:

function mapper(data: SplitIO.IntegrationData, defaultMapping: UniversalAnalytics.FieldsObject): UniversalAnalytics.FieldsObject {
  // Of course you can apply any rules you'd like as long as you return a valid FieldsObject from the function.
  // The received object is a copy, so it's safe to modify and return afterwards avoiding the need for always defining a new object.

  if (data.type === 'EVENT') {
    defaultMapping.dimension1 = data.payload.trafficType;
  }

  return defaultMapping;
}

Trackers

If using named trackers, provide the names for the ones you want to connect with the integration. By default, Split hooks to the default tracker ('').

For example, to only send event data through the "marketing" tracker, write the below"

const factory = SplitFactory({
  core: {
    authorizationKey: 'YOUR_BROWSER_API_KEY',
    key: 'CUSTOMER_ID'
  },
  integrations: [{
    type: 'SPLIT_TO_GOOGLE_ANALYTICS',
    trackers: ['marketing'],
    impressions: false
  }]
});

See the full interface of the SPLIT_TO_GOOGLE_ANALYTICS integration object defined below:

interface ISplitToGoogleAnalyticsConfig {
  /**
  * Type constant.
  */
  type: 'SPLIT_TO_GOOGLE_ANALYTICS',
  /**
    * Optional flag to filter Split impressions from being tracked as GA hits.
    * @default true
    */
  impressions?: boolean,
  /**
    * Optional flag to filter Split events from being tracked as GA hits.
    * @default true
    */
  events?: boolean,
  /**
    * Optional predicate used to define a custom filter for tracking Split data (events and impressions) as GA hits.
   */
  filter?: (data: SplitIO.IntegrationData) => boolean,
  /**
    * Optional function useful when you need to modify the GA hit before sending it.
    * This function is invoked with two arguments:
    * 1. the input data (Split event or impression).
    * 2. the default format of the mapped FieldsObject instance (GA hit).
    * The return value must be a FieldsObject, that can be the second argument or a new object.
    */
  mapper?: (data: SplitIO.IntegrationData, defaultMapping: UniversalAnalytics.FieldsObject) => UniversalAnalytics.FieldsObject,
  /**
    * List of tracker names to send the hit. An empty string represents the default tracker.
    * If not provided, hits are only sent to default tracker.
    */
  trackerNames?: string[],
}