• HOME
  • INTEGRATIONS
  • SDKS
  • GUIDES
  • API DOCS
No results for ""
EXPAND ALL

EDIT ON GITHUB

Sending custom events

Read time: 7 minutes
Last edited: Jul 28, 2021

Overview

This topic explains how to send custom events using the track feature in your SDK. The track feature is available on both client-side and server-side SDKs.

Tracking events

The track feature lets you record actions your users take in your application as events. You can connect these events to metrics in A/B tests or experiments in the LaunchDarkly dashboard.

Details about each SDK's configuration are available in the SDK-specific sections below.

  • Client-side SDKs
  • Server-side SDKs

Client-side SDKs

This feature is available in the following client-side SDKs:

Android

The track method lets you record actions your users take in your application. You can also attach custom JSON data to your event by passing an extra JsonElement parameter to track.

Here's how:

1ldClient.track("your-goal-key", data);

To learn more, read track.

You can also attach custom data to your event by calling TrackData or TrackMetric.

C/C++ (client-side)

The track method allows you to record custom events in your application with LaunchDarkly:

1LDClientTrack(client, "YOUR_EVENT_KEY");

To learn more, read LDClientTrack.

You can also attach custom data to your event by calling LDClientTrackData or LDClientTrackMetric.

Electron

Evaluating flags, either with variation() or with allFlags(), produces analytics events which you can observe on your LaunchDarkly Debugger page. The initial user you specify in the client constructor, as well as any user you specify with identify(), produces an analytics event which is how LaunchDarkly receives your user data.

You can also explicitly send an event with any data you like using the track function:

1client.track('my-custom-event-key', { customProperty: someValue });

You can completely disable event sending by setting sendEvents to false in the client options, but be aware that this means you will not have user data on your LaunchDarkly dashboard.

Flutter

The track method lets you record actions your users take in your you do application. You can have also attach custom JSON data to your event by passing an extra LDValue parameter to track.

Here's how:

1await LDClient.track('your-goal-key', data: LDValue.objectBuilder().addBool("clicked-button", true).build());

You can also attach custom data to your event using the track method with optional parameters.

iOS

In the iOS SDK, track is a custom event added to the LDClient event store. A client app can set a tracking event to allow client customized data analysis. After an app has called track, the app cannot remove the event from the event store. LDClient periodically transmits events to LaunchDarkly based on the frequency set in LDConfig.eventFlushInterval. The LDClient must be started and online.

After the SDK's event store is full, the SDK discards new events until the event store is cleared when it reports events to LaunchDarkly. Configure the size of the event store using LDConfig.eventCapacity. The first parameter, key, is the key for the event. The SDK does nothing with the key, which can be any string the client app sends. The second parameter, data, is the data for the event. The data paraemeter is optional. The SDK does nothing with the data, which can be any valid JSON item the client app sends. If the data is not a valid JSON item, the method throws an LDInvalidArgumentError.

Optionally, you can add a metricValue parameter of type Double to track in Swift or as a required paramter to the overloaded track method in Objective-C.

1try {
2 let data = ["some-custom-key": "some-custom-value", "another-custom-key": 7] as [String: Any]
3 try LDClient.get()!.track(key: "MY_TRACK_EVENT_NAME", data: data)
4} catch is LDInvalidArgumentError {
5 // Do something with the error
6} catch {}

To learn how to attach custom data to your event with optional parameters, read Events.

JavaScript

You can record custom events using the track function. In LaunchDarkly, you can connect these events to metrics in experiments. To learn more, read Experimentation.

Call track with the event name to record custom conversion metrics.

The second argument is optional. It assists with observational analytics for Data Export destinations. With Data Export, the second argument gives additional context without saving the data to the LaunchDarkly user.

To call track:

1ldclient.track("your-event-name", { customProperty: someValue });

To learn how to attach custom data to your event with optional parameters, read track.

Tracking click and pageview events in JavaScript



If you've defined click or pageview goals in LaunchDarkly, they'll be sent automatically once the client has been initialized. You do not have to do anything else with the client to send click or pageview goals.

To learn more about click and pageview goals, read Experimentation.

Single-page apps

The SDK automatically handles URL changes made by the HTML5 history API or by changing the URL hash fragment, and will trigger pageview and click events correctly.

Analytics in JavaScript


Evaluating flags, either with variation() or with allFlags(), produces analytics events which you can observe on your LaunchDarkly Debugger page. The initial user you specify in the client constructor, as well as any user you specify with identify(), produces an analytics event which is how LaunchDarkly receives your user data.

You can also explicitly send an event with any data you like using the track function. The second argument is optional. For example:

1ldclient.track("your-event-name", { customProperty: someValue });

If you define click or pageview metrics in LaunchDarkly, they are sent automatically once the client has been initialized. You do not have to do anything else with the client to send click or pageview goals. The SDK will generate pageview events correctly regardless of how the URL is changed, such as by the HTML5 history API, by changing the URL hash fragment, etc.

You can completely disable event sending by setting sendEvents to false in the client options, but this means you will not have user data on your LaunchDarkly dashboard.

Do Not Track and ad blocking software

The JavaScript SDK respects the Do Not Track events header. If an end-user has Do Not Track enabled in their browser, the SDK does not send analytics events for flag evaluations or goals to events.launchdarkly.com. In addition, ad blocking software may block analytics events from being sent. This does not impact feature flag evaluations.

