diff --git a/docs/feature-management-experimentation/20-sdks-and-infrastructure/client-side-suites/ios-suite.md b/docs/feature-management-experimentation/20-sdks-and-infrastructure/client-side-suites/ios-suite.md index 9171b44faae..55dea34a1f1 100644 --- a/docs/feature-management-experimentation/20-sdks-and-infrastructure/client-side-suites/ios-suite.md +++ b/docs/feature-management-experimentation/20-sdks-and-infrastructure/client-side-suites/ios-suite.md @@ -19,7 +19,7 @@ Set up FME in your code base with the following two steps: Add the Harness FME SDK, RUM agent, and Suite into your project using Swift Package Manager by adding the following package dependencies: -- [iOS SDK] (https://github.com/splitio/ios-client), latest version `3.3.3` +- [iOS SDK](https://github.com/splitio/ios-client), latest version `3.3.3` - [iOS RUM](https://github.com/splitio/ios-rum), latest version `0.4.0` - [iOS Suite](https://github.com/splitio/ios-suite), latest version `2.2.3` diff --git a/docs/feature-management-experimentation/40-feature-management/monitoring-analysis/impressions.md b/docs/feature-management-experimentation/40-feature-management/monitoring-analysis/impressions.md index 3202132d02e..ea758c3beb9 100644 --- a/docs/feature-management-experimentation/40-feature-management/monitoring-analysis/impressions.md +++ b/docs/feature-management-experimentation/40-feature-management/monitoring-analysis/impressions.md @@ -32,6 +32,62 @@ Each impression contains these fields. | Traffic type ID and name | Traffic type associated to the feature flag evaluated. | | Treatment | Treatment that was returned. | +## Impression properties + +Impression properties allow you to attach custom metadata to impressions generated by an FME SDK when calling `getTreatment`. These properties can be useful for debugging, Live Tail analysis, or downstream external analytics from third-party integrations such as Amplitude. + +An example impression payload: + +```json +{ + "environmentId": "prod", + "feature": "new_ui", + "treatment": "on", + "key": "user_12345", + "timestamp": 1725682200000, + "properties": { // Optional key-value pairs you can append to impressions + "planType": "premium", + "appVersion": "2.3.1", + "region": "us-west" + } +} +``` + +### Supported SDKs for impression properties + +The following SDKs support appending custom properties for each `getTreatment` call: + + + + + | **Client-side SDK** | **Version that supports impression properties** | + |----------------------|-----------------------------------------------| + | [Browser SDK](/docs/feature-management-experimentation/sdks-and-infrastructure/client-side-sdks/browser-sdk#append-properties-to-impressions) | 1.2 and later | + | [iOS SDK](/docs/feature-management-experimentation/sdks-and-infrastructure/client-side-sdks/ios-sdk#append-properties-to-impressions) | 3.2.0 and later | + | [JavaScript SDK](/docs/feature-management-experimentation/sdks-and-infrastructure/client-side-sdks/javascript-sdk#append-properties-to-impressions) | 11.2.0 and later | + | [React SDK](/docs/feature-management-experimentation/sdks-and-infrastructure/client-side-sdks/react-sdk#append-properties-to-impressions) | 2.1.0 and later | + | [Redux SDK](/docs/feature-management-experimentation/sdks-and-infrastructure/client-side-sdks/redux-sdk#append-properties-to-impressions) | 2.1.0 and later | + + + + + | **Client-side SDK Suite** | **Version that supports impression properties** | + |----------------------|-----------------------------------------------| + | [Browser Suite](/docs/feature-management-experimentation/sdks-and-infrastructure/client-side-suites/browser-suite#append-properties-to-impressions) | 2.1.0 and later | + | [iOS Suite](/docs/feature-management-experimentation/sdks-and-infrastructure/client-side-suites/ios-suite#append-properties-to-impressions) | 2.1.0 and later | + + + + + | **Server-side SDK** | **Version that supports impression properties** | + |----------------------|-----------------------------------------------| + | [Java SDK](/docs/feature-management-experimentation/sdks-and-infrastructure/server-side-sdks/java-sdk#append-properties-to-impressions) | 4.15.0 and later | + | [Node.js SDK](/docs/feature-management-experimentation/sdks-and-infrastructure/server-side-sdks/nodejs-sdk#append-properties-to-impressions) | 11.2.0 and later | + + + + + ## Tracking impressions Impressions are tracked by each Harness FME SDK and are periodically sent to Harness backend servers. @@ -166,7 +222,10 @@ Additionally, if you don’t want to send a customer UUID to Harness as the key, ## Integrations for impression data -Use our integrations to push FME feature flag impression data to your existing platforms or your data warehouse for a comprehensive view of user engagement and other key use metrics. Integration documentation is available for the following: +Use our integrations to push FME feature flag impression data to your existing platforms or your data warehouse for a comprehensive view of user engagement and other key user metrics. + +Integration documentation is available for the following: + - [Amazon S3](/docs/feature-management-experimentation/integrations/amazon-s3) - [Amplitude](/docs/feature-management-experimentation/integrations/amplitude) - [Full Story](/docs/feature-management-experimentation/integrations/fullstory) @@ -178,4 +237,4 @@ Use our integrations to push FME feature flag impression data to your existing p - [Quantum-Metric](/docs/feature-management-experimentation/integrations/quantummetric) - [SmartBear Bugsnag](/docs/feature-management-experimentation/integrations/bugsnag) - [Segment](/docs/feature-management-experimentation/integrations/segment) -- [Webhook (outgoing)](https://help.split.io/hc/en-us/articles/360020700232) +- [Webhook (outgoing)](/docs/feature-management-experimentation/api/webhook/impressions/) diff --git a/docs/feature-management-experimentation/80-integrations/amplitude.md b/docs/feature-management-experimentation/80-integrations/amplitude.md index c8076dc4abd..e396ee796b9 100644 --- a/docs/feature-management-experimentation/80-integrations/amplitude.md +++ b/docs/feature-management-experimentation/80-integrations/amplitude.md @@ -10,11 +10,34 @@ Amplitude is a product intelligence platform that helps teams convert, engage, a This integration will send impressions to Amplitude as events, mapped according to the configuration settings. It gives you the ability to connect Harness FME to Amplitude and easily run deeper analysis on A/B and beta tests. -Each call to **getTreatment** in an FME SDK is passed to Amplitude as a separate event. +Each call to `getTreatment` in an FME SDK is passed to Amplitude as a separate event. Harness FME also sends impression properties to Amplitude along with each `getTreatment` event. If you define a custom property with the same name as one of the [built-in properties](/docs/feature-management-experimentation/feature-management/monitoring-analysis/impressions#impression-fields) that Harness FME adds by default, your custom value will overwrite the built-in value in Amplitude. + +In this example, the following impression in Amplitude includes the `key` property: + +```json +{ + "key": "value" +} +``` +![](./static/amplitude-impression-1.png) + +In this example, the following impression includes three custom properties: + +```json +{ + "customProperty1": "value1", + "customProperty2": "value2", + "customProperty3": "value3", +} +``` + +![](./static/amplitude-impression-2.png) + +For more information about impression properties, see the [Impressions documentation](/docs/feature-management-experimentation/feature-management/monitoring-analysis/impressions#impression-properties). ### In Amplitude -Within your Amplitude account, set up Harness FME as a data source. Copy your Amplitude project's API Key to be used in FME. +Within your Amplitude account, set up Harness FME as a data source. Copy your Amplitude project's API Key to be used in Harness FME. ### In Harness FME @@ -25,9 +48,9 @@ Within your Amplitude account, set up Harness FME as a data source. Copy your Am ![Amplitude](./static/amplitude-for-default.png) 4. Select the environment from where you want data sent and then select how you want to map Harness FME traffic types to Amplitude identities. You can select either: - * user_id - * device_id -5. FME impressions are shown as ‘get_treatment’ events in Amplitude by default. You can customize this event name, with a maximum of 1,024 characters. + * `user_id` + * `device_id` +5. FME impressions are shown as `get_treatment` events in Amplitude by default. You can customize this event name, with a maximum of 1,024 characters. 6. Paste the API key and secret from your Amplitude account, copied above, and click **Save**. 7. Select your Amplitude region. The default region is Standard. 8. Once you save the configuration, send a test event from Harness FME into Amplitude. @@ -38,9 +61,11 @@ You can repeat this process depending on how many environments and traffic types There are some situations where the recommended approach to send FME impressions to Amplitude is not preferred. One example is when the same impression is expected to be sent frequently. Amplitude bills by event volume so each impression counts against your organization's event quota. -Using Amplitude’s Identify API, you can leverage a **User Property** in Amplitude to store which FME feature flag treatments a user receives. If you have already instrumented your application with Amplitude, this approach should be seamless to configure, and the user properties can then be used in Amplitude for further analysis. This integration does not send events to Amplitude. This use case is discussed further in [Amplitude's documentation](https://help.amplitude.com/hc/en-us/articles/115001580108-Analyze-A-B-test-results-in-Amplitude) under **2) Identify API**. As Amplitude notes, be cautious that: +Using Amplitude’s Identify API, you can leverage a **User Property** in Amplitude to store which FME feature flag treatments a user receives. If you have already instrumented your application with Amplitude, this approach should be seamless to configure, and the user properties can then be used in Amplitude for further analysis. This integration does not send events to Amplitude. This use case is discussed further in [Amplitude's documentation](https://help.amplitude.com/hc/en-us/articles/115001580108-Analyze-A-B-test-results-in-Amplitude) under **2) Identify API**. + +As Amplitude notes, be cautious that: -*The user property will not take effect until the user takes an action.* +> *The user property will not take effect until the user takes an action.* ### How to implement @@ -48,7 +73,7 @@ If you have an existing Amplitude integration with Harness FME, you will need to ![Integrations Amplitude for Harness FME](./static/amplitude-for-default.png) -#### Step 1: Rationalize the Harness FME traffic type with the Amplitude id +#### Step 1: Rationalize the Harness FME traffic type with the Amplitude ID If you are using an id in Amplitude other than that of a known user, you should not call the identity API to set a user_id with that id. The device_id may be an appropriate alternative in that scenario. If using the SDK, this may be already handled, but it is important to keep in mind which Amplitude id you are using and to which traffic type it maps to in Harness FME. @@ -89,7 +114,7 @@ function amplitudeIdentify(amplitudeApiKey, userId, splitName, treatment) { -2. Running as an impression listener should only be used for calling the identify API with additional properties that are available from the frontend that you need. The next option we will go over is a more robust approach. The code below outlines the creation of a service that can utilize Harness FME's [impressions webhook](https://help.split.io/hc/en-us/articles/360020700232-Webhook-impressions) using a Node.js script. +2. Running as an impression listener should only be used for calling the identify API with additional properties that are available from the frontend that you need. The next option we will go over is a more robust approach. The code below outlines the creation of a service that can utilize Harness FME's [impressions webhook](/docs/feature-management-experimentation/api/webhook/impressions/) using a Node.js script. The piece of Node.js code below requires the express and axios libraries. diff --git a/docs/feature-management-experimentation/80-integrations/mixpanel.md b/docs/feature-management-experimentation/80-integrations/mixpanel.md index 850c2fc92b5..bc28514d3d6 100644 --- a/docs/feature-management-experimentation/80-integrations/mixpanel.md +++ b/docs/feature-management-experimentation/80-integrations/mixpanel.md @@ -32,7 +32,7 @@ Both AWS and GCF versions cache the HTTP client used to POST to Mixpanel in thei #### Step 2: Configure Harness FME to use your webhook -Copy your function/lambdas URL endpoint and paste it into the [FME impressions webhook](https://help.split.io/hc/en-us/articles/360020700232-Webhook-impressions) configuration. +Copy your function/lambdas URL endpoint and paste it into the [FME impressions webhook](/docs/feature-management-experimentation/api/webhook/impressions/) configuration. Make sure you choose the environment from which you wish to receive impressions. If you are generating traffic in a testing environment, you will not see those impressions in production, and vice-versa. diff --git a/docs/feature-management-experimentation/80-integrations/static/amplitude-impression-1.png b/docs/feature-management-experimentation/80-integrations/static/amplitude-impression-1.png new file mode 100644 index 00000000000..8e5b298e283 Binary files /dev/null and b/docs/feature-management-experimentation/80-integrations/static/amplitude-impression-1.png differ diff --git a/docs/feature-management-experimentation/80-integrations/static/amplitude-impression-2.png b/docs/feature-management-experimentation/80-integrations/static/amplitude-impression-2.png new file mode 100644 index 00000000000..6c40bc5ff2b Binary files /dev/null and b/docs/feature-management-experimentation/80-integrations/static/amplitude-impression-2.png differ diff --git a/release-notes/feature-management-experimentation.md b/release-notes/feature-management-experimentation.md index e75436ddc14..af8fe098efb 100644 --- a/release-notes/feature-management-experimentation.md +++ b/release-notes/feature-management-experimentation.md @@ -173,7 +173,10 @@ const App = () => ( ---- #### 2025-04-10 The following SDKs now allow you to append properties to impressions for each `getTreatment` call: Browser, iOS, JavaScript, Node.js, React, and Redux. This provides additional context for in-product troubleshooting within Live tail or downstream external analysis. + #### Related documentation + +- [Impressions](/docs/feature-management-experimentation/feature-management/monitoring-analysis/impressions#impression-properties) - [Browser SDK](/docs/feature-management-experimentation/sdks-and-infrastructure/client-side-sdks/browser-sdk#append-properties-to-impressions) - [Browser SDK Suite](/docs/feature-management-experimentation/sdks-and-infrastructure/client-side-suites/browser-suite#append-properties-to-impressions) - [iOS SDK](/docs/feature-management-experimentation/sdks-and-infrastructure/client-side-sdks/ios-sdk#append-properties-to-impressions)