docs: Flagsmith integration

README.md

@@ -19,7 +19,7 @@
 
 # [Flagsmith](https://flagsmith.com/) is an Open-Source Feature Flagging Tool to Ship Faster & Control Releases 
 
-Change the way your team releases software. Roll out, segment, and optimise—with granular control. Stay secure with on-premise and private cloud hosting.
+Change the way your team releases software. Roll out, segment, and optimise—with granular control. Stay secure with on-premise and private cloud hosting. 
 
 * Feature flags: Release features behind the safety of a feature flag
 * Make changes remotely: Easily toggle individual features on and off, and make changes without deploying new code

docs/docs/flagsmith-integration/CLI.md

@@ -0,0 +1,48 @@
+---
+description: Flagsmith Command Line Interface (CLI)
+sidebar_label: CLI
+sidebar_position: 40
+---
+
+# Flagsmith CLI
+
+Flagsmith has a [CLI tool](https://github.com/Flagsmith/flagsmith-cli) that you can use to help in your development
+workflows.
+
+## Installation
+
+Install globally:
+
+```bash
+npm install -g flagsmith-cli
+```
+
+## Sample Usage
+
+```bash
+USAGE
+  $ flagsmith get [ENVIRONMENT] [-o <value>] [-a <value>] [-i <value>]
+
+ARGUMENTS
+  ENVIRONMENT  The flagsmith environment key to use,
+  defaults to the environment variable FLAGSMITH_ENVIRONMENT
+
+FLAGS
+  -a, --api=<value>       The API URL to fetch the feature flags from
+  -i, --identity=<value>  The identity for which to fetch feature flags
+  -o, --output=<value>    [default: ./flagsmith.json] The file path output
+
+DESCRIPTION
+  Retrieve flagsmith feature flags from the Flagsmith API and output them to a file.
+
+EXAMPLES
+  $ FLAGSMITH_ENVIRONMENT=x flagsmith get
+
+  $ flagsmith get <ENVIRONMENT_ID>
+
+  $ flagsmith get --o ./my-file.json
+
+  $ flagsmith get --a https://flagsmith.example.com/api/v1/
+
+  $ flagsmith get --i flagsmith_identity
+```

docs/docs/flagsmith-integration/_category_.json

@@ -0,0 +1,5 @@
+{
+    "label": "Flagsmith Integration",
+    "position": 70,
+    "collapsed": true
+}

docs/docs/flagsmith-integration/client-side-sdks/_category_.json

@@ -0,0 +1,5 @@
+{
+    "label": "Client-Side SDKs",
+    "position": 20,
+    "collapsed": true
+}

docs/docs/flagsmith-integration/client-side-sdks/android.md

@@ -0,0 +1,234 @@
+---
+title: Flagsmith Android/Kotlin SDK
+sidebar_label: Android / Kotlin
+description: Manage your Feature Flags and Remote Config in your Android applications.
+slug: /clients/android
+---
+
+import CodeBlock from '@theme/CodeBlock'; import { AndroidVersion } from '@site/src/components/SdkVersions.js';
+
+This SDK can be used for Android applications written in Kotlin. The source code for the client is available on
+[GitHub](https://github.com/Flagsmith/flagsmith-kotlin-android-client/).
+
+## Installation
+
+### Gradle
+
+```groovy
+repositories {
+    google()
+    mavenCentral()
+}
+```
+
+In your project path `app/build.gradle` add a new dependency:
+
+<CodeBlock>{`implementation("com.flagsmith:flagsmith-kotlin-android-client:`}<AndroidVersion />"{`)`}</CodeBlock>
+
+## Basic Usage
+
+The SDK is initialised against a single environment within a project on [https://flagsmith.com](https://flagsmith.com),
+for example the Development or Production environment. You can find your Client-side Environment Key in the Environment
+settings page.
+
+## Initialization
+
+### Within your Activity inside `onCreate()`
+
+```kotlin
+lateinit var flagsmith : Flagsmith
+
+override fun onCreate(savedInstanceState: Bundle?) {
+    initFlagsmith();
+}
+
+private fun initFlagsmith() {
+    flagsmith = Flagsmith(environmentKey = FlagsmithConfigHelper.environmentDevelopmentKey, context = context)
+}
+```
+
+## Custom configuration
+
+The Flagsmith SDK has various parameters for initialisation. Most of these are optional, and allow you to configure the
+Flagsmith SDK to your specific needs:
+
+- `environmentKey` Take this API key from the Flagsmith dashboard and pass here
+- `baseUrl` By default we'll connect to the Flagsmith backend, but if you self-host you can configure here
+- `context` The current Context is required to use the Flagsmith Analytics functionality
+- `enableAnalytics` Enable analytics - default true. Disable this if you'd like to avoid the use of Context
+- `analyticsFlushPeriod` The period in seconds between attempts by the Flagsmith SDK to push analytic events to the
+  server
+- `enableRealtimeUpdates` Enable the SDK to receive updates to features in real time while the app is running
+- `defaultFlags` Provide default flags the the SDK to ensure values are availble when no network connection can be made
+- `cacheConfig` Disabled by default, but when enabled will allow Flagsmith to fall back to cached values when no network
+  connection can be made
+- `request / read / writeTimeoutSeconds` Fine-grained control of the HTTP timeouts used inside the Flagsmith SDK
+
+## Flags
+
+Now you are all set to retrieve feature flags from your project. To list and print all flags:
+
+```kotlin
+flagsmith.getFeatureFlags { result ->
+    result.fold(
+        onSuccess = { flagList ->
+            Log.i("Flagsmith", "Current flags:")
+            flagList.forEach { Log.i("Flagsmith", "- ${it.feature.name} - enabled: ${it.enabled} value: ${it.featureStateValue ?: "not set"}") }
+        },
+        onFailure = { err ->
+            Log.e("Flagsmith", "Error getting feature flags", err)
+        })
+}
+```
+
+### Get Flags for an Identity
+
+To get feature flags for a specific identity:
+
+```kotlin
+flagsmith.getFeatureFlags(identity = "test-user@gmail.com") { result ->
+    result.fold(
+        onSuccess = { flagList ->
+            Log.i("Flagsmith", "Current flags:")
+            flagList.forEach { Log.i("Flagsmith", "- ${it.feature.name} - enabled: ${it.enabled} value: ${it.featureStateValue ?: "not set"}") }
+        },
+        onFailure = { err ->
+            Log.e("Flagsmith", "Error getting feature flags", err)
+        })
+}
+```
+
+You can also get flags for an identity and set the traits at the same time:
+
+```kotlin
+flagsmith.getFeatureFlags(identity = "test-user@gmail.com", traits = listOf(Trait(key = "set-from-client", value = "12345"))) { result ->
+    result.fold(
+        onSuccess = { flagList ->
+            Log.i("Flagsmith", "Current flags:")
+            flagList.forEach { Log.i("Flagsmith", "- ${it.feature.name} - enabled: ${it.enabled} value: ${it.featureStateValue ?: "not set"}") }
+        },
+        onFailure = { err ->
+            Log.e("Flagsmith", "Error getting feature flags", err)
+        })
+}
+```
+
+### Get Flag Object by `featureId`
+
+To retrieve a feature flag boolean value by its name:
+
+```kotlin
+flagsmith.hasFeatureFlag(forFeatureId = "test_feature1") { result ->
+    val isEnabled = result.getOrDefault(true)
+    Log.i("Flagsmith", "test_feature1 is enabled? $isEnabled")
+}
+```
+
+### Create a Trait for a user identity
+
+```kotlin
+flagsmith.setTrait(Trait(key = "set-from-client", value = "12345"), identity = "test@test.com") { result ->
+    result.fold(
+        onSuccess = { _ ->
+            Log.i("Flagsmith", "Successfully set trait")
+
+        },
+        onFailure = { err ->
+            Log.e("Flagsmith", "Error setting trait", err)
+        })
+}
+```
+
+### Get all Traits
+
+To retrieve a trait for a particular identity as explained here
+[Traits](../../basic-features/managing-identities.md#identity-traits)
+
+```kotlin
+flagsmith.getTraits(identity = "test@test.com") { result ->
+    result.fold(
+        onSuccess = { traits ->
+            traits.forEach {
+                Log.i("Flagsmith", "Trait - ${it.key} : ${it.traitValue}")
+            }
+        },
+        onFailure = { err ->
+            Log.e("Flagsmith", "Error getting traits", err)
+        })
+}
+```
+
+### Providing Default Flags
+
+You can define default flag values when initialising the SDK. This ensures that your application works as intended in
+the event that it cannot receive a response from our API.
+
+```kotlin
+val defaultFlags = listOf(
+    Flag(
+        feature = Feature(
+            id = 345345L,
+            name = "Flag 1",
+            createdDate = "2023‐07‐07T09:07:16Z",
+            description = "Flag 1 description",
+            type = "CONFIG",
+            defaultEnabled = true,
+            initialValue = "true"
+        ), enabled = true, featureStateValue = "value1"
+    ),
+    Flag(
+        feature = Feature(
+            id = 34345L,
+            name = "Flag 2",
+            createdDate = "2023‐07‐07T09:07:16Z",
+            description = "Flag 2 description",
+            type = "CONFIG",
+            defaultEnabled = true,
+            initialValue = "true"
+        ), enabled = true, featureStateValue = "value2"
+    ),
+)
+
+// Then pass these during initialisation:
+flagsmith = Flagsmith(
+    environmentKey = FlagsmithConfigHelper  environmentDevelopmentKey,
+    defaultFlags = defaultFlags,
+    context = context)
+
+```
+
+### Cache
+
+By default, the cache is off. When turned on, Flagsmith will cache all flags returned by the API (to permanent storage),
+and in case of a failed response, fall back on the cached values. The cache can be turned off or on during
+initialisation:
+
+```kotlin
+flagsmith = Flagsmith(
+    environmentKey = FlagsmithConfigHelper  environmentDevelopmentKey,
+    cacheConfig = FlagsmithCacheConfig(enableCache = true)
+    context = context)
+```
+
+You can also set a TTL for the cache (in seconds) for finer control:
+
+```kotlin
+FlagsmithCacheConfig (
+    enableCache = true,
+    cacheTTLSeconds = 3600L, // 1 hour
+    val cacheSize = 1024L * 1024L, // 1 MB
+)
+```
+
+## Override the default base URL
+
+By default, the client uses a default configuration. You can override the configuration as follows. If you're also using
+realtime flag updates in your hosted environment you'll also need to pass the eventSourceUrl in a similar fashion:
+
+```kotlin
+        flagsmith = Flagsmith(
+            environmentKey = Helper.environmentDevelopmentKey,
+            context = context,
+            baseUrl = "https://flagsmith.example.com/api/v1/"),
+            eventSourceUrl = "https://realtime.flagsmith.example.com/"
+```