Merge pull request #1345 from Unleash/docs/impression-data-how-to

docs: Add "How to send impression data to your third-party sink" guide

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)
 

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. `<placeholder-name>`). 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 **`<sink-url>`**.
+- **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).
+
+<ApiRequest verb="post" payload={{name: "<feature-toggle-name>", impressionData: true}} url="api/admin/projects/<project-id>/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):
+
+<ApiRequest verb="patch" payload={[{op: "replace", path: "/impressionData", value: true}]} url="api/admin/projects/<project-id>/features/<feature-toggle-name>" title="Enable impression data on an existing 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.

website/docusaurus.config.js

@@ -40,12 +40,13 @@ module.exports = {
         },
         prism: {
             additionalLanguages: [
-                'java',
-                'swift',
-                'ruby',
                 'csharp',
+                'http',
+                'java',
                 'kotlin',
                 'php',
+                'ruby',
+                'swift',
             ],
         },
         footer: {

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: {

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 (
+        <Tabs groupId="api-request">
+            <TabItem value="http" label="HTTP">
+                <CodeBlock language="http" title={title}>
+                    {`
+${verbUpper} <unleash-url>/${url}
+Authorization: <API-token>
+content-type: application/json
+
+${prettyPayload}
+`.trim()}
+                </CodeBlock>
+            </TabItem>
+            <TabItem value="curl" label="cURL">
+                <CodeBlock language="bash" title={title}>
+                    {`
+curl -H "Content-Type: application/json" \\
+     -H "Authorization: <API-token>" \\
+     -X ${verbUpper} \\
+     -d '${prettyPayload}' \\
+     <unleash-url>/${url}
+`.trim()}
+                </CodeBlock>
+            </TabItem>
+            <TabItem value="httpie" label="HTTPie">
+                <CodeBlock language="bash" title={title}>
+                    {`echo '${prettyPayload}' \\
+| http ${verbUpper} \\
+  <unleash-url>/${url} \\
+  Authorization:<API-token>`.trim()}
+                </CodeBlock>
+            </TabItem>
+        </Tabs>
+    );
+};
+
+export default Component;