mirror of
https://github.com/Unleash/unleash.git
synced 2025-10-27 11:02:16 +01:00
docs: add docs for impression data (#1328)
* docs: add docs for impression data * fix: update wording * Update website/docs/advanced/impression_data.md Co-authored-by: Thomas Heartman <thomas@getunleash.ai> * Update website/docs/advanced/impression_data.md Co-authored-by: Thomas Heartman <thomas@getunleash.ai> * docs: use hyphen instead of underscore in file name and title/slug We've been very inconsistent with our use of separators previously (we should try and find a standard). Hyphens are most common online, so I've switched to that instead. * docs: use syntax highlighting for shell commands * docs: start outlining impression data restructure. * docs: Add impression data info to API: create toggles * docs: Add impression data row to compatibility matrix * docs: restructures the impression data reference doc. * chore: remove question callout in source material * docs: add redirect for `impression_data` -> 'impression-data' * docs: Add sdk availability to availability note * chore: Fix broken doc paths. Co-authored-by: Thomas Heartman <thomas@getunleash.ai>
This commit is contained in:
Fredrik Strand Oseberg
GitHub
parent
de2e2ae934
commit
acb98db00f
104
website/docs/advanced/impression-data.md
Normal file
104
website/docs/advanced/impression-data.md
Normal file
@ -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).
|
||||
|
||||
|
||||
|
||||
## 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);
|
||||
})
|
||||
```
|
||||
@ -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
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
@ -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}
|
||||
|
||||
|
||||
@ -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 (
|
||||
|
||||
@ -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',
|
||||
|
||||
BIN
website/static/img/create_feat_impression.png
Normal file
BIN
website/static/img/create_feat_impression.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 586 KiB |
Loading…
Reference in New Issue
Block a user