Events

To power your analytics and experimentation, you need to send a set of events to Split. This allows you to measure customer behavior and customer experience in your application by sending events such as clicks, views, checkout events, page load time, or any other event that measures behavior, experience, or engineering performance. Event data can be sent to Split in one of three ways:

• Call Split's SDK track method
• Post a JSON body to Split's events API
• Split integrations with Segment, mParticle, Sentry, Amazon S3, or Google Analytics

The API and integration routes allow you to ingest event data from existing sources (i.e., take advantage of telemetry from existing instrumentation or analytics). Use the track method if you want to explicitly add instrumentation code to your application to record events using Split’s SDK. Events can then be aggregated to produce metrics. Refer to our Creating a metric guide for more information on metrics.

Note: Split’s customer success organization’s Integration Advisors are here to help and assist you with standing up your events integration pipelines. We are committed to ensuring your success. Contact your Customer Success Manager to set up a meeting and explore options.

The API and integration routes allow you to ingest event data from existing sources (i.e. take advantage of telemetry from existing instrumentation or analytics). Use the track method if you want to explicitly add instrumentation code to your application to record events.

Events can then be aggregated to produce metrics. Learn more about creating a metric in Split.

Event fields

Each event contains the following fields:

Using the SDK track method

Use the track method to record any actions your customers perform. Each action is known as an event and corresponds to an event type. Calling track through one of our SDKs is the first step to getting experimentation data into Split and allows you to measure the impact of your feature flags on your users’ actions and metrics. In the following examples, you can see that the .track() method can take up to five arguments. The proper data type and syntax for each are the following:

• key: The key variable used in the getTreatment call and firing this track event. The expected data type is String.
• TRAFFIC_TYPE: The traffic type of the key in the track call. The expected data type is String. You can only pass values that match the names of traffic types that you have defined in your instance of Split.
• EVENT_TYPE: The event type that this event should correspond to. The expected data type is String. Full requirements on this argument are:
  • Contains 63 characters or fewer.
  • Starts with a letter or number.
  • Contains only letters, numbers, hyphen, underscore, or period.
  • This is the regular expression we use to validate the value: [a-zA-Z0-9][-_\.a-zA-Z0-9]{0,62}
• VALUE: (Optional) The value to be used in creating the metric. This field can be sent in as null or 0 if you intend to purely use the count function when creating a metric. The expected data type is Integer or Float.
• PROPERTIES: (Optional). A Map of key-value pairs that can be used to filter your metrics or used for the value in sum and average metrics. Refer to event property capture for more information. Split currently supports three types of properties: strings, numbers, and booleans.

The following is an example in Java.

Note: Other SDK languages each have specific syntax that need to be followed on their own help pages. Refer to our SDK section of our help documentation for more information about using the track call for your selected SDK.

// If you would like to send an event without a value 
boolean trackEvent = client.track("key", "TRAFFIC_TYPE", "EVENT_TYPE");
// Example
boolean trackEvent = client.track("john@doe.com", "user", "page_load_time");

// If you would like to associate a value to an event
boolean trackEvent = client.track("key", "TRAFFIC_TYPE", "EVENT_TYPE", VALUE);
// Example  
boolean trackEvent = client.track("john@doe.com", "user", "page_load_time", 83.334);

// If you would like to associate a value and properties to an event
boolean trackEvent = client.track("key", "TRAFFIC_TYPE", "EVENT_TYPE", VALUE, {PROPERTIES});
// Example  
HashMap<String, Object> properties = new HashMap<>();
properties.put("package", "premium");
properties.put("admin", true);
properties.put("discount", 50);

boolean trackEvent = client.track("john@doe.com", "user", "page_load_time", 83.334, properties);

Considerations

This method generally is best for two use cases:

• You are new to event tracking and experimentation in general. If Split is the first time you are tracking events, then using Split's track method is a great way to start.
• You already have one or more tools that do tracking and have a wrapped function that calls all of your trackers. In this case, it would be straightforward just to add Split's track method to that function.

When using the track method we strongly recommend wrapping the function. If you are in the first use case and early on your experimentation journey, it is important to ensure a quality code architecture and as such wrapping the track call allows further extensibility to other applications that you may be tracking with later on.

Level of effort using the track method

The following explains the level of effort you can expect when using this method to send events to Split.

Using the track method requires that you call this function for each of the events you want to track. This would include multiple traffic types and every event that you may want to use to measure the impact of a feature flag treatment. If you are already tracking events using other systems, you can include Split's track method in a wrapped call with your other trackers.

If you are already using a system for tracking events and Split has an events integration with that system, Split would recommend that approach over using the track method.

Using events APIs

You can post a JSON body to Split's events API to ingest event data from existing sources. You can see the schema for sending an event in the following:

[{
  "eventTypeId": String, 
  "trafficTypeName": String, 
  "key": String, 
  "timestamp": Number, 
  "value": Number,
  "properties":{String: Any,String: Any, etc.}
}]

Considerations

Using the events API makes sense when you have a stream of events from some other system where you are tracking events that you can tap in to.

If you are already tracking user events with some other system and it offers some kind of webhook, one common approach is to use a serverless function like AWS lambda to transform events from that webhook into Split’s format and send those events across to Split.

Another possible use case would be the scenario where you have a system that cannot or will not be running the Split SDK but still needs to track events. The advantage of using the events API over the SDK is that almost every single programming language has the ability to make HTTP API calls. So any internet connected application can send events to Split with this method.

There is no rate limit on the events API. It can handle any volume of load of events. However, it is recommended to keep individual payload sizes under 1 megabyte.

Level of effort using events API

