Impression data

Requires SDK compatibility.

Unleash can provide you with impression data about the flags in your application. Impression data contains information about a specific feature flag activation check: The client SDK will emit an impression event when it calls isEnabled or getVariant. Some front-end SDKs emit impression events only when a flag is enabled.

Impression data was designed to make it easier for you to collect analytics data, perform A/B tests, and enrich experiments in your applications. It contains information about the feature flag and the related Unleash Context.

Impression data is opt-in on a per-flag basis. Unleash will not emit impression events for flags not marked as such. Once you’ve turned impression data on for a flag, you can start listening for impression events in your client SDK.

Impression event data

There’s two types of impression events you can listen for:

• isEnabled events
• getVariant events

The getVariant event contains all the information found in an isEnabled event in addition to extra data that’s only relevant to getVariant calls.

This table describes all the properties on the impression events:

Example isEnabled event

1
{
2
  eventType: 'isEnabled',
3
  eventId: '84b41a43-5ba0-47d8-b21f-a60a319607b0',
4
  context: {
5
    sessionId: 54085233,
6
    appName: 'my-webapp',
7
    environment: 'default'
8
  },
9
  enabled: true,
10
  featureName: 'my-feature-flag',
11
}

Example getVariant event

1
{
2
  eventType: 'getVariant',
3
  eventId: '84b41a43-5ba0-47d8-b21f-a60a319607b0',
4
  context: {
5
    sessionId: 54085233,
6
    appName: 'my-webapp',
7
    environment: 'default'
8
  },
9
  enabled: true,
10
  featureName: 'my-feature-flag',
11
  variant: 'variantA'
12
}

Enabling impression data

Impression data is strictly an opt-in feature and must be enabled on a per-flag basis. You can enable and disable it both when you create a flag and when you edit a flag.

You can enable impression data via the impression data flag in the admin UI’s flag creation form. You can also go via the API, using the impressionData option.

1
curl -X POST https://app.unleash-instance.example.com/api/admin/projects/projectId/features \
2
     -H "Authorization: <apiKey>" \
3
     -H "Content-Type: application/json" \
4
     -d '{
5
  "name": "disable-comments"
6
}'

For more detailed instructions, see the section on enabling impression data in the how-to guide for capturing impression data.

Example setup

The exact setup will vary depending on your client SDK. The below example configures the Unleash Proxy client to listen for impression events and log them to the console. If “my-feature-flag” is configured to emit impression data, then it will trigger an impression event as soon as Unleash is ready.

1
const unleash = new UnleashClient({
2
  url: 'https://eu.unleash-hosted.com/hosted/proxy',
3
  clientKey: 'your-proxy-key',
4
  appName: 'my-webapp',
5
});
6
7
unleash.start();
8
9
unleash.on('ready', () => {
10
  unleash.isEnabled('my-feature-flag');
11
});
12
13
unleash.on('impression', (event) => {
14
  // Capture the event here and pass it to internal data lake or analytics provider
15
  console.log(event);
16
});

Understand why a flag was enabled

Unleash SDKs do not expose an evaluation reason API: isEnabled and getVariant return the result of the evaluation, but not which strategy or constraint produced it. If you need to understand why a flag evaluated the way it did, you have the following options:

• Use the Playground to simulate a context and see detailed evaluation results, including which strategies and constraints matched. This is the best tool for debugging targeting rules.
• Use impression data, as described on this page, to track that a flag was evaluated, with which context, and with what result.