Skip to content

Commit 6498d7a

Browse files
z4kn4feinz4kn4fein
authored
New OF provider docs (#554)
* Fixup ios/kotlin docs * Add docs for new OF providers * Update .validationignore * Remove snapshot badge of Kotlin SDK * Change Ruby OF provider gem badge * Swift doc change * Refine Xcode Dependencies section * Update kotlin.mdx
1 parent 709438a commit 6498d7a

File tree

15 files changed

+625
-16
lines changed

15 files changed

+625
-16
lines changed

‎website/.validationignore

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -106,6 +106,9 @@
106106
/docs/sdk-reference/openfeature/php.mdx
107107
/docs/sdk-reference/openfeature/python.mdx
108108
/docs/sdk-reference/openfeature/rust.mdx
109+
/docs/sdk-reference/openfeature/ruby.mdx
110+
/docs/sdk-reference/openfeature/swift.mdx
111+
/docs/sdk-reference/openfeature/kotlin.mdx
109112
/docs/sdk-reference/overview.mdx
110113
/docs/sdk-reference/php.mdx
111114
/docs/sdk-reference/python.mdx

‎website/docs/sdk-reference/ios.mdx

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -425,7 +425,7 @@ let isMyFeatureEnabled = snapshot.getValue(for: "isMyFeatureEnabled", defaultVal
425425
<TabItem value="objectivec" label="Objective-C">
426426

427427
```objectivec
428-
ConfigCatSnapshot* snapshot = [client snapshot];
428+
ConfigCatClientSnapshot* snapshot = [client snapshot];
429429

430430
BOOL isMyFeatureEnabled = [snapshot getBoolValueFor:@"isMyFeatureEnabled"
431431
defaultValue:false
@@ -454,7 +454,7 @@ client.hooks.addOnReady { state in
454454
<TabItem value="objectivec" label="Objective-C">
455455

456456
```objectivec
457-
[client.hooks addOnReadyWithHandler:^(enum ClientReadyState state) {
457+
[client.hooks addOnReadyWithHandler:^(enum ClientCacheState state) {
458458
// the state parameter tells what is the SDK's initialization state
459459
}];
460460
```
@@ -974,10 +974,10 @@ ConfigCatClient* client = [ConfigCatClient getWithSdkKey:@"#YOUR-SDK-KEY#"
974974

975975
With the following hooks you can subscribe to particular events fired by the SDK:
976976

977-
- `onReady(ClientReadyState)`: This event is sent when the SDK reaches the ready state. If the SDK is initialized with lazy load or manual polling it's considered ready right after instantiation.
977+
- `onReady(ClientCacheState)`: This event is sent when the SDK reaches the ready state. If the SDK is initialized with lazy load or manual polling it's considered ready right after instantiation.
978978
If it's using auto polling, the ready state is reached when the SDK has a valid config JSON loaded into memory either from cache or from HTTP. If the config couldn't be loaded neither from cache nor from HTTP the `onReady` event fires when the auto polling's `maxInitWaitTimeInSeconds` is reached.
979979

980-
- `onConfigChanged([String: Setting])`: This event is sent when the SDK loads a valid config JSON into memory from cache, and each subsequent time when the loaded config JSON changes via HTTP.
980+
- `onConfigChanged((Config, ConfigCatClientSnapshot))`: This event is sent when the SDK loads a valid config JSON into memory from cache, and each subsequent time when the loaded config JSON changes via HTTP.
981981

982982
- `onFlagEvaluated(EvaluationDetails)`: This event is sent each time when the SDK evaluates a feature flag or setting. The event sends the same evaluation details that you would get from [`getValueDetails()`](#anatomy-of-getvaluedetails).
983983

‎website/docs/sdk-reference/kotlin.mdx

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,6 @@ export const KotlinSchema = require('@site/src/schema-markup/sdk-reference/kotli
1111
[![Star on GitHub](https://img.shields.io/github/stars/configcat/kotlin-sdk.svg?style=social)](https://github.com/configcat/kotlin-sdk/stargazers)
1212
[![Kotlin CI](https://github.com/configcat/kotlin-sdk/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/configcat/kotlin-sdk/actions/workflows/ci.yml)
1313
[![Maven Central](https://img.shields.io/maven-central/v/com.configcat/configcat-kotlin-client?label=maven%20central)](https://search.maven.org/artifact/com.configcat/configcat-kotlin-client/)
14-
![Snapshot](https://img.shields.io/nexus/s/com.configcat/configcat-kotlin-client?label=snapshot&server=https%3A%2F%2Foss.sonatype.org)
1514
[![Quality Gate Status](https://img.shields.io/sonar/quality_gate/configcat_kotlin-sdk?logo=SonarCloud&server=https%3A%2F%2Fsonarcloud.io)](https://sonarcloud.io/project/overview?id=configcat_kotlin-sdk)
1615
[![SonarCloud Coverage](https://img.shields.io/sonar/coverage/configcat_kotlin-sdk?logo=SonarCloud&server=https%3A%2F%2Fsonarcloud.io)](https://sonarcloud.io/project/overview?id=configcat_kotlin-sdk)
1716

@@ -321,7 +320,7 @@ client.setDefaultUser(user)
321320
val otherUser = ConfigCatUser(identifier = "brian@example.com")
322321

323322
// otherUser will be used at the evaluation process.
324-
val value = await client.getValue("keyOfMySetting", false, otherUser)
323+
val value = client.getValue("keyOfMySetting", false, otherUser)
325324
```
326325

327326
For deleting the default user, you can do the following:
@@ -752,4 +751,4 @@ Check out our Sample Applications how they use the ConfigCat SDK
752751
753752
- <a href="https://github.com/configcat/kotlin-sdk" target="_blank">ConfigCat Kotlin Multiplatform SDK's repository on GitHub</a>
754753
- <a href="https://configcat.github.io/kotlin-sdk/" target="_blank">ConfigCat Kotlin Multiplatform SDK's API documentation</a>
755-
- <a href="https://search.maven.org/artifact/com.configcat/configcat-kotlin-client" target="_blank">ConfigCat Kotlin Multiplatform SDK on Maven Central</a>
754+
- <a href="https://central.sonatype.com/artifact/com.configcat/configcat-kotlin-client" target="_blank">ConfigCat Kotlin Multiplatform SDK on Maven Central</a>

‎website/docs/sdk-reference/openfeature/kotlin.mdx

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
1+
---
2+
id: kotlin
3+
title: OpenFeature Provider for Kotlin
4+
description: ConfigCat OpenFeature Provider for Kotlin. This is a step-by-step guide on how to use ConfigCat with the OpenFeature Kotlin SDK.
5+
---
6+
7+
[![CI](https://github.com/configcat/openfeature-kotlin/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/configcat/openfeature-kotlin/actions/workflows/ci.yml)
8+
[![Maven Central](https://img.shields.io/maven-central/v/com.configcat/configcat-openfeature-provider?label=maven%20central)](https://central.sonatype.com/artifact/com.configcat/configcat-openfeature-provider)
9+
10+
<a href="https://github.com/configcat/openfeature-kotlin" target="_blank">
11+
ConfigCat OpenFeature Provider for Kotlin on GitHub
12+
</a>
13+
14+
## Getting started
15+
16+
### 1. Install the provider
17+
18+
```kotlin
19+
dependencies {
20+
implementation("com.configcat:configcat-openfeature-provider:$providerVersion")
21+
}
22+
```
23+
24+
### 2. Initialize the provider
25+
26+
The `ConfigCatProvider` function takes the SDK key and an optional `ConfigCatOptions`
27+
argument containing the additional configuration options for
28+
the [ConfigCat Kotlin SDK](../../kotlin/#setting-up-the-configcat-client):
29+
30+
```kotlin
31+
import com.configcat.*
32+
import dev.openfeature.sdk.*
33+
34+
coroutineScope.launch(Dispatchers.IO) {
35+
// Configure the provider.
36+
val provider = ConfigCatProvider("<YOUR-CONFIGCAT-SDK-KEY>") {
37+
pollingMode = autoPoll { pollingInterval = 60.seconds }
38+
}
39+
40+
// Configure the OpenFeature API with the ConfigCat provider.
41+
OpenFeatureAPI.setProviderAndWait(provider)
42+
43+
// Create a client.
44+
val client = OpenFeatureAPI.getClient()
45+
}
46+
```
47+
48+
For more information about all the configuration options, see the [Kotlin SDK documentation](../../kotlin/#setting-up-the-configcat-client).
49+
50+
### 3. Evaluate your feature flag
51+
52+
```kotlin
53+
val isAwesomeFeatureEnabled = client.getBooleanValue("isAwesomeFeatureEnabled", false)
54+
if (isAwesomeFeatureEnabled) {
55+
doTheNewThing()
56+
} else {
57+
doTheOldThing()
58+
}
59+
```
60+
61+
## Evaluation Context
62+
63+
An <a href="https://openfeature.dev/docs/reference/concepts/evaluation-context" target="_blank">evaluation context</a> in the OpenFeature specification is a container for arbitrary contextual data that can be used as a basis for feature flag evaluation.
64+
The ConfigCat provider translates these evaluation contexts to ConfigCat [User Objects](../../kotlin/#user-object).
65+
66+
The following table shows how the different context attributes are mapped to User Object attributes.
67+
68+
| Evaluation context | User Object | Required |
69+
| ------------------ | ------------ | -------- |
70+
| `targetingKey` | `identifier` | &#9745; |
71+
| `Email` | `email` | |
72+
| `Country` | `country` | |
73+
| Any other | `custom` | |
74+
75+
To evaluate feature flags for a context, use the `setEvaluationContext()` method on the `OpenFeatureAPI` to set the context for the provider:
76+
77+
```kotlin
78+
val context = ImmutableContext(
79+
targetingKey = "#SOME-USER-ID#",
80+
attributes = mapOf(
81+
"Email" to Value.String("configcat@example.com"),
82+
"Country" to Value.String("CountryID"),
83+
"Rating" to Value.Double(4.5),
84+
"RegisteredAt" to Value.Date(Date.from(Instant.parse("2023-11-22T12:34:56+00:00"))),
85+
"Roles" to Value.List(listOf(Value.String("Role1"), Value.String("Role2")))
86+
),
87+
)
88+
OpenFeatureAPI.setEvaluationContext(context)
89+
```
90+
91+
## Look under the hood
92+
93+
- <a href="https://github.com/configcat/openfeature-kotlin/tree/main/samples/android" target="_blank">Sample Android APP</a>
94+
- <a href="https://github.com/configcat/openfeature-kotlin" target="_blank">ConfigCat OpenFeature Provider's repository on GitHub</a>
95+
- <a href="https://central.sonatype.com/artifact/com.configcat/configcat-openfeature-provider" target="_blank">ConfigCat OpenFeature Provider on Maven Central</a>

‎website/docs/sdk-reference/openfeature/overview.mdx

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,9 +15,12 @@ ConfigCat offers providers for the following platforms supported by OpenFeature
1515
- [Go](./go.mdx)
1616
- [Java](./java.mdx)
1717
- [JavaScript](./js.mdx)
18+
- [Kotlin (Android)](./kotlin.mdx)
1819
- [NestJS](./nestjs.mdx)
1920
- [Node.js](./node.mdx)
2021
- [PHP](./php.mdx)
2122
- [Python](./python.mdx)
2223
- [React](./react.mdx)
23-
- [Rust](./rust.mdx)
24+
- [Ruby](./ruby.mdx)
25+
- [Rust](./rust.mdx)
26+
- [Swift (iOS)](./swift.mdx)

‎website/docs/sdk-reference/openfeature/ruby.mdx

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
1+
---
2+
id: ruby
3+
title: OpenFeature Provider for Ruby
4+
description: ConfigCat OpenFeature Provider for Ruby. This is a step-by-step guide on how to use ConfigCat with the OpenFeature Ruby SDK.
5+
---
6+
7+
[![Build Status](https://github.com/configcat/openfeature-ruby/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/configcat/openfeature-ruby/actions/workflows/ci.yml)
8+
[![Gem Version](https://badge.fury.io/rb/configcat-openfeature-provider.svg?icon=si%3Arubygems)](https://badge.fury.io/rb/configcat-openfeature-provider)
9+
10+
<a href="https://github.com/configcat/openfeature-ruby" target="_blank">ConfigCat OpenFeature Provider for Ruby on GitHub</a>
11+
12+
## Getting started
13+
14+
### 1. Install the provider
15+
16+
```bash
17+
gem install configcat-openfeature-provider
18+
```
19+
20+
### 2. Initialize the provider
21+
22+
The initializer of `ConfigCat::OpenFeature::Provider` takes the SDK key and an optional `ConfigCat::ConfigCatOptions`
23+
argument containing the additional configuration options for the [ConfigCat Ruby SDK](../../ruby/#creating-the-configcat-client):
24+
25+
```ruby
26+
require "configcat-openfeature-provider"
27+
28+
# Configure the OpenFeature API with the ConfigCat provider.
29+
OpenFeature::SDK.configure do |config|
30+
config.set_provider(ConfigCat::OpenFeature::Provider.new(
31+
sdk_key: "<YOUR-CONFIGCAT-SDK-KEY>",
32+
# Build options for the ConfigCat SDK.
33+
options: ConfigCat::ConfigCatOptions.new(
34+
polling_mode: ConfigCat::PollingMode.auto_poll
35+
)))
36+
end
37+
38+
# Create a client.
39+
client = OpenFeature::SDK.build_client
40+
```
41+
42+
For more information about all the configuration options, see the [Ruby SDK documentation](../../ruby/#creating-the-configcat-client).
43+
44+
### 3. Evaluate your feature flag
45+
46+
```ruby
47+
is_awesome_feature_enabled = client.fetch_boolean_value(
48+
flag_key: "isAwesomeFeatureEnabled",
49+
default_value: false
50+
)
51+
if is_awesome_feature_enabled
52+
do_the_new_thing
53+
else
54+
do_the_old_thing
55+
end
56+
```
57+
58+
## Evaluation Context
59+
60+
An <a href="https://openfeature.dev/docs/reference/concepts/evaluation-context" target="_blank">evaluation context</a> in the OpenFeature specification is a container for arbitrary contextual data that can be used as a basis for feature flag evaluation.
61+
The ConfigCat provider translates these evaluation contexts to ConfigCat [User Objects](../../ruby/#user-object).
62+
63+
The following table shows how the different context attributes are mapped to User Object attributes.
64+
65+
| Evaluation context | User Object | Required |
66+
| ------------------ | ------------ | -------- |
67+
| `targeting_key` | `identifier` | &#9745; |
68+
| `Email` | `email` | |
69+
| `Country` | `country` | |
70+
| Any other | `custom` | |
71+
72+
To evaluate feature flags for a context, use the <a href="https://openfeature.dev/docs/reference/concepts/evaluation-api/" target="_blank">OpenFeature Evaluation API</a>:
73+
74+
```ruby
75+
context = OpenFeature::SDK::EvaluationContext.new(
76+
OpenFeature::SDK::EvaluationContext::TARGETING_KEY => "#SOME-USER-ID#",
77+
"Email" => "configcat@example.com",
78+
"Country" => "CountryID",
79+
"Rating" => 4.5,
80+
"RegisteredAt" => DateTime.iso8601("2023-11-22T12:34:56+00:00"),
81+
"Roles" => [ "Role1", "Role2" ]
82+
)
83+
84+
is_awesome_feature_enabled = client.fetch_boolean_value(
85+
flag_key: "isAwesomeFeatureEnabled",
86+
default_value: false,
87+
evaluation_context: context
88+
)
89+
```
90+
91+
## Look under the hood
92+
93+
- <a href="https://github.com/configcat/openfeature-ruby/tree/main/samples/provider-sample" target="_blank">Sample Ruby APP</a>
94+
- <a href="https://github.com/configcat/openfeature-ruby" target="_blank">ConfigCat OpenFeature Provider's repository on GitHub</a>
95+
- <a href="https://rubygems.org/gems/configcat-openfeature-provider" target="_blank">ConfigCat OpenFeature Provider in RubyGems</a>

‎website/docs/sdk-reference/openfeature/swift.mdx

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
---
2+
id: swift
3+
title: OpenFeature Provider for Swift
4+
description: ConfigCat OpenFeature Provider for Swift. This is a step-by-step guide on how to use ConfigCat with the OpenFeature Swift SDK.
5+
---
6+
7+
[![CI](https://github.com/configcat/openfeature-swift/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/configcat/openfeature-swift/actions/workflows/ci.yml)
8+
9+
<a href="https://github.com/configcat/openfeature-swift" target="_blank">
10+
ConfigCat OpenFeature Provider for Swift on GitHub
11+
</a>
12+
13+
## Getting started
14+
15+
### 1. Install the provider
16+
17+
#### Swift Package Manager
18+
19+
If you manage dependencies through SPM, in the dependencies section of Package.swift add:
20+
21+
```swift
22+
.package(url: "https://github.com/configcat/openfeature-swift", from: "0.1.0")
23+
```
24+
25+
and in the target dependencies section add:
26+
```swift
27+
.product(name: "ConfigCat", package: "openfeature-swift"),
28+
```
29+
30+
#### Xcode Dependencies
31+
32+
- Open the dependencies dialog from `File` > `Add Package Dependencies...`
33+
- Search for `https://github.com/configcat/openfeature-swift` and click `Add Package`.
34+
35+
### 2. Initialize the provider
36+
37+
The initializer of `ConfigCatProvider` takes the SDK key and an optional `ConfigCatOptions`
38+
argument containing the additional configuration options for
39+
the [ConfigCat Swift SDK](../../ios/#creating-the-configcat-client):
40+
41+
```swift
42+
import ConfigCatOpenFeature
43+
import ConfigCat
44+
import OpenFeature
45+
46+
Task {
47+
// Configure the provider.
48+
let provider = ConfigCatProvider(sdkKey: "<YOUR-CONFIGCAT-SDK-KEY>") { opts in
49+
opts.pollingMode = PollingModes.autoPoll()
50+
}
51+
52+
// Configure the OpenFeature API with the ConfigCat provider.
53+
await OpenFeatureAPI.shared.setProviderAndWait(provider: provider)
54+
55+
// Create a client.
56+
let client = OpenFeatureAPI.shared.getClient()
57+
}
58+
```
59+
60+
For more information about all the configuration options, see the [Swift SDK documentation](../../ios/#creating-the-configcat-client).
61+
62+
### 3. Evaluate your feature flag
63+
64+
```swift
65+
let isAwesomeFeatureEnabled = client.getBooleanValue(key: "isAwesomeFeatureEnabled", defaultValue: false)
66+
if isAwesomeFeatureEnabled {
67+
doTheNewThing()
68+
} else {
69+
doTheOldThing()
70+
}
71+
```
72+
73+
## Evaluation Context
74+
75+
An <a href="https://openfeature.dev/docs/reference/concepts/evaluation-context" target="_blank">evaluation context</a> in the OpenFeature specification is a container for arbitrary contextual data that can be used as a basis for feature flag evaluation.
76+
The ConfigCat provider translates these evaluation contexts to ConfigCat [User Objects](../../ios/#user-object).
77+
78+
The following table shows how the different context attributes are mapped to User Object attributes.
79+
80+
| Evaluation context | User Object | Required |
81+
| ------------------ | ------------ | -------- |
82+
| `targetingKey` | `identifier` | &#9745; |
83+
| `Email` | `email` | |
84+
| `Country` | `country` | |
85+
| Any other | `custom` | |
86+
87+
To evaluate feature flags for a context, use the `setEvaluationContext()` method on `OpenFeatureAPI.shared` to set the context for the provider:
88+
89+
```swift
90+
let context = MutableContext(targetingKey: "#SOME-USER-ID#", structure: MutableStructure(attributes: [
91+
"Email": Value.string("configcat@example.com"),
92+
"Country": Value.string("CountryID"),
93+
"Rating": Value.double(4.5),
94+
"Roles": Value.list([Value.string("Role1"), Value.string("Role2")])
95+
]))
96+
OpenFeatureAPI.shared.setEvaluationContext(evaluationContext: context)
97+
```
98+
99+
## Look under the hood
100+
101+
- <a href="https://github.com/configcat/openfeature-swift/tree/main/samples/ios" target="_blank">Sample iOS APP</a>
102+
- <a href="https://github.com/configcat/openfeature-swift" target="_blank">ConfigCat OpenFeature Provider's repository on GitHub</a>

‎website/sidebars.ts

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -269,12 +269,15 @@ const sidebars: SidebarsConfig = {
269269
{ type: 'doc', id: 'sdk-reference/openfeature/go', label: 'Go' },
270270
{ type: 'doc', id: 'sdk-reference/openfeature/java', label: 'Java' },
271271
{ type: 'doc', id: 'sdk-reference/openfeature/js', label: 'JavaScript' },
272+
{ type: 'doc', id: 'sdk-reference/openfeature/kotlin', label: 'Kotlin (Android)' },
272273
{ type: 'doc', id: 'sdk-reference/openfeature/nestjs', label: 'NestJS' },
273274
{ type: 'doc', id: 'sdk-reference/openfeature/node', label: 'Node.js' },
274275
{ type: 'doc', id: 'sdk-reference/openfeature/php', label: 'PHP' },
275276
{ type: 'doc', id: 'sdk-reference/openfeature/python', label: 'Python' },
276277
{ type: 'doc', id: 'sdk-reference/openfeature/react', label: 'React' },
278+
{ type: 'doc', id: 'sdk-reference/openfeature/ruby', label: 'Ruby' },
277279
{ type: 'doc', id: 'sdk-reference/openfeature/rust', label: 'Rust' },
280+
{ type: 'doc', id: 'sdk-reference/openfeature/swift', label: 'Swift (iOS)' },
278281
],
279282
},
280283
{

0 commit comments

Comments
 (0)