The level of effort for implementing the events API is low. It is a straightforward HTTP API call with a JSON formatted body and authenticated with a Bearer auth token. If the events data can be tapped into from some sort of events stream, or some application that is already tracking events and formatted into Split’s events format, it can be sent across to Split.

Using integrations to send events

You can use Segment, mParticle, Sentry, Amazon S3, or Google Analytics (GA) to ingest event data from existing sources. Using these integrations allows you to avoid explicitly sending events to Split and instead send events to these systems that forwards them on to Split.

Considerations

If you’re already tracking events using Google Analytics, mParticle, Segment, or Sentry, Split strongly recommends using these integrations for ease of ingesting events. One thing to be aware of is that these integrations typically send all events from the source system to Split. Specifically the Sentry, Segment, and mParticle integrations do not have filtering to only send some events. The GA integration can be configured with filters. The Amazon S3 integration requires filtering when the file is generated, if events were to be excluded.

The Amazon S3 integration is best used when event collection is already centralized and AWS infrastructure is available for use. Then the events can be piped directly to Split with this integration.

Level of effort using integrations

The Sentry, Segment, and mParticle integrations are similar in that there is no engineering effort required to load events captured within these systems. There is configuration that has to happen within Split and within the third-party application to map the events and traffic types to what they will be in Split. For more information, view the specific pages of each of these integrations in the help center.

The Google Analytics integration is for the browser only and requires the SDK to be instantiated on any page that you want to use it on. Once instantiated in code, it allows sending GA hits to Split automatically without needing to track individual events. This can also be used in concert with our Google Tag Manager (GTM) helper script that adds Split’s tracker automatically to any GTM trackers.

The Amazon S3 integration requires infrastructure work of creating a new S3 bucket and setting up files with the proper naming convention, data schema, file format, and compression algorithm. The user doing this setup needs rights to set the bucket policy as well.

Event types

You can find all the event types that have been received by Split in the last 150 days in the Admin Settings under the event types category to the left. Here you can see all the event types that have been received along with additional information to help understand if you have set them up correctly. 

When you import events successfully, Split automatically captures the event types for use in creating metric definitions. You will see those events in the metric builder of the Metric definition page.

An event type does not need to already exist in order to create a metric definition. You can enter any text for the event type in the metric builder and use that to create the metric definition. These manually entered event types however, will not appear in the Event types table or in the metric builder until an event with that event type is received by Split.

Event properties

Properties provide additional context around the events your customers generate. Event properties are attributes of a particular event and reflect the state and additional metadata at which the event was generated. For the event checkout.click, an event property could be 'category' which denotes the type of person checking out. A customer could generate the checkout.click event by being a 'guest' or 'user'. The event property 'guest' provides more information about the specific event. Split supports capturing event specific properties and exposes these properties within Split’s metric definition builder. With event properties, you can create more granular and flexible metrics.

Below is a sample event checkout.click showing the event properties with Split’s common fields removed. We use these event properties in the examples below.

JSON

{
 "eventTypeId": "checkout.click",
 "environmentName": "Production",
 "trafficTypeName": "user",
 "timestamp": 1557936519990,
 "value": 0,
 "source": "Segment",
 "foreignId": "ajs-85cb03f2f34af1426d9a2128146ab832",
 "properties": {
   "category": "guest",
   "packaging_fees": "25.08",
   "discount_saving": "4",
   "label": "necklace",
   "login_id": "null",
   "page_version":"unit_page",
   "total_tax": "32.00",
   "total_cost": "945.69",
   "type": "button",
   "package": "luxury",
   "visitor_id": "null"
 }
}

You can use event properties as:

• An event value for sum and average value metrics
• Filters for your metric definition

You can view the event properties being sent for a given event by using the Live tail functionality in Data hub.

Using properties as event values

Split supports a range of different types of metric functions, including the sum of event values and the average of event values.

When selecting one of these functions, the default value for the event type will be selected. If there is a particular value in the properties of the event you would like to use in the metric definition, you can select which property you want to use as the value field. Note that the properties available are based on the properties being passed with the event type that is associated with the metric's definition.  

A property used as a value field must be numeric (e.g., a float or an integer). If you select a property that has no numeric values associated with it and returns a null value, this is converted into zero (0) at time of calculation.

Refer to the Events guide for more information about how to send events and event values.

For example, below is the raw event shown above and the properties passed with the event. While all properties display in the value field, not all of the properties are valid to be used in metric value calculations and if you select a non-numeric property, it is treated as the value 0.

JSON

{
 "eventTypeId": "checkout.click",
 "environmentName": "Production",
 "trafficTypeName": "user",
 "timestamp": 1557936519990,
 "value": 0,
 "source": "Segment",
 "foreignId": "ajs-85cb03f2f34af1426d9a2128146ab832",
 "properties": {
   "category": "guest",
   "packaging_fees": "25.08",
   "discount_saving": "4",
   "label": "necklace",
   "login_id": "null",
   "page_version":"unit_page",
   "total_tax": "32.00",
   "total_cost": "945.69",
   "type": "button",
   "package": "luxury",
   "visitor_id": "null"
 }
}

Using properties as filters

Apply a property filter to the event you are measuring

Split supports the ability to use event properties as property filters for your metric definition to condition the event by an event property. You can use up to 20 event properties to filter your event by. Using multiple event properties are calculated as having an and relationship between them.

Event property limits

Split supports the capturing of 300 properties per event type, and each property has a 256 character limit.

FAQs

How can I see the event properties for a particular event?

You can access your raw events and the properties being passed to Split by capturing them in Data hub's Live tail function and look to see what properties exist.