From 1ce5ea5112078cc1686565034b7de4da77cb9f19 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Rodrigo=20L=C3=B3pez=20Dato?= Date: Mon, 8 Jul 2024 14:28:22 -0300 Subject: [PATCH] docs(flagsmith): Improve README (#872) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Rodrigo López Dato Co-authored-by: Todd Baert --- providers/flagsmith/README.md | 68 +++++++++++++++++------------------ 1 file changed, 33 insertions(+), 35 deletions(-) diff --git a/providers/flagsmith/README.md b/providers/flagsmith/README.md index 2902a6f42..180e20fbc 100644 --- a/providers/flagsmith/README.md +++ b/providers/flagsmith/README.md @@ -1,6 +1,7 @@ # Flagsmith OpenFeature Java Provider ![Experimental](https://img.shields.io/badge/experimental-breaking%20changes%20allowed-yellow) [![Download](https://img.shields.io/maven-central/v/com.flagsmith/flagsmith-java-client)](https://mvnrepository.com/artifact/com.flagsmith/flagsmith-java-client) + Flagsmith provides an all-in-one platform for developing, implementing, and managing your feature flags. ## Installation @@ -8,7 +9,6 @@ Flagsmith provides an all-in-one platform for developing, implementing, and mana ```xml - dev.openfeature.contrib.providers flagsmith @@ -20,17 +20,35 @@ Flagsmith provides an all-in-one platform for developing, implementing, and mana ## Usage -The `FlagsmithProvider` communicates with Flagsmith using the Flagsmith java sdk. Information on the sdk can be found in -the Flagsmith documentaiton here https://docs.flagsmith.com/clients/server-side. The following code snippet shows how to -initialize the `FlagsmithProvider`: +The `FlagsmithProvider` communicates with Flagsmith using the [Flagsmith Java SDK](https://docs.flagsmith.com/clients/server-side?language=java). +This example shows how to initialize and use the Flagsmith OpenFeature provider: ```java -FlagsmithProviderOptions options = FlagsmithProviderOptions.builder() - .apiKey("API_KEY") - .build(); - -FlagsmithProvider provider = new FlagsmithProvider(); -OpenFeatureAPI.getInstance().setProvider(provider); +import dev.openfeature.contrib.providers.flagsmith.FlagsmithProvider; +import dev.openfeature.contrib.providers.flagsmith.FlagsmithProviderOptions; +import dev.openfeature.sdk.Client; +import dev.openfeature.sdk.MutableContext; +import dev.openfeature.sdk.OpenFeatureAPI; + +public class FlagsmithExample { + public static void main(String[] args) { + FlagsmithProviderOptions options = FlagsmithProviderOptions.builder() + .apiKey("API_KEY") + .build(); + + FlagsmithProvider provider = new FlagsmithProvider(options); + OpenFeatureAPI api = OpenFeatureAPI.getInstance(); + api.setProvider(provider); + + // Optional: set a targeting key and traits to use segment and/or identity overrides + MutableContext evaluationContext = new MutableContext(); + evaluationContext.setTargetingKey("my-identity-id"); + + Client client = api.getClient(); + boolean flag = client.getBooleanValue("my-boolean-flag", false, evaluationContext); + System.out.println(flag); + } +} ``` Options can be defined using the FlagsmithProviderOptions builder. Below are all the options: @@ -38,6 +56,10 @@ Options can be defined using the FlagsmithProviderOptions builder. Below are all | Option name | Type | Default | Description | ----------- | ------- | --------- | --------- | apiKey | String | | Your API Token. Note that this is either the `Environment API` key or the `Server Side SDK Token` +| baseUri | String | https://edge.api.flagsmith.com/api/v1/ | Override the default Flagsmith API URL if you are self-hosting. +| localEvaluation | boolean | false | Controls which mode to run in; [local or remote evaluation](https://docs.flagsmith.com/clients/overview#server-side-sdks). +| environmentRefreshIntervalSeconds | int | 60 | Set environment refresh rate when using local evaluation mode +| enableAnalytics | boolean | false | Controls whether [Flag Analytics](https://docs.flagsmith.com/advanced-use/flag-analytics) data is sent to the Flagsmith API | headers | HashMap | | Add custom headers which will be sent with each network request to the Flagsmith API. | envFlagsCacheKey | String | | Enable in-memory caching for the Flagsmith API. | expireCacheAfterWriteTimeUnit | TimeUnit | TimeUnit.MINUTES | The time unit used for cache expiry after write. @@ -46,7 +68,6 @@ Options can be defined using the FlagsmithProviderOptions builder. Below are all | expireCacheAfterAccess | int | -1 | The integer time for cache expiry after reading. | maxCacheSize | int | -1 | The maximum size of the cache in MB. | recordCacheStats | boolean | false | Whether cache statistics should be recorded. -| baseUri | String | https://edge.api.flagsmith.com/api/v1/ | Override the default Flagsmith API URL if you are self-hosting. | connectTimeout | int | 2000 | The network timeout in milliseconds. | writeTimeout | int | 5000 | The network timeout in milliseconds when writing. | readTimeout | int | 5000 | The network timeout in milliseconds when reading. @@ -54,27 +75,4 @@ Options can be defined using the FlagsmithProviderOptions builder. Below are all | trustManager | X509TrustManager | | X509TrustManager used when overriding the sslSocketFactory. | httpInterceptor | Interceptor | | Add a custom HTTP interceptor in the form of an okhttp3.Interceptor object. | retries | int | 3 | Add a custom com.flagsmith.config.Retry object to configure the backoff / retry configuration. -| localEvaluation | boolean | false | Controls which mode to run in; local or remote evaluation. -| environmentRefreshIntervalSeconds | int | 60 | Set environment refresh rate with polling manager. -| enableAnalytics | boolean | false | Controls whether Flag Analytics data is sent to the Flagsmith API -| usingBooleanConfigValue | boolean | false | Determines whether to resolve a feature value as a boolean or use the isFeatureEnabled as the flag itself. These values will be false and true respectively. - -### Identity flags - -In order to use specific identity flags, a targeting key must be provided in the EvaluationContext provided to the flag -evaluation method. An example of this can be seen below: - -```java -FlagsmithProviderOptions options = FlagsmithProviderOptions.builder() - .apiKey("API_KEY") - .build(); - -FlagsmithProvider provider = new FlagsmithProvider(); -OpenFeatureAPI.getInstance().setProvider(provider); - -EvaluationContext evaluationContext = new MutableContext(); -evaluationContext.setTargetingKey("my-identity"); - -Client client = api.getClient(); -boolean flag = client.getBooleanValue("key", false); -``` \ No newline at end of file +| usingBooleanConfigValue | boolean | false | Determines whether to resolve a feature value as a boolean or use the isFeatureEnabled as the flag itself. These values will be false and true respectively. \ No newline at end of file