Node.js (client-side)

The track method lets you record actions your users take, giving them any event name you want. This lets you record events that take place client-side. The current user data automatically accompany the event.

Here's an example:

1ldClient.track("something-happened");
2
3ldClient.track("something-happened-with-custom-data", { someData: 2 });

To learn how to attach custom data to your event with optional parameters, read track.

React Native

The track method lets you record actions your users take in your app. You can also attach custom JSON data to your event by passing an extra parameter to track.

AvailabilitySince v2.1.0

Optionally, you can add a metricValue parameter to the track method if you are using the latest version of Experimentation.

Here's how:

1client.track('MY_GOAL_FLAG_KEY', false);
2client.track('MY_GOAL_FLAG_KEY_WITH_DATA', {'some_data':'value'});

To learn how to attach custom data to your event with optional parameters, read track.

Roku

The track method lets you record custom events in your application with LaunchDarkly.

Here's how:

1REM without optional data
2launchDarkly.track("YOUR_EVENT_KEY")
3
4REM with optional data
5launchDarkly.track("YOUR_EVENT_KEY", {"customField": 123})
6
7REM with optional numeric metric
8launchDarkly.track("YOUR_EVENT_KEY", invalid, 52.3)

Xamarin

The track method lets you record actions your users take on your site. This lets you record events that take place on your server.

Here's how:

1ldClient.Track("your-goal-key");

You can also attach custom data to your event by passing an extra parameter to Track, using the LdValue class to represent any value that can be encoded in JSON. To learn how, read LdClient.Track.

Server-side SDKs

This feature is available in the following server-side SDKs:

.NET

The Track method lets you record actions users take on your site. This lets you record events that take place on your server. In LaunchDarkly, you can tie these events to goals in A/B tests.

Here's an example:

1ldClient.Track("your-goal-key", user);

You can also attach custom data to your event by passing an extra parameter to Track. To do this, use the LdValue type, which can contain any kind of data supported by JSON. You can also pass another parameter for a custom metric value.

Apex

The track method lets you record actions your users take in your you do application. You can also attach custom JSON data to your event by passing an LDValue parameter to track, or a custom metric value by passing a Double parameter.

Here's how:

1client.track(user, 'your-goal-key', 52.3, LDValue.of('my value'));

To learn how to attach custom data to your event with extra parameters, read Other methods.

C/C++ (server-side)

The LDClientTrack function lets you record actions your users take on your site. This lets you record events that take place on your server.

Here's how:

1LDClientTrack(client, "your-goal-key", user, NULL);

To learn more, read LDClientTrack().

You can also attach custom data to your event by calling LDClientTrackMetric().

Erlang

The track function lets you record actions your users take on your site. This lets you record events that take place on your server.

Here's how:

ldclient:track(<<"YOUR-METRIC-KEY">>, #{key => <<"aa0ceb">>}, #{data => <<"example">>})

To learn more, read track.

You can also attach a JSON object containing arbitrary data to your event, or a custom metric value. To learn how, read track_metric.

Go

The Track methods allow you to record actions your users take on your site. This lets you record events that take place on your server.

In this example, we use TrackEvent to send an event called completed-purchase. This event can correspond to a metric with the same key.

Here's how:

1ldClient.TrackEvent("completed-purchase", user)

You can also attach custom data to your event by calling TrackData, which takes an extra parameter. Or, if you are using experimentation, you can specify a numeric metric with TrackMetric.

Haskell

The track function lets you record actions your users take on your site. This lets you record events that take place on your server.

Here's how:

1track client user "your-metric-key" Nothing Nothing

You can also attach a JSON object containing arbitrary data to your event, or a custom metric value. To learn how, read track.

Java

The track method lets you record actions your users take on your site. This lets you record events that take place on your server.

Here's how:

1ldClient.track("your-goal-key", user);

You can also attach custom JSON data to your event with an alternate version of track, trackData. You can set the data to any value that can be represented in JSON. To learn more, read LDValue.

If you are using experimentation, you can specify a numeric metric with trackMetric.

Lua

The track method lets you record actions your users take. This lets you record events that take place on your server.

Here's how:

1client:track("your-goal-key", user);

You can also attach an object containing arbitrary data to your event. To learn how, read track.

Node.js (server-side)

The track method lets you record actions your users take on your site. This lets you record events that take place on your server.

Here's how:

1ldClient.track("your-goal-key", user);

You can also attach custom data to your event with optional parameters. To learn how, read track.

PHP

The track method lets you record actions your users take on your site. This lets you record events that take place on your server.

Here's how:

1$client->track("your-goal-key", user);

You can also attach custom data, including anything that can be marshaled to JSON, to your event by passing an extra parameter to track. To learn how, read track().

Python

The track method lets you record actions your users take on your site. This lets you record events that take place on your server.

Here's how:

1ldclient.get().track("your-goal-key", user)

You can also attach custom data to your event with optional parameters. To learn how, read track.

Ruby

The track method lets you record actions your users take on your site. This lets you record events that take place on your server.

Here's how:

1ld_client.track("your-goal-key", user)

You can also attach an extra hash containing arbitrary data to your event. To learn how, read track.