From 307bc19968af81f1bdeacee26d28ccc438bcbdc0 Mon Sep 17 00:00:00 2001 From: Austin Lai Date: Tue, 12 Aug 2025 16:11:56 -0700 Subject: [PATCH 01/11] Remove Feature Management FAQs --- .../10-getting-started/overview/boxes-demo.md | 69 +++++++++++ .../overview/build-a-resilient-integration.md | 2 +- .../overview/create-a-metric-alert-policy.md | 2 +- .../overview/create-a-metric.md | 2 +- .../overview/create-an-experiment.md | 17 ++- .../10-getting-started/overview/index.md | 4 + .../manage-the-feature-flag-lifecycle.md | 2 +- .../overview/send-event-data.md | 2 +- .../static}/boxes-split.txt | 0 .../static}/boxes.htm | 0 .../static}/create-box-split.sh.zip | Bin .../static/split-boxes-chrome.png | Bin .../static/split-boxes-demo.png | Bin .../client-side-sdks/javascript-sdk.md | 67 ++++++++++- .../best-practices/_category_.json | 6 - ...en-targeting-an-account-or-organization.md | 21 ---- .../best-practices/csv-file-comma.md | 23 ---- .../best-practices/o-reilly-book.md | 9 -- .../best-practices/split-boxes-demo.md | 55 --------- ...setting-the-order-of-treatments-matters.md | 85 -------------- .../create-a-feature-flag.md | 70 ++++++++++- .../default-treatment.md | 38 +++--- ...e-feature-flag-treatments-and-targeting.md | 67 ++++++++++- .../dynamic-configurations.md | 28 ++++- .../faqs/_category_.json | 6 - ...even-after-deleting-the-targeting-rules.md | 21 ---- ...-configuration-section-does-not-show-up.md | 16 --- .../ensure-a-consistent-user-experience.md | 34 ------ ...users-with-a-superseding-targeting-rule.md | 21 ---- ...can-you-tell-what-treatment-a-user-sees.md | 51 -------- ...atment-even-if-the-rollout-plan-changes.md | 87 -------------- ...it-the-number-of-users-in-an-experiment.md | 15 --- .../useful-regex-examples-for-targeting.md | 84 -------------- ...vs-custom-attributes-in-targeting-rules.md | 19 --- ...ween-default-rule-and-default-treatment.md | 26 ----- .../why-are-some-users-double-bucketed.md | 70 ----------- ...e-same-user-id-get-different-treatments.md | 19 --- .../maintaining-consistent-treatments.md | 96 +++++++++++++++ .../40-feature-management/segments.md | 27 ++++- .../static/create-date-1.png | Bin 0 -> 21215 bytes .../static/create-date-2.png | Bin 0 -> 47682 bytes .../static/create-date-3.png | Bin 0 -> 69238 bytes .../static/create-date-4.png | Bin 0 -> 76172 bytes .../static/create-date-5.png | Bin 0 -> 39969 bytes .../static/create-date-6.png | Bin 0 -> 16310 bytes .../40-feature-management/static/delete-1.png | Bin 0 -> 57372 bytes .../40-feature-management/static/delete-2.png | Bin 0 -> 24310 bytes .../40-feature-management/static/delete-3.png | Bin 0 -> 45991 bytes .../40-feature-management/static/delete-4.png | Bin 0 -> 22807 bytes .../static/delete-error.png | Bin 0 -> 38689 bytes .../does-my-sdk-version-support-semver.png | Bin .../static/dynamic-configuration-section.png | Bin .../40-feature-management/static/regex-1.png | Bin 0 -> 30795 bytes .../40-feature-management/static/regex-2.png | Bin 0 -> 28886 bytes .../40-feature-management/static/regex-3.png | Bin 0 -> 30262 bytes .../40-feature-management/static/regex-4.png | Bin 0 -> 29160 bytes .../40-feature-management/static/regex-5.png | Bin 0 -> 51487 bytes .../40-feature-management/static/rules-1.png | Bin 0 -> 67686 bytes .../40-feature-management/static/rules-2.png | Bin 0 -> 67258 bytes .../static/targeting-1.png | Bin 0 -> 30795 bytes .../static/targeting-2.png | Bin 0 -> 28886 bytes .../static/targeting-3.png | Bin 0 -> 30262 bytes .../static/targeting-4.png | Bin 0 -> 29160 bytes .../static/targeting-5.png | Bin 0 -> 51487 bytes .../static/treatment-1.png | Bin 0 -> 197798 bytes .../static/treatment-2.png | Bin 0 -> 119929 bytes .../static/use-case-1.png | Bin 0 -> 197798 bytes .../static/use-case-2.png | Bin 0 -> 119929 bytes .../target-with-custom-attributes.md | 109 +++++++++++++++++- .../targeting-an-account.md | 40 +++++++ .../viewing-user-treatments.md | 69 +++++++++++ .../60-experimentation/setup/index.md | 8 +- 72 files changed, 678 insertions(+), 709 deletions(-) create mode 100644 docs/feature-management-experimentation/10-getting-started/overview/boxes-demo.md rename docs/feature-management-experimentation/{40-feature-management/best-practices/shared => 10-getting-started/static}/boxes-split.txt (100%) rename docs/feature-management-experimentation/{40-feature-management/best-practices/shared => 10-getting-started/static}/boxes.htm (100%) rename docs/feature-management-experimentation/{40-feature-management/best-practices/shared => 10-getting-started/static}/create-box-split.sh.zip (100%) rename docs/feature-management-experimentation/{40-feature-management/best-practices => 10-getting-started}/static/split-boxes-chrome.png (100%) rename docs/feature-management-experimentation/{40-feature-management/best-practices => 10-getting-started}/static/split-boxes-demo.png (100%) delete mode 100644 docs/feature-management-experimentation/40-feature-management/best-practices/_category_.json delete mode 100644 docs/feature-management-experimentation/40-feature-management/best-practices/best-practices-when-targeting-an-account-or-organization.md delete mode 100644 docs/feature-management-experimentation/40-feature-management/best-practices/csv-file-comma.md delete mode 100644 docs/feature-management-experimentation/40-feature-management/best-practices/o-reilly-book.md delete mode 100644 docs/feature-management-experimentation/40-feature-management/best-practices/split-boxes-demo.md delete mode 100644 docs/feature-management-experimentation/40-feature-management/best-practices/why-setting-the-order-of-treatments-matters.md delete mode 100644 docs/feature-management-experimentation/40-feature-management/faqs/_category_.json delete mode 100644 docs/feature-management-experimentation/40-feature-management/faqs/cannot-delete-feature-flag-from-ui-even-after-deleting-the-targeting-rules.md delete mode 100644 docs/feature-management-experimentation/40-feature-management/faqs/dynamic-configuration-section-does-not-show-up.md delete mode 100644 docs/feature-management-experimentation/40-feature-management/faqs/ensure-a-consistent-user-experience.md delete mode 100644 docs/feature-management-experimentation/40-feature-management/faqs/how-can-i-override-individually-targeted-users-with-a-superseding-targeting-rule.md delete mode 100644 docs/feature-management-experimentation/40-feature-management/faqs/how-can-you-tell-what-treatment-a-user-sees.md delete mode 100644 docs/feature-management-experimentation/40-feature-management/faqs/how-do-i-maintain-the-state-of-a-users-treatment-even-if-the-rollout-plan-changes.md delete mode 100644 docs/feature-management-experimentation/40-feature-management/faqs/is-there-a-way-to-limit-the-number-of-users-in-an-experiment.md delete mode 100644 docs/feature-management-experimentation/40-feature-management/faqs/useful-regex-examples-for-targeting.md delete mode 100644 docs/feature-management-experimentation/40-feature-management/faqs/what-are-attributes-in-the-admin-api-vs-custom-attributes-in-targeting-rules.md delete mode 100644 docs/feature-management-experimentation/40-feature-management/faqs/what-is-the-difference-between-default-rule-and-default-treatment.md delete mode 100644 docs/feature-management-experimentation/40-feature-management/faqs/why-are-some-users-double-bucketed.md delete mode 100644 docs/feature-management-experimentation/40-feature-management/faqs/why-might-the-same-user-id-get-different-treatments.md create mode 100644 docs/feature-management-experimentation/40-feature-management/maintaining-consistent-treatments.md create mode 100644 docs/feature-management-experimentation/40-feature-management/static/create-date-1.png create mode 100644 docs/feature-management-experimentation/40-feature-management/static/create-date-2.png create mode 100644 docs/feature-management-experimentation/40-feature-management/static/create-date-3.png create mode 100644 docs/feature-management-experimentation/40-feature-management/static/create-date-4.png create mode 100644 docs/feature-management-experimentation/40-feature-management/static/create-date-5.png create mode 100644 docs/feature-management-experimentation/40-feature-management/static/create-date-6.png create mode 100644 docs/feature-management-experimentation/40-feature-management/static/delete-1.png create mode 100644 docs/feature-management-experimentation/40-feature-management/static/delete-2.png create mode 100644 docs/feature-management-experimentation/40-feature-management/static/delete-3.png create mode 100644 docs/feature-management-experimentation/40-feature-management/static/delete-4.png create mode 100644 docs/feature-management-experimentation/40-feature-management/static/delete-error.png rename docs/feature-management-experimentation/40-feature-management/{faqs => }/static/does-my-sdk-version-support-semver.png (100%) rename docs/feature-management-experimentation/40-feature-management/{faqs => }/static/dynamic-configuration-section.png (100%) create mode 100644 docs/feature-management-experimentation/40-feature-management/static/regex-1.png create mode 100644 docs/feature-management-experimentation/40-feature-management/static/regex-2.png create mode 100644 docs/feature-management-experimentation/40-feature-management/static/regex-3.png create mode 100644 docs/feature-management-experimentation/40-feature-management/static/regex-4.png create mode 100644 docs/feature-management-experimentation/40-feature-management/static/regex-5.png create mode 100644 docs/feature-management-experimentation/40-feature-management/static/rules-1.png create mode 100644 docs/feature-management-experimentation/40-feature-management/static/rules-2.png create mode 100644 docs/feature-management-experimentation/40-feature-management/static/targeting-1.png create mode 100644 docs/feature-management-experimentation/40-feature-management/static/targeting-2.png create mode 100644 docs/feature-management-experimentation/40-feature-management/static/targeting-3.png create mode 100644 docs/feature-management-experimentation/40-feature-management/static/targeting-4.png create mode 100644 docs/feature-management-experimentation/40-feature-management/static/targeting-5.png create mode 100644 docs/feature-management-experimentation/40-feature-management/static/treatment-1.png create mode 100644 docs/feature-management-experimentation/40-feature-management/static/treatment-2.png create mode 100644 docs/feature-management-experimentation/40-feature-management/static/use-case-1.png create mode 100644 docs/feature-management-experimentation/40-feature-management/static/use-case-2.png create mode 100644 docs/feature-management-experimentation/40-feature-management/targeting-an-account.md create mode 100644 docs/feature-management-experimentation/40-feature-management/viewing-user-treatments.md diff --git a/docs/feature-management-experimentation/10-getting-started/overview/boxes-demo.md b/docs/feature-management-experimentation/10-getting-started/overview/boxes-demo.md new file mode 100644 index 00000000000..d97122c8df6 --- /dev/null +++ b/docs/feature-management-experimentation/10-getting-started/overview/boxes-demo.md @@ -0,0 +1,69 @@ +--- +title: Explore How Feature Flags Affect User Targeting +sidebar_label: Explore How Feature Flags Affect User Targeting +description: Learn how to use this visualization tool to help you explore the effects of individual targeting, custom attributes, traffic allocation limits, and dynamic configurations on feature flags. +sidebar_position: 3 +redirect_from: + - /docs/feature-management-experimentation/feature-management/best-practices/split-boxes-demo/ +--- + +## Overview + +The Split Boxes demo is a tool to help users understand the interaction between rules and the impact of various features. It’s a simple visualization that allows you to see the impact of individually targeting, custom attribution, limit exposure, and dynamic configuration. + +## Using the Boxes Demo + +Each box represents a user ID. + +![](.././static/split-boxes-demo.png) + +* You can individually target using the cell location, such as b8 or j5. +* You can also create a segment that includes any of the available values. +* You can create targeting rules using the attributes **row**, **col**, or **account**; + + * _row_ and _col_ use letters and numbers respectively, usually with "is in list" as the matcher. + * Valid account names include: Nike, Apple, LinkedIn, Best Buy, Google, Microsoft, Pinterest, Dell, Slack, Zoom, Samsung, and Disney. + +* You can modify the configuration of the treatments by updating any of the values. The `font_size` expects standard HTML sizes such as medium, large, x-large, etc. + +## Setting up the Boxes Demo + +There are three files attached: + +* The HTML contains the SDK and can be run locally or on a server. +* You need to provide the browser API key for the Split environment where you will update the rollout plan. +* You also need to provide the feature flag name. These are entered as variables in the HTML: + + ```html + + ``` + + * The Boxes_split.txt file contains an example baseline definition of the feature flag. + * The feature flag can be created automatically using the `CreateBoxSplit.sh` script, which uses the Split Admin REST API and the `jq` tool. Run the script with this command line to create the feature flag and add definitions: + + ```css + CreateBoxSplit [Project Name] [Environment Name] [Traffic Type] [Split Name] [Admin API_KEY] + ``` + + Example: + + ```sql + CreateBoxSplit Default Production user front_end_choose_boxes 9enxxxxxxxxxxxxxxxxxxxxxx + ``` + +In Chrome, to see feature flag changes immediately, disable cache in the Network tab of the Developer Tools. + +![](.././static/split-boxes-chrome.png) + +## Downloads + +| File | Size | Notes | +| --------------------------------------------------------- | --------- | --------------------------------- | +| [CreateBoxSplit.sh.zip](.././static/create-box-split.sh.zip) | 1 KB | | +| [Boxes\_split.txt](.././static/boxes-split.txt) | 658 Bytes | *Right-click > Save Link As...* | +| [Boxes.htm](.././static/boxes.htm) | 8 KB | *Right-click > Save Link As...* | + + diff --git a/docs/feature-management-experimentation/10-getting-started/overview/build-a-resilient-integration.md b/docs/feature-management-experimentation/10-getting-started/overview/build-a-resilient-integration.md index b45467ca0e9..31192672b12 100644 --- a/docs/feature-management-experimentation/10-getting-started/overview/build-a-resilient-integration.md +++ b/docs/feature-management-experimentation/10-getting-started/overview/build-a-resilient-integration.md @@ -2,7 +2,7 @@ title: Build a Resilient Integration sidebar_label: Build a Resilient Integration description: Learn how to build a resilient integration with Harness FME. -sidebar_position: 7 +sidebar_position: 8 --- ## Overview diff --git a/docs/feature-management-experimentation/10-getting-started/overview/create-a-metric-alert-policy.md b/docs/feature-management-experimentation/10-getting-started/overview/create-a-metric-alert-policy.md index 47493ec22bd..05c471148fb 100644 --- a/docs/feature-management-experimentation/10-getting-started/overview/create-a-metric-alert-policy.md +++ b/docs/feature-management-experimentation/10-getting-started/overview/create-a-metric-alert-policy.md @@ -1,6 +1,6 @@ --- title: Create a Metric Alert Policy -sidebar_position: 5 +sidebar_position: 6 --- import AlertPolicies from '/docs/feature-management-experimentation/shared/alert-policies/index.mdx' diff --git a/docs/feature-management-experimentation/10-getting-started/overview/create-a-metric.md b/docs/feature-management-experimentation/10-getting-started/overview/create-a-metric.md index 31d2d554078..ae69d57a466 100644 --- a/docs/feature-management-experimentation/10-getting-started/overview/create-a-metric.md +++ b/docs/feature-management-experimentation/10-getting-started/overview/create-a-metric.md @@ -1,6 +1,6 @@ --- title: Create a Metric -sidebar_position: 4 +sidebar_position: 5 --- import MetricsSetup from '/docs/feature-management-experimentation/shared/metrics/setup/index.mdx' diff --git a/docs/feature-management-experimentation/10-getting-started/overview/create-an-experiment.md b/docs/feature-management-experimentation/10-getting-started/overview/create-an-experiment.md index 456e85c34c2..84ab0511036 100644 --- a/docs/feature-management-experimentation/10-getting-started/overview/create-an-experiment.md +++ b/docs/feature-management-experimentation/10-getting-started/overview/create-an-experiment.md @@ -2,7 +2,9 @@ title: Create an Experiment sidebar_label: Create an Experiment description: Learn how to create an experiment in Harness FME. -sidebar_position: 6 +sidebar_position: 7 +redirect_from: + - /docs/feature-management-experimentation/feature-management/faqs/is-there-a-way-to-limit-the-number-of-users-in-an-experiment --- ## Overview @@ -33,6 +35,19 @@ To create an A/B test in Harness FME: 1. Apply tags to help categorize your experiment (for example, by team, status, or feature area). 1. Click **Save**. +### Limiting the number of users in an experiment + +You can't directly cap the total number of users who will participate in an experiment. However, you can use the **Limit exposure** option to control the percentage of eligible users who are exposed to the experiment at any given time. + +This approach lets you: + +- Reduce risk when rolling out changes. +- Gather results from a smaller sample before expanding to all users. + +:::tip +Start with a lower exposure percentage (for example, 10%) to validate results, then increase it gradually. +::: + ## View experiment results Once your experiment is running, Harness FME automatically tracks key metrics and monitors the statistical significance of the results. diff --git a/docs/feature-management-experimentation/10-getting-started/overview/index.md b/docs/feature-management-experimentation/10-getting-started/overview/index.md index 8bd75150d14..3e64a686736 100644 --- a/docs/feature-management-experimentation/10-getting-started/overview/index.md +++ b/docs/feature-management-experimentation/10-getting-started/overview/index.md @@ -2,6 +2,8 @@ title: Overview sidebar_label: Overview description: How to make Feature Management & Experimentation work for you +redirect_from: + - /docs/feature-management-experimentation/feature-management/best-practices/o-reilly-book --- Harness Feature Management & Experimentation (FME) combines capabilities for feature delivery and control with built-in tools for measurement and learning. FME connects insightful data to every feature release and supports modern practices like continuous delivery and progressive delivery. @@ -142,6 +144,8 @@ Split has robust data pipelines and attribution logic. If you do find a mismatch Manage feature flag scheduling, flag sets, and flag lifecycles. Feature flags turn on features to specific users or segments. You can tailor access to beta testers and early adopters based on individual IDs, attributes, dependencies, or percentages. Gradually increase the rollout percentage to limit the blast radius of your releases. +In [this book](https://www.harness.io/resources/feature-flags-best-practices), Split CTO Pato Echague and Pete Hodgson explain how to implement feature-flagged software successfully, and offer some tips to developers on how to configure and manage a growing set of feature flags within your product, maintain them over time, manage infrastructure migrations, and more. + ### Release monitoring Release monitoring detects the impact of each feature on system performance and user behavior, starting with the earliest stage of a gradual rollout. With detection and triage done at the flag level, you can ship more often and with greater confidence. diff --git a/docs/feature-management-experimentation/10-getting-started/overview/manage-the-feature-flag-lifecycle.md b/docs/feature-management-experimentation/10-getting-started/overview/manage-the-feature-flag-lifecycle.md index 67e9f1737ed..58fd036440a 100644 --- a/docs/feature-management-experimentation/10-getting-started/overview/manage-the-feature-flag-lifecycle.md +++ b/docs/feature-management-experimentation/10-getting-started/overview/manage-the-feature-flag-lifecycle.md @@ -2,7 +2,7 @@ title: Manage the Feature Flag Lifecycle sidebar_label: Manage the Feature Flag Lifecycle description: Learn how to manage the feature flag lifecycle with Harness FME. -sidebar_position: 8 +sidebar_position: 9 --- ## Overview diff --git a/docs/feature-management-experimentation/10-getting-started/overview/send-event-data.md b/docs/feature-management-experimentation/10-getting-started/overview/send-event-data.md index 4ccd5cfb0dc..aee934624af 100644 --- a/docs/feature-management-experimentation/10-getting-started/overview/send-event-data.md +++ b/docs/feature-management-experimentation/10-getting-started/overview/send-event-data.md @@ -2,7 +2,7 @@ title: Send Event Data sidebar_label: Send Event Data description: Learn how to send event data to Harness FME. -sidebar_position: 3 +sidebar_position: 4 --- ## Overview diff --git a/docs/feature-management-experimentation/40-feature-management/best-practices/shared/boxes-split.txt b/docs/feature-management-experimentation/10-getting-started/static/boxes-split.txt similarity index 100% rename from docs/feature-management-experimentation/40-feature-management/best-practices/shared/boxes-split.txt rename to docs/feature-management-experimentation/10-getting-started/static/boxes-split.txt diff --git a/docs/feature-management-experimentation/40-feature-management/best-practices/shared/boxes.htm b/docs/feature-management-experimentation/10-getting-started/static/boxes.htm similarity index 100% rename from docs/feature-management-experimentation/40-feature-management/best-practices/shared/boxes.htm rename to docs/feature-management-experimentation/10-getting-started/static/boxes.htm diff --git a/docs/feature-management-experimentation/40-feature-management/best-practices/shared/create-box-split.sh.zip b/docs/feature-management-experimentation/10-getting-started/static/create-box-split.sh.zip similarity index 100% rename from docs/feature-management-experimentation/40-feature-management/best-practices/shared/create-box-split.sh.zip rename to docs/feature-management-experimentation/10-getting-started/static/create-box-split.sh.zip diff --git a/docs/feature-management-experimentation/40-feature-management/best-practices/static/split-boxes-chrome.png b/docs/feature-management-experimentation/10-getting-started/static/split-boxes-chrome.png similarity index 100% rename from docs/feature-management-experimentation/40-feature-management/best-practices/static/split-boxes-chrome.png rename to docs/feature-management-experimentation/10-getting-started/static/split-boxes-chrome.png diff --git a/docs/feature-management-experimentation/40-feature-management/best-practices/static/split-boxes-demo.png b/docs/feature-management-experimentation/10-getting-started/static/split-boxes-demo.png similarity index 100% rename from docs/feature-management-experimentation/40-feature-management/best-practices/static/split-boxes-demo.png rename to docs/feature-management-experimentation/10-getting-started/static/split-boxes-demo.png diff --git a/docs/feature-management-experimentation/20-sdks-and-infrastructure/client-side-sdks/javascript-sdk.md b/docs/feature-management-experimentation/20-sdks-and-infrastructure/client-side-sdks/javascript-sdk.md index 1c11d340c3d..73868d49bdb 100644 --- a/docs/feature-management-experimentation/20-sdks-and-infrastructure/client-side-sdks/javascript-sdk.md +++ b/docs/feature-management-experimentation/20-sdks-and-infrastructure/client-side-sdks/javascript-sdk.md @@ -1,6 +1,8 @@ --- title: JavaScript SDK sidebar_label: JavaScript SDK +redirect_from: + - /docs/feature-management-experimentation/feature-management/faqs/why-are-some-users-double-bucketed/ --- import Tabs from '@theme/Tabs'; @@ -1350,4 +1352,67 @@ ReactGA.pageview(window.location.pathname); The following example applications detail how to configure and instantiate the JavaScript SDK on commonly used platforms: * [Basic HTML](https://github.com/splitio/example-javascript-client) -* [AngularJS](https://github.com/splitio/angularjs-sdk-examples) \ No newline at end of file +* [AngularJS](https://github.com/splitio/angularjs-sdk-examples) + +## Troubleshooting + +### User IDs Being Double Bucketed (SDK_READY_TIMED_OUT Event Issue) + +Using the JavaScript SDK, some percentage of User IDs are double bucketed: the same User ID is processed in the Control block, and at a later call in an actual treatment block. + +One possible root cause is that the JavaScript SDK engine completes fetching treatments after the `requestTimeoutBeforeReady` or `readyTimeout` parameter expires, firing the browser event `SDK_READY_TIMED_OUT`. + +This tends to happen for mobile users with slow internet connections. + +If the JavaScript code does not properly handle this event—for example, if it only raises an error and exits: + +```javascript +var client = SdkFactory.client(); +this.clientReady = new Promise(function(resolve, reject) { + client.once(client.Event.SDK_READY, function() { + resolve(); + }); + client.once(client.Event.SDK_READY_TIMED_OUT, function() { + reject(new Error("Client SDK Ready Timed Out")); + }); +}); +``` + +There are two possible events: + +* If the `SDK_READY` event comes first, the promise resolves, and everything works as expected. +* If the `SDK_READY_TIMED_OUT` event comes first, the promise rejects and remains rejected, meaning that any `.catch()` attached will always be called—even if the SDK eventually becomes ready later. + +If you add a `.catch()` that does not return or throw an error, the wrapper code might continue executing as if the SDK is ready, even when it is not. For example: + +```javascript +this.clientReady.catch(() => {}).then(() => { +}); +``` + +Here, the `.catch()` swallows the error without returning or throwing, causing the promise chain to appear "recovered." This can cause code to run prematurely against an SDK that isn’t ready. + +Even if the `SDK_READY_TIMED_OUT` event fires, the SDK might become ready a few milliseconds later and emit the `SDK_READY` event. You should handle these events only when you actually want to respond to them. + +1. Allow the SDK to retry fetching treatments a couple of times before giving up, increasing the chance the SDK becomes ready within the timeout: + + ```javascript + startup: { + requestTimeoutBeforeReady: 5, // 5 seconds + readyTimeout: 5, // 5 seconds + retriesOnFailureBeforeReady: 2, // 2 retries + } + ``` + +1. Configure the SDK to store `Splits` and `mySegments` data in the browser’s `LOCALSTORAGE`. This caches data between page loads and reduces fetch time on subsequent page visits, making the SDK ready faster: + + ```javascript + storage: { + type: 'LOCALSTORAGE', + prefix: 'MYPREFIX' + }, + ``` + + Use a custom prefix to prevent data collision across projects. + +For more information, see the [API reference documentation](https://docs.split.io/docs/javascript-sdk-overview#section-configuration). \ No newline at end of file diff --git a/docs/feature-management-experimentation/40-feature-management/best-practices/_category_.json b/docs/feature-management-experimentation/40-feature-management/best-practices/_category_.json deleted file mode 100644 index 5dc379bfa40..00000000000 --- a/docs/feature-management-experimentation/40-feature-management/best-practices/_category_.json +++ /dev/null @@ -1,6 +0,0 @@ -{ - "label": "Best practices", - "collapsible": "true", - "collapsed": "true", - "className": "red" -} \ No newline at end of file diff --git a/docs/feature-management-experimentation/40-feature-management/best-practices/best-practices-when-targeting-an-account-or-organization.md b/docs/feature-management-experimentation/40-feature-management/best-practices/best-practices-when-targeting-an-account-or-organization.md deleted file mode 100644 index e7dcf5c92f6..00000000000 --- a/docs/feature-management-experimentation/40-feature-management/best-practices/best-practices-when-targeting-an-account-or-organization.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -title: Best practices when targeting an account or organization -sidebar_label: Best practices when targeting an account or organization -sidebar_position: 4 ---- - -import Link from "@docusaurus/Link"; - -Traffic types that target using a key for accounts or organizations (or schools or hospitals or...) as opposed to individual users are most often based on managing entitlements or for B2B applications. Of course, you can also target based on a department, plant, location or any level of granularity for which you have an associated key. We'll use 'account' as a proxy for all of the above. - -## Consistency of Experience - -When you want consistency of experience for all users within a single account, then use the account traffic type. This ensures that by providing a single ID - the account ID - you get the benefit of consistency without having to provide any complex data objects around users. - -If you want to measure the impact of a feature being rolled out by accounts through experimentation, avoid using SUM or COUNT metrics. As an example, say account A has 1,000 users but account B has two users. A metric that COUNTs or SUMs activity across these two accounts will be skewed in favor of the bigger account. Conversely, if you create metrics that measure AVERAGEs or PERCENTAGEs, data is normalized across accounts. - -As a B2B company, if you are OK with rolling out some of the features without the guarantee of consistency of experience for all users within a single account, then use a user traffic type. This also opens up a world of experimentation for you as you can measure SUM, COUNTs, AVERAGEs, PERCENTAGEs. - -Another option is to roll out a feature flag by user, but use company as a custom attribute to ensure everyone in specific (or all) companies get the same experience. This allows you to create a consistent experience within each organization, but still evaluate the results on a user by user basis. Of course, as noted above, you will not be able to control the distribution if some companies have far more users than others. More on that in [this article](/docs/feature-management-experimentation/feature-management/faqs/ensure-a-consistent-user-experience). - -These are tradeoffs that individual teams can make. You can roll out some features by accounts and others by users and Split allows you manage the experiences for each. \ No newline at end of file diff --git a/docs/feature-management-experimentation/40-feature-management/best-practices/csv-file-comma.md b/docs/feature-management-experimentation/40-feature-management/best-practices/csv-file-comma.md deleted file mode 100644 index ad72fede326..00000000000 --- a/docs/feature-management-experimentation/40-feature-management/best-practices/csv-file-comma.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: How to upload CSV file that contains IDs with comma character to new segment? -sidebar_label: How to upload CSV file that contains IDs with comma character to new segment? -sidebar_position: 1 ---- - -### Question - -Using the CSV upload feature in segment page in Split user interface, is it possible to upload user IDs in the CSV file that contain comma? The standard escape for CSV comma values is encapsulating the column value with double quotes like the example below: -``` -"user1, key1" -"user2, key2" -"user3, key3" -``` - -### Answer - -The CSV upload functionality in Split user interface automatically considers each line as a unique user id, so there is no need to add the double quotes, as they are added to the final user IDs that are imported to a Split segment. To use the example above, remove the double quotes, as below: -``` -user1, key1 -user2, key2 -user3, key3 -``` \ No newline at end of file diff --git a/docs/feature-management-experimentation/40-feature-management/best-practices/o-reilly-book.md b/docs/feature-management-experimentation/40-feature-management/best-practices/o-reilly-book.md deleted file mode 100644 index 4f996eef7b5..00000000000 --- a/docs/feature-management-experimentation/40-feature-management/best-practices/o-reilly-book.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -title: "O'Reilly book: Feature Flag Best Practices" -sidebar_label: "O'Reilly book: Feature Flag Best Practices" -sidebar_position: 2 ---- - -import Link from "@docusaurus/Link"; - -In [this book](https://try.split.io/hubfs/pdfs/oreilly-feature-flag-best-practices/OReilly_and_Split_Feature_Flag_Best_Practices.pdf), Split CTO Pato Echague and Pete Hodgson explain how to implement feature-flagged software successfully, and offer some tips to developers on how to configure and manage a growing set of feature flags within your product, maintain them over time, manage infrastructure migrations, and more. \ No newline at end of file diff --git a/docs/feature-management-experimentation/40-feature-management/best-practices/split-boxes-demo.md b/docs/feature-management-experimentation/40-feature-management/best-practices/split-boxes-demo.md deleted file mode 100644 index fa90e41153c..00000000000 --- a/docs/feature-management-experimentation/40-feature-management/best-practices/split-boxes-demo.md +++ /dev/null @@ -1,55 +0,0 @@ ---- -title: Split Boxes Demo -sidebar_label: Split Boxes Demo -helpdocs_is_private: false -helpdocs_is_published: true -sidebar_position: 5 ---- - -import Link from "@docusaurus/Link"; - -The Split Boxes demo is a tool to help users understand the interaction between rules and the impact of various features. It's a simple visualization that allows you to see the impact of individually targeting, custom attribution, limit exposure, and dynamic configuration. - -## Using the Boxes Demo - -Each box represents a user ID. - -![](./static/split-boxes-demo.png) - -You can individually target using the cell location, such as b8 or j5. You can also create a segment that includes any of the available values. - -You can create targeting rules using the attributes row, col, or account; row and col will use letters and numbers respectively, usually with 'is in list' as the matcher. Valid account names include Nike, Apple, LinkedIn, Best Buy, Google, Microsoft, Pinterest, Dell, Slack, Zoom, Samsung and Disney. - -You can modify the configuration of the treatments by updating any of the values. The font_size expects standard HTML sizes, such as medium, large, x-large, etc. - -## Setting up the Boxes Demo - -There are three files attached. The HTML contains the SDK and can be run locally or on a server. You need to provide the browser API key for whichever Split environment in which you will be updating the rollout plan. You also need to provide the name of the feature flag. These are entered as vars in the HTML. - -```html -