diff --git a/docs/feature-management-experimentation/20-sdks-and-infrastructure/client-side-sdks/flutter-plugin.md b/docs/feature-management-experimentation/20-sdks-and-infrastructure/client-side-sdks/flutter-plugin.md index 63939220679..48687812916 100644 --- a/docs/feature-management-experimentation/20-sdks-and-infrastructure/client-side-sdks/flutter-plugin.md +++ b/docs/feature-management-experimentation/20-sdks-and-infrastructure/client-side-sdks/flutter-plugin.md @@ -286,6 +286,35 @@ if (treatment == 'on') { +### Append properties to impressions + +[Impressions](/docs/feature-management-experimentation/feature-management/monitoring-analysis/impressions) are generated by the SDK each time a `getTreatment` method is called. These impressions are periodically sent back to Harness servers for feature monitoring and experimentation. + +You can append properties to an impression by passing an object of key-value pairs to the `getTreatment` method. These properties are then included in the impression sent by the SDK and can provide useful context to the impression data. + +Three types of properties are supported: strings, numbers, and booleans. + +```dart +_split.client(onReady: (client) async { + final treatment = await client.getTreatment( + 'FEATURE_FLAG_NAME', + properties: { + 'userType': 'premium', // string + 'loginCount': 42, // number + 'isAdmin': true // boolean + }, + ); + + if (treatment == 'on') { + print('Feature ON'); + } else if (treatment == 'off') { + print('Feature OFF'); + } else { + print('Control treatment'); + } +}); +``` + ### Shutdown Call the `client.destroy()` method once you've stopped using the client, as this method gracefully shuts down the SDK by stopping all background threads, clearing caches, closing connections, and flushing the remaining unpublished impressions. diff --git a/docs/feature-management-experimentation/20-sdks-and-infrastructure/client-side-suites/android-suite.md b/docs/feature-management-experimentation/20-sdks-and-infrastructure/client-side-suites/android-suite.md index f3d18a30046..4126c2a69bc 100644 --- a/docs/feature-management-experimentation/20-sdks-and-infrastructure/client-side-suites/android-suite.md +++ b/docs/feature-management-experimentation/20-sdks-and-infrastructure/client-side-suites/android-suite.md @@ -469,6 +469,54 @@ val treatmentsByFlagSets = client.getTreatmentsByFlagSets(flagSets) +### Append properties to impressions + +[Impressions](/docs/feature-management-experimentation/feature-management/monitoring-analysis/impressions) are generated by the SDK each time a `getTreatment` method is called. These impressions are periodically sent back to Harness servers for feature monitoring and experimentation. + +You can append properties to an impression by passing an object of key-value pairs to the `getTreatment` method. These properties are then included in the impression sent by the SDK and can provide useful context to the impression data. + +Three types of properties are supported: strings, numbers, and booleans. + + + + +```java +SplitClient client = suite.client(); + +// Get treatment for a flag +String treatment = client.getTreatment("FEATURE_FLAG_NAME"); + +// Append properties with suite.track() +Map properties = new HashMap<>(); +properties.put("package", "premium"); +properties.put("admin", true); +properties.put("discount", 50L); + +suite.track("flag_evaluated", null, properties); +``` + + + + +```kotlin +val client = suite.client() + +// Get treatment for a flag +val treatment = client.getTreatment("FEATURE_FLAG_NAME") + +// Append properties with suite.track() +val properties = mapOf( + "package" to "premium", + "admin" to true, + "discount" to 50L +) + +suite.track("flag_evaluated", null, properties) +``` + + + + ### Track Tracking events is the first step to getting experimentation data into Harness FME and allows you to measure the impact of your feature flags on your users' actions and metrics. See the [Events](/docs/feature-management-experimentation/release-monitoring/events/) documentation for more information. 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/20-sdks-and-infrastructure/server-side-sdks/python-sdk.md b/docs/feature-management-experimentation/20-sdks-and-infrastructure/server-side-sdks/python-sdk.md index dc4a48a1450..b1a3cb8ccdb 100644 --- a/docs/feature-management-experimentation/20-sdks-and-infrastructure/server-side-sdks/python-sdk.md +++ b/docs/feature-management-experimentation/20-sdks-and-infrastructure/server-side-sdks/python-sdk.md @@ -661,7 +661,7 @@ print(treatments) -### Get Treatments with Configurations +### Get treatments with configurations To [leverage dynamic configurations with your treatments](/docs/feature-management-experimentation/feature-management/setup/dynamic-configurations), you should use the `get_treatment_with_config` method. @@ -795,6 +795,61 @@ for feature_flag, treatment_with_config in result.items(): +### Append properties to impressions + +[Impressions](/docs/feature-management-experimentation/feature-management/monitoring-analysis/impressions) are generated by the SDK each time a `getTreatment` method is called. These impressions are periodically sent back to Harness servers for feature monitoring and experimentation. + +You can append properties to an impression by passing an object of key-value pairs to the `getTreatment` method. These properties are then included in the impression sent by the SDK and can provide useful context to the impression data. + +Three types of properties are supported: strings, numbers, and booleans. + + + + +```python +# Define impression properties +properties = { + "userType": "premium", # string + "loginCount": 42, # number + "isAdmin": True # boolean +} + +# Get treatment with properties +treatment = split.get_treatment('key', 'FEATURE_FLAG_NAME', properties=properties) + +if treatment == "on": + # Show ON treatment +elif treatment == "off": + # Show OFF treatment +else: + # Control treatment +``` + + + + +```python +# Define impression properties +properties = { + "userType": "premium", # string + "loginCount": 42, # number + "isAdmin": True # boolean +} + +# Get treatment with properties +treatment = await split.get_treatment('key', 'FEATURE_FLAG_NAME', properties=properties) + +if treatment == "on": + # Show ON treatment +elif treatment == "off": + # Show OFF treatment +else: + # Control treatment +``` + + + + ### Shutdown The in-memory implementation of Python uses threads in Multi-threaded mode and tasks in asyncio mode to synchronize feature flags, segments, and impressions. If at any point in the application the SDK factory client is not longer needed, you can disable it by calling the `destroy()` method on the factory object. diff --git a/docs/feature-management-experimentation/20-sdks-and-infrastructure/server-side-sdks/ruby-sdk.md b/docs/feature-management-experimentation/20-sdks-and-infrastructure/server-side-sdks/ruby-sdk.md index c7b57fdfade..463b8d81df2 100644 --- a/docs/feature-management-experimentation/20-sdks-and-infrastructure/server-side-sdks/ruby-sdk.md +++ b/docs/feature-management-experimentation/20-sdks-and-infrastructure/server-side-sdks/ruby-sdk.md @@ -235,7 +235,7 @@ treatments = split.get_treatments_by_flag_sets('key', ['backend', 'server_side'] You can also use the [Split Manager](#manager) if you want to get all of your treatments at once. -### Get Treatments with Configurations +### Get treatments with configurations To [leverage dynamic configurations with your treatments](/docs/feature-management-experimentation/feature-management/setup/dynamic-configurations), you should use the `get_treatment_with_config` method. @@ -299,6 +299,34 @@ end +### Append properties to impressions + +[Impressions](/docs/feature-management-experimentation/feature-management/monitoring-analysis/impressions) are generated by the SDK each time a `getTreatment` method is called. These impressions are periodically sent back to Harness servers for feature monitoring and experimentation. + +You can append properties to an impression by passing an object of key-value pairs to the `getTreatment` method. These properties are then included in the impression sent by the SDK and can provide useful context to the impression data. + +Three types of properties are supported: strings, numbers, and booleans. + +```ruby +# Define impression properties +properties = { + userType: 'premium', # string + loginCount: 42, # number + isAdmin: true # boolean +} + +# Get treatment with properties +treatment = split_client.get_treatment('KEY', 'FEATURE_FLAG_NAME', properties: properties) + +if treatment == 'on' + # Show ON treatment +elsif treatment == 'off' + # Show OFF treatment +else + # Control treatment +end +``` + ### Shutdown Call the `.destroy` method before letting a process using the SDK exit, as this method gracefully shuts down the SDK by stopping all background threads, clearing caches, closing connections, and flushing the remaining unpublished impressions. 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..fdccfe95d6d 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,67 @@ 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** | + |----------------------|-----------------------------------------------| + | [Android SDK](/docs/feature-management-experimentation/sdks-and-infrastructure/client-side-sdks/android-sdk#append-properties-to-impressions) | 5.2.0 and later | + | [Browser SDK](/docs/feature-management-experimentation/sdks-and-infrastructure/client-side-sdks/browser-sdk#append-properties-to-impressions) | 1.2 and later | + | [Flutter Plugin](/docs/feature-management-experimentation/sdks-and-infrastructure/client-side-sdks/flutter-plugin#append-properties-to-impressions) | 1.0.0 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** | + |----------------------|-----------------------------------------------| + | [Android Suite](/docs/feature-management-experimentation/sdks-and-infrastructure/client-side-suites/android-suite#append-properties-to-impressions) | 2.1.0 and later | + | [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 | + | [Ruby SDK](/docs/feature-management-experimentation/sdks-and-infrastructure/server-side-sdks/ruby-sdk#append-properties-to-impressions) | 8.7.0 and later | + | [Python SDK](/docs/feature-management-experimentation/sdks-and-infrastructure/server-side-sdks/python-sdk#append-properties-to-impressions) | 10.4.0 and later | + + + + + ## Tracking impressions Impressions are tracked by each Harness FME SDK and are periodically sent to Harness backend servers. @@ -166,7 +227,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 +242,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..0e6e01b0f86 100644 --- a/release-notes/feature-management-experimentation.md +++ b/release-notes/feature-management-experimentation.md @@ -1,7 +1,7 @@ --- title: Feature Management & Experimentation release notes sidebar_label: Feature Management & Experimentation -date: 2025-07-25T10:00:00 +date: 2025-09-17T10:00:00 tags: ["fme", "feature management experimentation"] sidebar_position: 11 --- @@ -12,7 +12,7 @@ import HarnessApiData from '../src/components/HarnessApiData/index.tsx'; These release notes describe recent changes to Harness Feature Management & Experimentation (FME). -#### Last updated: July 25, 2025 +#### Last updated: September 18, 2025 ## July 2025 @@ -173,9 +173,15 @@ 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) +- [Android SDK](/docs/feature-management-experimentation/sdks-and-infrastructure/client-side-sdks/android-sdk/#append-properties-to-impressions) +- [Android Suite](/docs/feature-management-experimentation/sdks-and-infrastructure/client-side-suites/android-suite#append-properties-to-impressions) - [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) +- [Flutter Plugin](/docs/feature-management-experimentation/sdks-and-infrastructure/client-side-sdks/flutter-plugin#append-properties-to-impressions) - [iOS SDK](/docs/feature-management-experimentation/sdks-and-infrastructure/client-side-sdks/ios-sdk#append-properties-to-impressions) - [iOS SDK Suite](/docs/feature-management-experimentation/sdks-and-infrastructure/client-side-suites/ios-suite#append-properties-to-impressions) - [Java SDK](/docs/feature-management-experimentation/sdks-and-infrastructure/server-side-sdks/java-sdk#append-properties-to-impressions) @@ -183,6 +189,8 @@ The following SDKs now allow you to append properties to impressions for each `g - [Node.js SDK](/docs/feature-management-experimentation/sdks-and-infrastructure/server-side-sdks/nodejs-sdk#append-properties-to-impressions) - [React SDK](/docs/feature-management-experimentation/sdks-and-infrastructure/client-side-sdks/react-sdk#append-properties-to-impressions) - [Redux SDK](/docs/feature-management-experimentation/sdks-and-infrastructure/client-side-sdks/redux-sdk#append-properties-to-impressions) +- [Ruby SDK](/docs/feature-management-experimentation/sdks-and-infrastructure/server-side-sdks/ruby-sdk#append-properties-to-impressions) +- [Python SDK](/docs/feature-management-experimentation/sdks-and-infrastructure/server-side-sdks/python-sdk#append-properties-to-impressions) ## March 2025 ### [New Feature] Feature flag impression toggle