diff --git a/website/docs/advanced/impression-data.md b/website/docs/advanced/impression-data.md index c4f0ea8106f..117f9045c97 100644 --- a/website/docs/advanced/impression-data.md +++ b/website/docs/advanced/impression-data.md @@ -72,7 +72,7 @@ This table describes all the properties on the impression events: 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). +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). For more detailed instructions, see [the section on enabling impression data in the how-to guide for capturing impression data](../how-to/how-to-capture-impression-data.mdx#step-1). ![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) diff --git a/website/docs/how-to/how-to-capture-impression-data.mdx b/website/docs/how-to/how-to-capture-impression-data.mdx new file mode 100644 index 00000000000..6a16ef2e14b --- /dev/null +++ b/website/docs/how-to/how-to-capture-impression-data.mdx @@ -0,0 +1,85 @@ +--- +title: How to capture impression data +--- +import ApiRequest from '@site/src/components/ApiRequest' + +:::info Placeholders +Placeholders in code samples below are delimited by angle brackets (i.e. ``). You will need to replace them with the values that are correct in _your_ situation for the code samples to run properly. +::: + +Unleash allows you to gather [**impression data**](../advanced/impression-data.md) from your feature toggles, giving you complete visibility into who checked what toggles and when. What you do with this data is entirely up to you, but a common use case is to send it off to an aggregation and analytics service such as [Posthog](https://posthog.com/) or [Google Analytics](https://analytics.google.com/), either just for monitoring purposes or to facilitate [A/B testing](../topics/a-b-testing.md). + +This guide will take you through everything you need to do in Unleash to facilitate such a workflow. It will show you how to send data to Posthog as an example sink, but the exact same principles will apply to any other service of the same kind. + + +## Prerequisites + +We will assume that you have the necessary details for your third-party service: + +- **where to send the data to**. We'll refer to this in the code samples below as **``**. +- **what format the data needs to be in**. This will determine how you transform the event data before you send it. + +In addition, you'll need to have a toggle to record impression data for and an [Unleash client SDK](../sdks/index.md) that supports impression data. This guide will use the [JavaScript proxy SDK](../sdks/proxy-javascript.md). + +When you have those things sorted, follow the below steps. + +## Step 1: Enable impression data for your feature toggle {#step-1} + +Because impression data is an **opt-in feature**, the first step is to enable it for the feature you want to gather data from. You can use both the UI and the API. + +### Enabling impression data for new feature toggles {#step-1-new-toggles} + +When you create a new feature toggle via the UI, there's an option at the end of the form that you must enable: + +![The create feature toggle form. There's a toggle at the end of the form that enables or disables impression data. It's labeled "impression data".](/img/enable-impression-data.png) + +To create a feature toggle with impression data enabled, set the `impressionData` option to `true` in the request payload, as seen below. For more options, check the [reference docs on creating features](../api/admin/feature-toggles-api-v2.md#create-toggle). + +", impressionData: true}} url="api/admin/projects//features" title="Create a feature toggle with impression data enabled."/> + +### Enabling impression data for existing feature toggles {#step-1-existing-toggles} + +To enable impression data for an existing toggle, use the "edit" button on the toggle's page in the admin UI. It will take you to a form that looks like the toggle creation form. Use the "impression data" toggle to enable impression data the same way you would when [enabling impression data for a new feature toggle](#step-1-new-toggles). + +![The create feature toggle form. There's a toggle at the end of the form that enables or disables impression data. It's labeled "impression data".](/img/enable-impression-data-existing-toggle.png) + +To enable impression data for an existing toggle, use the [API's toggle patching functionality](../api/admin/feature-toggles-api-v2.md#patch-toggle): + + + + +## Step 2: Capture impression events in your client {#step-2} + +In your client SDK, initialize the library for the third party service you're using. +For the full details on setting up a Posthog client, see [the official Posthog JavaScript client docs](https://posthog.com/docs/integrate/client/js). +The steps below will use extracts from said documentation. + +After initializing the library, you'll probably also want to identify the current user, so that events can be correlated properly: + +``` js title="Identify the user." +posthog.identify(userId); +``` + +### Capture and transform the event + +Attach an event listener to Unleash that listens for `"impression"` events. Inside the listener, transform the event data to the format you want and send it to your analytics service. + +``` js title="Capture, transform, and send impression data." +// listen for impression events +unleash.on("impression", (event) => { + + // capture and transform events + posthog.capture(event.eventType, { + ...event.context, + distinct_id: event.context?.userId, + featureName: event.featureName, + enabled: event.enabled, + variant: event.variant, + }); + +}); +``` + +Posthog expects an object with a `distinct_id` property that it uses to correlate data. +Additionally, you can add whatever properties you want, such as the feature toggle name, its state and/or variant, or the whole Unleash context. +The `posthog.capture` method sends the event data to your Posthog instance. diff --git a/website/docusaurus.config.js b/website/docusaurus.config.js index 3562cc6eb3c..108a0272a1d 100644 --- a/website/docusaurus.config.js +++ b/website/docusaurus.config.js @@ -40,12 +40,13 @@ module.exports = { }, prism: { additionalLanguages: [ - 'java', - 'swift', - 'ruby', 'csharp', + 'http', + 'java', 'kotlin', 'php', + 'ruby', + 'swift', ], }, footer: { diff --git a/website/sidebars.js b/website/sidebars.js index 5e0b4e321f0..de1844eacb6 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -57,6 +57,7 @@ module.exports = { 'user_guide/create_feature_toggle', 'how-to/how-to-define-custom-context-fields', 'how-to/how-to-use-custom-strategies', + 'how-to/how-to-capture-impression-data' ], type: 'category', link: { diff --git a/website/src/components/ApiRequest.jsx b/website/src/components/ApiRequest.jsx new file mode 100644 index 00000000000..55bb02886d6 --- /dev/null +++ b/website/src/components/ApiRequest.jsx @@ -0,0 +1,60 @@ +/** + This component displays API requests in multiple different formats + using the tabs component. It syncs across the page. + + Please note: it doees NOT cover all kinds of API requests just yet. + If the type you're looking for isn't included, you may need to do + some extra development before it can be used. In the future, it may + be necessary to separate into multiple components based on request + types, for instance. + +**/ + +import React from 'react'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + +const indentation = 2; + +const Component = ({ verb, payload, url, title }) => { + const verbUpper = verb?.toUpperCase() || ''; + const prettyPayload = JSON.stringify(payload, null, indentation); + + return ( + + + + {` +${verbUpper} /${url} +Authorization: +content-type: application/json + +${prettyPayload} +`.trim()} + + + + + {` +curl -H "Content-Type: application/json" \\ + -H "Authorization: " \\ + -X ${verbUpper} \\ + -d '${prettyPayload}' \\ + /${url} +`.trim()} + + + + + {`echo '${prettyPayload}' \\ +| http ${verbUpper} \\ + /${url} \\ + Authorization:`.trim()} + + + + ); +}; + +export default Component; diff --git a/website/static/img/enable-impression-data-existing-toggle.png b/website/static/img/enable-impression-data-existing-toggle.png new file mode 100644 index 00000000000..e85fa544c30 Binary files /dev/null and b/website/static/img/enable-impression-data-existing-toggle.png differ diff --git a/website/static/img/enable-impression-data.png b/website/static/img/enable-impression-data.png new file mode 100644 index 00000000000..0ee7a3910a6 Binary files /dev/null and b/website/static/img/enable-impression-data.png differ