diff --git a/website/docs/advanced/impression-data.md b/website/docs/advanced/impression-data.md new file mode 100644 index 00000000000..c4f0ea8106f --- /dev/null +++ b/website/docs/advanced/impression-data.md @@ -0,0 +1,104 @@ +--- +title: Impression data +--- + +:::info Availability +The impression data feature was introduced in **Unleash 4.7**. Listening for events requires [an SDK that supports impression data events](../sdks/index.md#server-side-sdk-compatibility-table). Currently, it's only supported in the [Unleash Proxy client](../sdks/proxy-javascript.md) and [React Proxy client](../sdks/proxy-react.md). +::: + +Unleash can provide you with **impression data** about the toggles in your application. Impression data contains information about a specific feature toggle activation check: The client SDK will emit an **impression event** whenever it calls `isEnabled` or `getVariant`. + +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 toggle and the related [Unleash Context](../user_guide/unleash-context.md). + +Impression data is **opt-in on a per-toggle basis**. Unleash will not emit impression events for toggles not marked as such. Once you've turned impression data on for a toggle, 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](#example-isenabled) +- [`getVariant` events](#example-getvariant) + +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: + +| Property name | Description | Event type | +|---------------|--------------------------------------------------------------------------------------|--------------------------| +| `eventType` | The type of the event: `isEnabled` or `getVariant` | All | +| `eventId` | A globally unique id (GUID) assigned to this event. | All | +| `context` | A representation of the current [Unleash Context](../user_guide/unleash-context.md). | All | +| `enabled` | Whether the toggle was enabled or not at when the client made the request. | All | +| `featureName` | The name of the feature toggle. | All | +| `variant` | The name of the active variant | `getVariant` events only | + +### Example `isEnabled` event {#example-isenabled} + +```js +{ + eventType: 'isEnabled', + eventId: '84b41a43-5ba0-47d8-b21f-a60a319607b0', + context: { + sessionId: 54085233, + appName: 'my-webapp', + environment: 'default' + }, + enabled: true, + featureName: 'my-feature-toggle', +} +``` + + +### Example `getVariant` event {#example-getvariant} + + +```js +{ + eventType: 'getVariant', + eventId: '84b41a43-5ba0-47d8-b21f-a60a319607b0', + context: { + sessionId: 54085233, + appName: 'my-webapp', + environment: 'default' + }, + enabled: true, + featureName: 'my-feature-toggle', + variant: 'variantA' +} +``` + +## Enabling impression data + +Impression data is strictly an **opt-in** feature and must be enabled on a **per-toggle basis**. +You can enable and disable it both when you create a toggle and when you edit a toggle. + +You can enable impression data via the impression data toggle in the admin UI's toggle creation form. You can also go via the [the API, using the `impressionData` option](../api/admin/feature-toggles-api-v2.md#create-toggle). + +![A feature toggle creation form. At the end of the form is a heading that says "Impression data", a short paragraph that describes the feature, and a toggle to opt in or out of it.](/img/create_feat_impression.png) + +## Example setup + +:::caution +This functionality is currently only supported in the [Unleash Proxy client](../sdks/proxy-javascript.md) and [React Proxy client](../sdks/proxy-react.md). +::: + +The exact setup will vary depending on your [client SDK](../sdks/index.md). The below example configures the [Unleash Proxy client](/sdks/proxy-javascript) to listen for impression events and log them to the console. If "my-feature-toggle" is configured to emit impression data, then it will trigger an impression event as soon as Unleash is ready. + +```js +const unleash = new UnleashClient({ + url: 'https://eu.unleash-hosted.com/hosted/proxy', + clientKey: 'your-proxy-key', + appName: 'my-webapp', +}); + +unleash.start(); + +unleash.on("ready", () => { + unleash.isEnabled("my-feature-toggle"); +}) + +unleash.on("impression", (event) => { + // Capture the event here and pass it internal data lake or analytics provider + console.log(event); +}) +``` diff --git a/website/docs/api/admin/feature-toggles-api-v2.md b/website/docs/api/admin/feature-toggles-api-v2.md index 71e7ffe3521..9693bc3e79b 100644 --- a/website/docs/api/admin/feature-toggles-api-v2.md +++ b/website/docs/api/admin/feature-toggles-api-v2.md @@ -9,12 +9,12 @@ title: /api/admin/projects/:projectId In this document we will guide you on how you can work with feature toggles and their configuration. Please remember the following details: -- All feature toggles exists _inside a project_. -- A feature toggle exists _across all environments_. +- All feature toggles exists _inside a project_. +- A feature toggle exists _across all environments_. - A feature toggle can take different configuration, activation strategies, per environment. -> We will in this guide use [HTTPie](https://httpie.io) commands to show examples on how to interact with the API. +> We will in this guide use [HTTPie](https://httpie.io) commands to show examples on how to interact with the API. ### Get Project Overview {#fetching-project} @@ -146,10 +146,23 @@ This endpoint will return all feature toggles and high level environment details This endpoint will accept HTTP POST request to create a new feature toggle for a given _projectId_ +**Toggle options** + +This endpoint accepts the following toggle options: + +| Property name | Required | Description | Example value | +|------------------|----------|--------------------------------------------------------------------------------------------------------------|-------------------------| +| `name` | Yes | The name of the feature toggle. | `"my-feature-toggle"` | +| `description` | No | The feature toggle's description. Defaults to an empty string. | `"Turn my feature on!"` | +| `impressionData` | No | Whether to enable [impression data](../../advanced/impression-data.md) for this toggle. Defaults to `false.` | `true` | +| `type` | No | The [type of toggle](../../advanced/feature-toggle-types.md) you want to create. Defaults to `"release"` | `"release"` | + + **Example Query** -```sh -echo '{"name": "demo2", "description": "A new feature toggle"}' | http POST http://localhost:4242/api/admin/projects/default/features Authorization:$KEY` +```bash +echo '{"name": "demo2", "description": "A new feature toggle"}' | \ +http POST http://localhost:4242/api/admin/projects/default/features Authorization:$KEY` ``` @@ -388,7 +401,7 @@ Transfer-Encoding: chunked `http://localhost:4242/api/admin/projects/:projectId/features/:featureName/environments/:environment/strategies` -This endpoint will allow you to add a new strategy to a feature toggle in a given environment. +This endpoint will allow you to add a new strategy to a feature toggle in a given environment. **Example Query** @@ -598,4 +611,3 @@ http PATCH http://localhost:4242/api/admin/projects/default/features/demo/varian ] } ``` - diff --git a/website/docs/sdks/index.md b/website/docs/sdks/index.md index 2612d5bdd16..af55ce80487 100644 --- a/website/docs/sdks/index.md +++ b/website/docs/sdks/index.md @@ -49,55 +49,56 @@ If you see an item marked with a ❌ that you would find useful, feel free to re ::: -| Capability | [Java](/sdks/java_sdk) | [Node.js](/sdks/node_sdk) | [Go](/sdks/go_sdk) | [Python](/sdks/python_sdk) | [Ruby](/sdks/ruby_sdk) | [.NET](/sdks/dot_net_sdk) | [PHP](/sdks/php_sdk) | [Rust](https://github.com/unleash/unleash-client-rust) | [Unleash Proxy Server](unleash-proxy.md) | -|---------------------------------------------------------------------------------------------------|:----------------------:|:-------------------------:|:------------------:|:--------------------------:|:----------------------:|:-------------------------:|:--------------------:|:-------------------------------------------------------:|:----------------------------------------:| -| **Category: Initialization** | | | | | | | | | -| Async initialization | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | N/A -| Can block until synchronized | ✅ | ✅ | ⭕ | ⭕ | ⭕ | ✅ | ⭕ | ⭕ | N/A -| Default refresh interval | 10s | 15s | 15s | 15s | 15s | 30s | 30s | 15s | 5s -| Default metrics interval | 60s | 60s | 60s | 60s | 60s | 60s | 30s | 15s | 30s -| Context provider | ✅ | N/A | N/A | N/A | N/A | ✅ | ✅ | N/A | N/A -| Global fallback function | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | N/A -| Toggle Query: `namePrefix` | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ -| Toggle Query: `tags` | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ -| Toggle Query: `project_name` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | N/A | ⭕ | ✅ -| **Category: Custom Headers** | | | | | | | | | -| static | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ⭕ | N/A -| function | ✅ | ✅ | ⭕ | ✅ | ⭕ | ✅ | ⭕ | ⭕ | N/A -| **Category: Built-in strategies** | | | | | | | | | -| [Standard](../user_guide/activation_strategy#standard) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ -| [Gradual rollout](../user_guide/activation_strategy#gradual-rollout) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ -| [Gradual rollout: custom stickiness](../user_guide/activation_strategy#customize-stickiness-beta) | ✅ | ✅ | ⭕ | ✅ | ✅ | ✅ | ✅ | ⭕ | ✅ -| [UserID](../user_guide/activation_strategy#userids) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ -| [IP](../user_guide/activation_strategy#ips) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ -| [IP](../user_guide/activation_strategy#ips): CIDR syntax | ✅ | ✅ | ✅ | ✅ | ✅ | ⭕ | ⭕ | ✅ | ✅ -| [Hostname](../user_guide/activation_strategy#hostnames) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ -| **Category: [Custom strategies](../advanced/custom_activation_strategy)** | | | | | | | | | -| Basic support | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ -| **Category: [Strategy constraints](../advanced/strategy_constraints)** | | | | | | | | | -| Basic support (`IN`, `NOT_IN` operators) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ -| **Category: [Unleash Context](../user_guide/unleash_context)** | | | | | | | | | -| Static fields (`environment`, `appName`) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ -| Defined fields | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ -| Custom properties | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ -| **Category: [`isEnabled`](../client-specification#implementation-of-isenabled)** | | | | | | | | | -| Can take context | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ -| Override fallback value | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ -| Fallback function | ✅ | ✅ | ✅ | ✅ | ✅ | ⭕ | ⭕ | ⭕ | ✅ -| **Category: [Variants](../advanced/toggle_variants)** | | | | | | | | | -| Basic support | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ -| Custom fallback variant | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ⭕ | ✅ -| Custom weight | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ⭕ | ✅ -| [Custom stickiness (beta)](../advanced/stickiness#custom-stickiness-beta) | ✅ | ✅ | ⭕ | ✅ | ✅ | ✅ | ✅ | ⭕ | ✅ -| **Category: Local backup** | | | | | | | | | -| File based backup | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ⭕ | ✅ -| **Category: Usage metrics** | | | | | | | | | -| Can disable metrics | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ -| Client registration | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ -| Basic usage metrics (yes/no) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ -| **Category: Bootstrap (beta)** | | | | | | | | | -| Bootstrap from file | ✅ | ✅ | ⭕ | ⭕ | ⭕ | ⭕ | ⭕ | ⭕ | ⭕ -| Custom Bootstrap implementation | ✅ | ✅ | ⭕ | ⭕ | ⭕ | ⭕ | ⭕ | ⭕ | ⭕ +| Capability | [Java](/sdks/java_sdk) | [Node.js](/sdks/node_sdk) | [Go](/sdks/go_sdk) | [Python](/sdks/python_sdk) | [Ruby](/sdks/ruby_sdk) | [.NET](/sdks/dot_net_sdk) | [PHP](/sdks/php_sdk) | [Rust](https://github.com/unleash/unleash-client-rust) | [Unleash Proxy Server](unleash-proxy.md) | +|---------------------------------------------------------------------------------------------------|:----------------------:|:-------------------------:|:------------------:|:--------------------------:|:----------------------:|:-------------------------:|:--------------------:|:------------------------------------------------------:|:----------------------------------------:| +| **Category: Initialization** | | | | | | | | | | +| Async initialization | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | N/A | +| Can block until synchronized | ✅ | ✅ | ⭕ | ⭕ | ⭕ | ✅ | ⭕ | ⭕ | N/A | +| Default refresh interval | 10s | 15s | 15s | 15s | 15s | 30s | 30s | 15s | 5s | +| Default metrics interval | 60s | 60s | 60s | 60s | 60s | 60s | 30s | 15s | 30s | +| Context provider | ✅ | N/A | N/A | N/A | N/A | ✅ | ✅ | N/A | N/A | +| Global fallback function | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | N/A | +| Toggle Query: `namePrefix` | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | | +| Toggle Query: `tags` | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | | +| Toggle Query: `project_name` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | N/A | ⭕ | | +| **Category: Custom Headers** | | | | | | | | | | +| static | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ⭕ | N/A | +| function | ✅ | ✅ | ⭕ | ✅ | ⭕ | ✅ | ⭕ | ⭕ | N/A | +| **Category: Built-in strategies** | | | | | | | | | | +| [Standard](../user_guide/activation_strategy#standard) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | +| [Gradual rollout](../user_guide/activation_strategy#gradual-rollout) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | +| [Gradual rollout: custom stickiness](../user_guide/activation_strategy#customize-stickiness-beta) | ✅ | ✅ | ⭕ | ✅ | ✅ | ✅ | ✅ | ⭕ | | +| [UserID](../user_guide/activation_strategy#userids) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | +| [IP](../user_guide/activation_strategy#ips) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | +| [IP](../user_guide/activation_strategy#ips): CIDR syntax | ✅ | ✅ | ✅ | ✅ | ✅ | ⭕ | ⭕ | ✅ | | +| [Hostname](../user_guide/activation_strategy#hostnames) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | +| **Category: [Custom strategies](../advanced/custom_activation_strategy)** | | | | | | | | | | +| Basic support | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | +| **Category: [Strategy constraints](../advanced/strategy_constraints)** | | | | | | | | | | +| Basic support (`IN`, `NOT_IN` operators) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | +| **Category: [Unleash Context](../user_guide/unleash_context)** | | | | | | | | | | +| Static fields (`environment`, `appName`) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | +| Defined fields | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | +| Custom properties | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | +| **Category: [`isEnabled`](../client-specification#implementation-of-isenabled)** | | | | | | | | | | +| Can take context | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | +| Override fallback value | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | +| Fallback function | ✅ | ✅ | ✅ | ✅ | ✅ | ⭕ | ⭕ | ⭕ | | +| **Category: [Variants](../advanced/toggle_variants)** | | | | | | | | | | +| Basic support | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | +| Custom fallback variant | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ⭕ | | +| Custom weight | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ⭕ | | +| [Custom stickiness (beta)](../advanced/stickiness#custom-stickiness-beta) | ✅ | ✅ | ⭕ | ✅ | ✅ | ✅ | ✅ | ⭕ | | +| **Category: Local backup** | | | | | | | | | | +| File based backup | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ⭕ | | +| **Category: Usage metrics** | | | | | | | | | | +| Can disable metrics | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | +| Client registration | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | +| Basic usage metrics (yes/no) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | +| [Impression data](../advanced/impression-data.md) | ⭕ | ⭕ | ⭕ | ⭕ | ⭕ | ⭕ | ⭕ | ⭕ | N/A | +| **Category: Bootstrap (beta)** | | | | | | | | | | +| Bootstrap from file | ✅ | ✅ | ⭕ | ⭕ | ⭕ | ⭕ | ⭕ | ⭕ | | +| Custom Bootstrap implementation | ✅ | ✅ | ⭕ | ⭕ | ⭕ | ⭕ | ⭕ | ⭕ | | ## Community SDKs ❤️ {#community-sdks} diff --git a/website/docusaurus.config.js b/website/docusaurus.config.js index 148539ac499..677980a1142 100644 --- a/website/docusaurus.config.js +++ b/website/docusaurus.config.js @@ -160,6 +160,10 @@ module.exports = { to: '/user_guide/activation_strategy', from: '/user_guide/control_rollout', }, + { + from: '/advanced/impression_data', + to: '/advanced/impression-data', + } ], createRedirects: function (toPath) { if ( diff --git a/website/sidebars.js b/website/sidebars.js index 73c23c2331e..e9673b0305c 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -246,6 +246,7 @@ module.exports = { 'user_guide/activation_strategy', 'advanced/archived_toggles', 'advanced/audit_log', + 'advanced/impression-data', 'advanced/custom_activation_strategy', 'user_guide/environments', 'advanced/feature_toggle_types', diff --git a/website/static/img/create_feat_impression.png b/website/static/img/create_feat_impression.png new file mode 100644 index 00000000000..f885f7857f3 Binary files /dev/null and b/website/static/img/create_feat_impression.png differ