mirror of
https://github.com/Unleash/unleash.git
synced 2024-12-28 00:06:53 +01:00
415e1b0596
## What The main purpose of this PR is to 1. Delete the proxy docs in this repo and replace them with the proxy's GitHub readme. 2. Add the docs for Unleash Edge. ### Detailed change description This PR contains a lot of small changes in a large number of files. To make it easier to get an overview, here's a detailed description of what happens where: #### In the `website/docs`directory Except for the deletion of the proxy doc, all changes in this directory are rewriting internal links, so that they point to the newly generated document instead. #### `package.json` and `yarn.lock` When including the documentation for Edge, we also want to render the mermaid diagrams it uses. Docusaurus supports this via a plugin. All changes in these files are related to installing that plugin. #### `docusaurus.config.js` There's two types of changes in this file: 1. Mermaid-related changes: we ask docusaurus to render mermaid in markdown files and add the plugin 2. Document generation. There's some rewrites to the sdk doc generation plus an entirely new section that generates docs for Edge and the proxy #### `sidebars.js` Two things: 1. Add the edge docs 2. Move both the Edge and the proxy docs up a level, so that they're directly under "reference docs" instead of nested inside "unleash concepts". #### In the `website/remote-content` directory These are the remote content files. Previously, all of this lived only in a `readme-fns.js` file, but with the introduction of Edge and proxy docs, this has been moved into its own directory and refactored into three files (`shared`, `sdks`, `edge-proxy`). #### `custom.css` Style updates to center mermaid diagrams and provide more space around them. #### In `static/img` The image files that were included in the proxy doc and that have been deleted. ## Why For two reasons: 1. Reduce duplication for the proxy. Have one source of truth. 2. Add docs for edge. ## Discussion points and review wishes This is a big PR, and I don't expect anyone to do a line-by-line review of it, nor do I think that is particularly useful. Instead, I'd like to ask reviewers to: 1. Visit the [documentation preview](https://unleash-docs-git-docs-source-proxy-gh-unleash-team.vercel.app/reference/unleash-proxy) and have a look at both the proxy docs and the Edge docs. Potentially have a look at the SDK docs too to verify that everything still works. 2. Consider whether they think moving the proxy and edge docs up a level (in the sidebar) makes sense. 3. Let me know what slug they'd prefer for the Edge docs. I've gone with `unleash-edge` for now (so that it's `docs.getunleash.io/reference/unleash-edge`), but we could potentially also just use `edge`. WDYT? 4. Read through the detailed changes section. 5. Let me know if they have any other concerns or questions. ## Screenies The new proxy doc:  The new edge doc: 
68 lines
5.2 KiB
Markdown
68 lines
5.2 KiB
Markdown
---
|
|
title: Custom Activation Strategies
|
|
---
|
|
|
|
:::tip
|
|
|
|
This document is a reference for custom activation strategies. If you're looking for a guide on how to use them, see the [_how to use custom strategies_ guide](../how-to/how-to-use-custom-strategies.md).
|
|
|
|
:::
|
|
|
|
**Custom activation strategies** let you define your own activation strategies to use with Unleash. When the [built-in activation strategies](../reference/activation-strategies.md) aren't enough, custom activation strategies are there to provide you with the flexibility you need.
|
|
|
|
Custom activation strategies work exactly like the built-in activation strategies when working in the admin UI.
|
|
|
|
## Definition
|
|
|
|
|
|
|
|
You define custom activation strategies on your Unleash instance, either via the admin UI or via the API. A strategy contains:
|
|
|
|
- A strategy **name**: You'll use this to refer to the strategy in the UI and in code. The strategy name should make it easy to understand what the strategy does. For instance, if a strategy uses contact numbers to determine whether a feature should be enabled, then _ContactNumbers_ would be a good name.
|
|
- An optional **description**: Use this to describe what the strategy should do.
|
|
- An optional list of **parameters**: The parameter list lets you pass arguments to your custom activation strategy. These will be made available to your custom strategy implementation. How you interact with them differs between SDKs, but refer to the [Node.js example in the how-to guide](../how-to/how-to-use-custom-strategies.md) for a rough idea.
|
|
|
|
The strategy **name** is the only required parameter, but adding a good **description** will make it easier to remember what a strategy should do. The list of **parameters** lets you pass data from the Unleash instance to the strategy implementation.
|
|
|
|
### Parameters
|
|
|
|
|
|
|
|
Parameters let you provide arguments to your strategy that it can access for evaluation. When creating a strategy, each parameter can be either required or optional. This marking is to help the user understand what they need to fill out; they can still save the strategy without filling out a required field.
|
|
|
|
Each parameter consists of three parts:
|
|
|
|
- a **name**: must be unique among the strategy's parameters.
|
|
- an optional **description**: describe the purpose or format of the parameter.
|
|
- a parameter **type**: dictates the kind of input field the user will see in the admin UI and the type of the value in the implementation code.
|
|
|
|
#### Parameter types
|
|
|
|
Each parameter has one of five different parameter types. A parameter's type impacts the kind of controls shown in the admin UI and how it's represented in code.
|
|
|
|
The below table lists the types and how they're represented in the JSON payload returned from the Unleash server. When parsed, the exact types will vary based on your programming language's type system.
|
|
|
|
All values have an **empty string (`""`) as the default value**. As such, if you don't interact with a control or otherwise set a value, the value will be an empty string.
|
|
|
|
| type name | code representation | example value | UI control |
|
|
| --- | --- | --- | --- |
|
|
| string | `string` | `"a string"` | A standard input field |
|
|
| percentage | a `string` representing a number between 0 and 100 (inclusive) | `"99"` | A value slider |
|
|
| list | `string` (values are comma-separated) | `"one,two"` | A multi-input text field |
|
|
| number | `string` | `"123"` | A numeric text field |
|
|
| boolean | a `string`: one of `"true"` or `"false"` | `"true"` | An on/off toggle |
|
|
|
|
## Implementation
|
|
|
|
:::note
|
|
|
|
If you have not implemented the strategy in your client SDK, the check will always return `false` because the client doesn't recognize the strategy.
|
|
|
|
:::
|
|
|
|
While custom strategies are _defined_ on the Unleash server, they must be _implemented_ on the client. All official Unleash client SDKs provide a way for you to implement custom strategies. You should refer to the individual SDK's documentation for specifics, but for an example, you can have a look at the [_Node.js client implementation_ section in the _how to use custom strategies_ guide](../how-to/how-to-use-custom-strategies.md#step-3-a).
|
|
|
|
The exact method for implementing custom strategies will vary between SDKs, but the server SDKs follow the same patterns. For front-end client SDKs ([Android](/docs/generated/sdks/client-side/android-proxy.md), [JavaScript](/docs/generated/sdks/client-side/javascript-browser.md), [React](/docs/generated/sdks/client-side/react.md), [iOS](/docs/generated/sdks/client-side/ios-proxy.md), [Flutter](/docs/generated/sdks/client-side/flutter.md)), the custom activation strategy must be implemented in the [Unleash Proxy](../generated/unleash-proxy.md).
|
|
|
|
When implementing a strategy in your client, you will get access to the strategy's parameters and the Unleash Context. Again, refer to your specific SDK's documentation for more details.
|