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>
Unleash · Feb 8, 2022 · acb98db · acb98db
1 parent de2e2ae
commit acb98db
Show file tree

Hide file tree

Showing 6 changed files with 178 additions and 56 deletions.
diff --git a/website/docs/advanced/impression-data.md 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
@@ -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
   ]
 }
 ```
-