Merge pull request #1124 from Unleash/docs/add-stickiness

docs: document stickiness

website/docs/activation-strategies.md

@@ -1,88 +0,0 @@
----
-id: activation_strategy
-title: Activation Strategies
----
-
-It is powerful to be able to turn a feature on and off instantaneously, without redeploying the application. The next level of control comes when you are able to enable a feature for specific users or enable it for a small subset of users. We achieve this level of control with the help of activation strategies. The most straightforward strategy is the “default” strategy, which basically means that the feature should be enabled to everyone.
-
-The definition of an activation strategy lives in the Unleash API and can be created via the Unleash UI. The implementation of activation strategies lives in various client implementations.
-
-Unleash comes with a few common activation strategies. Some of them require the client to provide the [unleash-context](./unleash-context.md), which gives the necessary context for Unleash.
-
-## default {#default}
-
-It is the simplest activation strategy and basically means "active for everyone".
-
-## userWithId {#userwithid}
-
-Active for users with a `userId` defined in the `userIds` list. Typically I want to enable a new feature only for myself in production before I enable it for everyone else. To achieve this, we can use the “UserWithIdStrategy”. This strategy allows you to specify a list of user IDs that you want to expose the new feature for. (A user id may, of course, be an email if that is more appropriate in your system.)
-
-**Parameters**
-
-- userIds - _List of user IDs you want the feature toggle to be enabled for_
-
-## flexibleRollout {#flexiblerollout}
-
-A flexible rollout strategy which combines all gradual rollout strategies in to a single strategy (and will in time replace them). This strategy have different options for how you want to handle the stickiness, and have sane default mode.
-
-**Parameters**
-
-- **stickiness** is used to define how we guarantee consistency for gradual rollout. The same userId and the same rollout percentage should give predictable results. Configuration that should be supported:
-  - **default** - Unleash chooses the first value present on the context in defined order userId, sessionId, random.
-  - **userId** - guaranteed to be sticky on userId. If userId not present the behavior would be false
-  - **sessionId** - guaranteed to be sticky on sessionId. If sessionId not present the behavior would be false.
-  - **random** - no stickiness guaranteed. For every isEnabled call it will yield a random true/false based on the selected rollout percentage.
-- **groupId** is used to ensure that different toggles will **hash differently** for the same user. The groupId defaults to _feature toggle name_, but the use can override it to _correlate rollout_ of multiple feature toggles.
-- **rollout** The percentage (0-100) you want to enable the feature toggle for.
-
-### Customize stickiness (beta) {#customize-stickiness-beta}
-
-By enabling the stickiness option on a custom context field you can use it together with the flexible rollout strategy. This will guarantee a consistent behavior for specific values of this context field. PS! support for this feature currently being supported by the following SDKs:
-
-- [unleash-client-node](https://github.com/Unleash/unleash-client-node) (from v3.6.0)
-
-## gradualRolloutUserId {#gradualrolloutuserid}
-
-The `gradualRolloutUserId` strategy gradually activates a feature toggle for logged-in users. Stickiness is based on the user ID. The strategy guarantees that the same user gets the same experience every time across devices. It also assures that a user which is among the first 10% will also be among the first 20% of the users. That way, we ensure the users get the same experience, even if we gradually increase the number of users exposed to a particular feature. To achieve this, we hash the user ID and normalize the hash value to a number between 1 and 100 with a simple modulo operator.
-
-![hash_and_normalise](/img/hash_and_normalise.png)
-
-Starting from v3.x all clients should use the 32-bit [MurmurHash3](https://en.wikipedia.org/wiki/MurmurHash) algorithm to normalize values. ([issue 247](https://github.com/Unleash/unleash/issues/247))
-
-**Parameters**
-
-- percentage - _The percentage (0-100) you want to enable the feature toggle for._
-- groupId - _Used to define an activation group, which allows you to correlate rollout across feature toggles._
-
-## gradualRolloutSessionId {#gradualrolloutsessionid}
-
-Similar to `gradualRolloutUserId` strategy, this strategy gradually activates a feature toggle, with the exception being that the stickiness is based on the session IDs. This makes it possible to target all users (not just logged-in users), guaranteeing that a user will get the same experience within a session.
-
-**Parameters**
-
-- percentage - _The percentage (0-100) you want to enable the feature toggle for._
-- groupId - _Used to define an activation group, which allows you to correlate rollout across feature toggles._
-
-## gradualRolloutRandom {#gradualrolloutrandom}
-
-The `gradualRolloutRandom` strategy randomly activates a feature toggle and has no stickiness. We have found this rollout strategy very useful in some scenarios, especially when we enable a feature which is not visible to the user. It is also the strategy we use to sample metrics and error reports.
-
-**Parameters**
-
-- percentage - _The percentage (0-100) you want to enable the feature toggle for._
-
-## remoteAddress {#remoteaddress}
-
-The remote address strategy activates a feature toggle for remote addresses defined in the IP list. We occasionally use this strategy to enable a feature only for IPs in our office network.
-
-**Parameters**
-
-- IPs - _List of IPs to enable the feature for._
-
-## applicationHostname {#applicationhostname}
-
-The application hostname strategy activates a feature toggle for client instances with a hostName in the `hostNames` list.
-
-**Parameters**
-
-- hostNames - _List of hostnames to enable the feature toggle for._

website/docs/advanced/custom-activation-strategy.md

@@ -3,7 +3,7 @@ id: custom_activation_strategy
 title: Custom Activation Strategy
 ---
 
-Even though Unleash comes with a few powerful [activation strategies](activation-strategies.md) there might be scenarios where you would like to extend Unleash with your own custom strategies.
+Even though Unleash comes with a few powerful [activation strategies](../user_guide/activation-strategies.md) there might be scenarios where you would like to extend Unleash with your own custom strategies.
 
 ### Example: TimeStamp Strategy {#example-timestamp-strategy}
 

website/docs/advanced/stickiness.md

@@ -0,0 +1,36 @@
+---
+id: stickiness
+title: Stickiness
+---
+
+_Stickiness_ is how Unleash guarantees that the same user gets the same features every time. Stickiness is useful in any scenario where you want to either show a feature to only a subset of users or give users a variant of a feature.
+
+## Calculation
+
+By default, Unleash calculates stickiness based on the user id and the group id. If the user id is unavailable, it falls back to using the session id instead. It hashes these values to a number between 0 and 100 using the [MurmurHash hash function](https://en.wikipedia.org/wiki/MurmurHash). This number is what determines whether a user will see a specific feature or variant. Because the process is deterministic, the same user will always get the same number.
+
+If both the user id and the session id is unavailable, the calculation returns a random value and stickiness is not guaranteed.
+
+## Consistency
+
+Because the number assigned to a user won't change, Unleash also guarantees that the a user will keep seeing the same features even if certain other parameters change.
+
+For instance: When using the [gradual rollout activation strategy](../user_guide/activation-strategies.md#gradual-rollout), any user whose number is less than or equal to the rollout percentage will see the feature. This means that the same users will keep seeing the feature even as you increase the percentage of your user base that sees the feature.
+
+## Custom stickiness (beta)
+
+:::info
+Custom stickiness is available starting from Unleash Enterprise v4.
+:::
+
+When using [the gradual rollout strategy](../user_guide/activation-strategies.md#gradual-rollout) or [feature toggle variants](./feature-toggle-variants.md), you can use parameters other than the user id to calculate stickiness. More specifically, you can use any field, custom or otherwise, of the [Unleash Context](../user_guide/unleash-context.md) as long as you have enabled custom stickiness for these fields.
+
+:::note
+This is a beta featue, so not all client SDKs support this feature yet. Check your SDK's documentation to learn more.
+:::
+
+### Enabling custom stickiness
+
+To enable custom stickiness on a field, navigate to the Create Context screen in the UI and find the field you want to enable. There's a "Custom stickiness" option at the bottom of the form. Enable this toggle and update the context field by pressing the "Update" button.
+
+![The Create Context screen in the Unleash UI. There's a toggle at the bottom to control custom stickiness.](/img/enable_custom_stickiness.png)

website/docs/api/client/feature-toggles-api.md

@@ -117,7 +117,7 @@ Used to fetch details about a specific feature toggle. This is mainly provided t
 
 > This is a unleash-enterprise feature
 
-Strategy definitions may also contain a `constraints` property. Strategy constraints is a feature in Unleash which work on context fields, which is defined as part of the [Unleash Context](/unleash_context). The purpose is to define a set of rules where all needs to be satisfied in order for the activation strategy to . A [high level description](https://www.unleash-hosted.com/articles/strategy-constraints) of it is available online.
+Strategy definitions may also contain a `constraints` property. Strategy constraints is a feature in Unleash which work on context fields, which is defined as part of the [Unleash Context](../../user_guide/unleash-context.md). The purpose is to define a set of rules where all needs to be satisfied in order for the activation strategy to evaluate to true. A [high level description](https://www.unleash-hosted.com/articles/strategy-constraints) of it is available online.
 
 **Example response:**
 

website/docs/client-specification.md

@@ -94,7 +94,7 @@ function isEnabled(name, unleashContext = {}, defaultValue = false) {
 
 Activation strategies are defined and configured in the unleash-service. It is up to the client to provide the actual implementation of each activation strategy.
 
-Unleash also ships with a few built-in strategies, and expects client SDK's to implement these. Read more about these [activation strategies](activation-strategies.md). For the built-in strategies to work as expected the client should also allow the user to define an [unleash-context](unleash-context.md). The context should be possible to pass in as part of the `isEnabled` call.
+Unleash also ships with a few built-in strategies, and expects client SDK's to implement these. Read more about these [activation strategies](user_guide/activation-strategies.md). For the built-in strategies to work as expected the client should also allow the user to define an [unleash-context](user_guide/unleash-context.md). The context should be possible to pass in as part of the `isEnabled` call.
 
 ### Extension points {#extension-points}
 

website/docs/sdks/go.md

@@ -65,7 +65,7 @@ The Go client comes with implementations for the built-in activation strategies
 - RemoteAddressStrategy
 - ApplicationHostnameStrategy
 
-Read more about the strategies in [activation-strategy.md](/activation_strategy).
+Read more about the strategies in [the activation strategies document](../user_guide/activation_strategy).
 
 ### Unleash context {#unleash-context}
 

website/docs/unleash-context.md

@@ -1,21 +0,0 @@
----
-id: unleash_context
-title: Unleash Context
----
-
-To standardise a few activation strategies, we also needed to standardise the Unleash context, which contains fields that vary per request, required to implement the activation strategies.
-
-The unleash context is defined by these fields:
-
-- userId: String,
-- sessionId: String,
-- remoteAddress: String,
-- properties: Map<String, String>
-- appName: String
-- environment: String
-
-All fields are optional, but if they are not set you will not be able to use certain activation strategies.
-
-E.g., the `userWithId` strategy obviously depends on the `userId` field.
-
-The `properties` field is more generic and can be used to provide more arbitrary data to strategies. Typical usage is to add more metadata. For instance, the `betaUser` strategy may read a field from `properties` to check whether the current user is a beta user.

website/docs/user_guide/activation-strategies.md

@@ -40,7 +40,7 @@ A flexible rollout strategy which combines all gradual rollout strategies in to
   - **userId** - guaranteed to be sticky on userId. If userId not present the behavior would be false
   - **sessionId** - guaranteed to be sticky on sessionId. If sessionId not present the behavior would be false.
   - **random** - no stickiness guaranteed. For every isEnabled call it will yield a random true/false based on the selected rollout percentage.
-- **groupId** is used to ensure that different toggles will **hash differently** for the same user. The groupId defaults to _feature toggle name_, but the use can override it to _correlate rollout_ of multiple feature toggles.
+- **groupId** is used to ensure that different toggles will **hash differently** for the same user. The groupId defaults to _feature toggle name_, but the user can override it to _correlate rollout_ of multiple feature toggles.
 - **rollout** The percentage (0-100) you want to enable the feature toggle for.
 
 This strategy has the following modelling name in the code:

website/docs/user_guide/whats-new-v4.md

@@ -51,4 +51,5 @@ In version 4 we improved the API Access and made it available for Unleash Open-S
 
 ### Custom stickiness {#custom-stickiness}
 
-In Unleash Enterprise v4 you can configure stickiness when you are doing a gradual rollout with the "flexible rollout" strategy or together with feature toggle variants. This means that you can now have consistent behavior based on any field available on the [Unleash context](unleash-context.md).
+In Unleash Enterprise v4 you can configure stickiness when you are
+doing a gradual rollout with the "gradual rollout" strategy (previously known as "flexible rollout") or together with feature toggle variants. This means that you can now have consistent behavior based on any field available on the [Unleash context](unleash-context.md).

website/sidebars.js

@@ -54,6 +54,7 @@ module.exports = {
             'advanced/custom_activation_strategy',
             'advanced/feature_toggle_types',
             'advanced/toggle_variants',
+            'advanced/stickiness',
             'advanced/archived_toggles',
             'advanced/audit_log',
             'advanced/api_access',