Skip to content

docs(flagsmith): Improve README #872

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Jul 8, 2024
Merged

docs(flagsmith): Improve README #872

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
4823e7f
docs(flagsmith): Improve README
rolodato Jul 6, 2024
2d03537
Merge branch 'main' into flagsmith-readme
toddbaert Jul 8, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
68 changes: 33 additions & 35 deletions providers/flagsmith/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,14 +1,14 @@
# 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

<!-- x-release-please-start-version -->

```xml

<dependency>
<groupId>dev.openfeature.contrib.providers</groupId>
<artifactId>flagsmith</artifactId>
Expand All @@ -20,24 +20,46 @@ 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:

| 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<String, String> | | 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.
Expand All @@ -46,35 +68,11 @@ 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.
| sslSocketFactory | SSLSocketFactory | | Override the sslSocketFactory.
| 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);
```
| 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.