Skip to content

Commit 076c124

Browse files
guiwritehtessaro
guiwrite
and
htessaro
authored
docs: Flagsmith integration (#5881)
Co-authored-by: htessaro <heitor@writechoice.io>
1 parent d12f16f commit 076c124

20 files changed

Lines changed: 4128 additions & 0 deletions

‎docs/docs/flagsmith-integration/CLI.md‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
---
2+
description: Flagsmith Command Line Interface (CLI)
3+
sidebar_label: CLI
4+
sidebar_position: 40
5+
---
6+
7+
# Flagsmith CLI
8+
9+
Flagsmith has a [CLI tool](https://github.com/Flagsmith/flagsmith-cli) that you can use to help in your development
10+
workflows.
11+
12+
## Installation
13+
14+
Install globally:
15+
16+
```bash
17+
npm install -g flagsmith-cli
18+
```
19+
20+
## Sample Usage
21+
22+
```bash
23+
USAGE
24+
$ flagsmith get [ENVIRONMENT] [-o <value>] [-a <value>] [-i <value>]
25+
26+
ARGUMENTS
27+
ENVIRONMENT The flagsmith environment key to use,
28+
defaults to the environment variable FLAGSMITH_ENVIRONMENT
29+
30+
FLAGS
31+
-a, --api=<value> The API URL to fetch the feature flags from
32+
-i, --identity=<value> The identity for which to fetch feature flags
33+
-o, --output=<value> [default: ./flagsmith.json] The file path output
34+
35+
DESCRIPTION
36+
Retrieve flagsmith feature flags from the Flagsmith API and output them to a file.
37+
38+
EXAMPLES
39+
$ FLAGSMITH_ENVIRONMENT=x flagsmith get
40+
41+
$ flagsmith get <ENVIRONMENT_ID>
42+
43+
$ flagsmith get --o ./my-file.json
44+
45+
$ flagsmith get --a https://flagsmith.example.com/api/v1/
46+
47+
$ flagsmith get --i flagsmith_identity
48+
```

‎docs/docs/flagsmith-integration/_category_.json‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
{
2+
"label": "Flagsmith Integration",
3+
"position": 70,
4+
"collapsed": true
5+
}

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

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
{
2+
"label": "Client-Side SDKs",
3+
"position": 20,
4+
"collapsed": true
5+
}

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

Lines changed: 234 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,234 @@
1+
---
2+
title: Flagsmith Android/Kotlin SDK
3+
sidebar_label: Android / Kotlin
4+
description: Manage your Feature Flags and Remote Config in your Android applications.
5+
slug: /clients/android
6+
---
7+
8+
import CodeBlock from '@theme/CodeBlock'; import { AndroidVersion } from '@site/src/components/SdkVersions.js';
9+
10+
This SDK can be used for Android applications written in Kotlin. The source code for the client is available on
11+
[GitHub](https://github.com/Flagsmith/flagsmith-kotlin-android-client/).
12+
13+
## Installation
14+
15+
### Gradle
16+
17+
```groovy
18+
repositories {
19+
google()
20+
mavenCentral()
21+
}
22+
```
23+
24+
In your project path `app/build.gradle` add a new dependency:
25+
26+
<CodeBlock>{`implementation("com.flagsmith:flagsmith-kotlin-android-client:`}<AndroidVersion />"{`)`}</CodeBlock>
27+
28+
## Basic Usage
29+
30+
The SDK is initialised against a single environment within a project on [https://flagsmith.com](https://flagsmith.com),
31+
for example the Development or Production environment. You can find your Client-side Environment Key in the Environment
32+
settings page.
33+
34+
## Initialization
35+
36+
### Within your Activity inside `onCreate()`
37+
38+
```kotlin
39+
lateinit var flagsmith : Flagsmith
40+
41+
override fun onCreate(savedInstanceState: Bundle?) {
42+
initFlagsmith();
43+
}
44+
45+
private fun initFlagsmith() {
46+
flagsmith = Flagsmith(environmentKey = FlagsmithConfigHelper.environmentDevelopmentKey, context = context)
47+
}
48+
```
49+
50+
## Custom configuration
51+
52+
The Flagsmith SDK has various parameters for initialisation. Most of these are optional, and allow you to configure the
53+
Flagsmith SDK to your specific needs:
54+
55+
- `environmentKey` Take this API key from the Flagsmith dashboard and pass here
56+
- `baseUrl` By default we'll connect to the Flagsmith backend, but if you self-host you can configure here
57+
- `context` The current Context is required to use the Flagsmith Analytics functionality
58+
- `enableAnalytics` Enable analytics - default true. Disable this if you'd like to avoid the use of Context
59+
- `analyticsFlushPeriod` The period in seconds between attempts by the Flagsmith SDK to push analytic events to the
60+
server
61+
- `enableRealtimeUpdates` Enable the SDK to receive updates to features in real time while the app is running
62+
- `defaultFlags` Provide default flags the the SDK to ensure values are availble when no network connection can be made
63+
- `cacheConfig` Disabled by default, but when enabled will allow Flagsmith to fall back to cached values when no network
64+
connection can be made
65+
- `request / read / writeTimeoutSeconds` Fine-grained control of the HTTP timeouts used inside the Flagsmith SDK
66+
67+
## Flags
68+
69+
Now you are all set to retrieve feature flags from your project. To list and print all flags:
70+
71+
```kotlin
72+
flagsmith.getFeatureFlags { result ->
73+
result.fold(
74+
onSuccess = { flagList ->
75+
Log.i("Flagsmith", "Current flags:")
76+
flagList.forEach { Log.i("Flagsmith", "- ${it.feature.name} - enabled: ${it.enabled} value: ${it.featureStateValue ?: "not set"}") }
77+
},
78+
onFailure = { err ->
79+
Log.e("Flagsmith", "Error getting feature flags", err)
80+
})
81+
}
82+
```
83+
84+
### Get Flags for an Identity
85+
86+
To get feature flags for a specific identity:
87+
88+
```kotlin
89+
flagsmith.getFeatureFlags(identity = "test-user@gmail.com") { result ->
90+
result.fold(
91+
onSuccess = { flagList ->
92+
Log.i("Flagsmith", "Current flags:")
93+
flagList.forEach { Log.i("Flagsmith", "- ${it.feature.name} - enabled: ${it.enabled} value: ${it.featureStateValue ?: "not set"}") }
94+
},
95+
onFailure = { err ->
96+
Log.e("Flagsmith", "Error getting feature flags", err)
97+
})
98+
}
99+
```
100+
101+
You can also get flags for an identity and set the traits at the same time:
102+
103+
```kotlin
104+
flagsmith.getFeatureFlags(identity = "test-user@gmail.com", traits = listOf(Trait(key = "set-from-client", value = "12345"))) { result ->
105+
result.fold(
106+
onSuccess = { flagList ->
107+
Log.i("Flagsmith", "Current flags:")
108+
flagList.forEach { Log.i("Flagsmith", "- ${it.feature.name} - enabled: ${it.enabled} value: ${it.featureStateValue ?: "not set"}") }
109+
},
110+
onFailure = { err ->
111+
Log.e("Flagsmith", "Error getting feature flags", err)
112+
})
113+
}
114+
```
115+
116+
### Get Flag Object by `featureId`
117+
118+
To retrieve a feature flag boolean value by its name:
119+
120+
```kotlin
121+
flagsmith.hasFeatureFlag(forFeatureId = "test_feature1") { result ->
122+
val isEnabled = result.getOrDefault(true)
123+
Log.i("Flagsmith", "test_feature1 is enabled? $isEnabled")
124+
}
125+
```
126+
127+
### Create a Trait for a user identity
128+
129+
```kotlin
130+
flagsmith.setTrait(Trait(key = "set-from-client", value = "12345"), identity = "test@test.com") { result ->
131+
result.fold(
132+
onSuccess = { _ ->
133+
Log.i("Flagsmith", "Successfully set trait")
134+
135+
},
136+
onFailure = { err ->
137+
Log.e("Flagsmith", "Error setting trait", err)
138+
})
139+
}
140+
```
141+
142+
### Get all Traits
143+
144+
To retrieve a trait for a particular identity as explained here
145+
[Traits](../../basic-features/managing-identities.md#identity-traits)
146+
147+
```kotlin
148+
flagsmith.getTraits(identity = "test@test.com") { result ->
149+
result.fold(
150+
onSuccess = { traits ->
151+
traits.forEach {
152+
Log.i("Flagsmith", "Trait - ${it.key} : ${it.traitValue}")
153+
}
154+
},
155+
onFailure = { err ->
156+
Log.e("Flagsmith", "Error getting traits", err)
157+
})
158+
}
159+
```
160+
161+
### Providing Default Flags
162+
163+
You can define default flag values when initialising the SDK. This ensures that your application works as intended in
164+
the event that it cannot receive a response from our API.
165+
166+
```kotlin
167+
val defaultFlags = listOf(
168+
Flag(
169+
feature = Feature(
170+
id = 345345L,
171+
name = "Flag 1",
172+
createdDate = "2023‐07‐07T09:07:16Z",
173+
description = "Flag 1 description",
174+
type = "CONFIG",
175+
defaultEnabled = true,
176+
initialValue = "true"
177+
), enabled = true, featureStateValue = "value1"
178+
),
179+
Flag(
180+
feature = Feature(
181+
id = 34345L,
182+
name = "Flag 2",
183+
createdDate = "2023‐07‐07T09:07:16Z",
184+
description = "Flag 2 description",
185+
type = "CONFIG",
186+
defaultEnabled = true,
187+
initialValue = "true"
188+
), enabled = true, featureStateValue = "value2"
189+
),
190+
)
191+
192+
// Then pass these during initialisation:
193+
flagsmith = Flagsmith(
194+
environmentKey = FlagsmithConfigHelper environmentDevelopmentKey,
195+
defaultFlags = defaultFlags,
196+
context = context)
197+
198+
```
199+
200+
### Cache
201+
202+
By default, the cache is off. When turned on, Flagsmith will cache all flags returned by the API (to permanent storage),
203+
and in case of a failed response, fall back on the cached values. The cache can be turned off or on during
204+
initialisation:
205+
206+
```kotlin
207+
flagsmith = Flagsmith(
208+
environmentKey = FlagsmithConfigHelper environmentDevelopmentKey,
209+
cacheConfig = FlagsmithCacheConfig(enableCache = true)
210+
context = context)
211+
```
212+
213+
You can also set a TTL for the cache (in seconds) for finer control:
214+
215+
```kotlin
216+
FlagsmithCacheConfig (
217+
enableCache = true,
218+
cacheTTLSeconds = 3600L, // 1 hour
219+
val cacheSize = 1024L * 1024L, // 1 MB
220+
)
221+
```
222+
223+
## Override the default base URL
224+
225+
By default, the client uses a default configuration. You can override the configuration as follows. If you're also using
226+
realtime flag updates in your hosted environment you'll also need to pass the eventSourceUrl in a similar fashion:
227+
228+
```kotlin
229+
flagsmith = Flagsmith(
230+
environmentKey = Helper.environmentDevelopmentKey,
231+
context = context,
232+
baseUrl = "https://flagsmith.example.com/api/v1/"),
233+
eventSourceUrl = "https://realtime.flagsmith.example.com/"
234+
```

0 commit comments

Comments
 (0)