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.

Visualize in Split

Event types can be found in Admin settings.

Delete an unneeded event type or view live tail to the right of an event type to view the raw events. Refer to the live tail guide for more information about this functionality. When you import events successfully, you also see those events in the Metric definition page, which allows you to create metrics to measure the impact of your features.

You can update an event type's name and description using the API.

Next steps

For more information about how events are associated with impressions as part of metrics, refer to our Attribution and exclusion guide.

For more information about metrics in Split, refer to the following. These are tools that require events to get the full value out of Split:

• • All about Split metrics
  • Experimentation essentials 101
  • Metrics guide