diff --git a/website/docs/advanced/config-v2-sdk-compatibility.md b/website/docs/advanced/config-v2-sdk-compatibility.md index 425891fa..b097af94 100644 --- a/website/docs/advanced/config-v2-sdk-compatibility.md +++ b/website/docs/advanced/config-v2-sdk-compatibility.md @@ -14,7 +14,7 @@ This table shows which SDK versions support Config V2. Read more about [Config V | Elixir | WIP | https://github.com/configcat/elixir-sdk/releases | | Go | v9.0.3 | https://github.com/configcat/go-sdk/releases | | Java | v9.0.0 | https://github.com/configcat/java-sdk/releases | -| Java (Android) | WIP | https://github.com/configcat/android-sdk/releases | +| Java (Android) | v10.0.0 | https://github.com/configcat/android-sdk/releases | | JavaScript | v9.4.0 | https://github.com/configcat/js-sdk/releases | | JavaScript (Chromium Extension) | v2.3.0 | https://github.com/configcat/js-chromium-extension-sdk/releases | | JavaScript (React) | v4.3.0 | https://github.com/configcat/react-sdk/releases | diff --git a/website/docs/advanced/proxy/endpoints.md b/website/docs/advanced/proxy/endpoints.md index 32055563..c8aecd1a 100644 --- a/website/docs/advanced/proxy/endpoints.md +++ b/website/docs/advanced/proxy/endpoints.md @@ -86,24 +86,24 @@ var configCatClient = configcat.getClient( The following SDK versions are supported by the `>=v0.3.X` Proxy's CDN endpoint: -| SDK | Version | -| ------- |---------------------------------------------------------------------------| -| .NET | [`>=v9.0.0`](https://github.com/configcat/.net-sdk/releases/tag/v9.0.0) | -| JS | [`>=v9.0.0`](https://github.com/configcat/js-sdk/releases/tag/v9.0.0) | -| JS SSR | [`>=v8.0.0`](https://github.com/configcat/js-ssr-sdk/releases/tag/v8.0.0) | -| React | [`>=v4.0.0`](https://github.com/configcat/react-sdk/releases/tag/v4.0.0) | -| Node | [`>=v11.0.0`](https://github.com/configcat/node-sdk/releases/tag/v11.0.0) | -| Python | [`>=v9.0.0`](https://github.com/configcat/python-sdk/releases/tag/v9.0.0) | -| Go | [`>=v9.0.0`](https://github.com/configcat/go-sdk/releases/tag/v9.0.0) | -| C++ | TBA | -| Dart | TBA | -| Elixir | TBA | -| Java | [`>=v9.0.0`](https://github.com/configcat/java-sdk/releases/tag/v9.0.0) | -| Android | TBA | -| Kotlin | TBA | -| PHP | TBA | -| Ruby | TBA | -| Swift | TBA | +| SDK | Version | +| ------- |------------------------------------------------------------------------------| +| .NET | [`>=v9.0.0`](https://github.com/configcat/.net-sdk/releases/tag/v9.0.0) | +| JS | [`>=v9.0.0`](https://github.com/configcat/js-sdk/releases/tag/v9.0.0) | +| JS SSR | [`>=v8.0.0`](https://github.com/configcat/js-ssr-sdk/releases/tag/v8.0.0) | +| React | [`>=v4.0.0`](https://github.com/configcat/react-sdk/releases/tag/v4.0.0) | +| Node | [`>=v11.0.0`](https://github.com/configcat/node-sdk/releases/tag/v11.0.0) | +| Python | [`>=v9.0.0`](https://github.com/configcat/python-sdk/releases/tag/v9.0.0) | +| Go | [`>=v9.0.0`](https://github.com/configcat/go-sdk/releases/tag/v9.0.0) | +| C++ | TBA | +| Dart | TBA | +| Elixir | TBA | +| Java | [`>=v9.0.0`](https://github.com/configcat/java-sdk/releases/tag/v9.0.0) | +| Android | [`>=v10.0.0`](https://github.com/configcat/android-sdk/releases/tag/v10.0.0) | +| Kotlin | TBA | +| PHP | TBA | +| Ruby | TBA | +| Swift | TBA | diff --git a/website/docs/sdk-reference/android.md b/website/docs/sdk-reference/android.md index cea5ae2c..71ede247 100644 --- a/website/docs/sdk-reference/android.md +++ b/website/docs/sdk-reference/android.md @@ -35,7 +35,7 @@ When you use R8 or ProGuard, the aar artifact automatically applies the [include ```groovy title="build.gradle" dependencies { - implementation 'com.configcat:configcat-android-client:9.+' + implementation 'com.configcat:configcat-android-client:10.+' } ``` @@ -142,6 +142,23 @@ boolean value = client.getValue( false // Default value ); ``` +:::caution +It is important to provide an argument for the `classOfT` parameter, specifically for the `T` generic type parameter, +that matches the type of the feature flag or setting you are evaluating. Please refer to the following table for the corresponding types. +::: + +
+ +| Setting Kind | Type parameter `T` | +| -------------- |-----------------------| +| On/Off Toggle | `boolean` / `Boolean` | +| Text | `String` | +| Whole Number | `int` / `Integer` | +| Decimal Number | `double` / `Double` | + +It's important to note that providing any other type for the type parameter will result in an `IllegalArgumentException`. + +If you specify an allowed type but it mismatches the setting kind, an error message will be logged and `defaultValue` will be returned. ## Anatomy of `getValueAsync()` @@ -167,6 +184,11 @@ client.getValueAsync( }); ``` +:::caution +It is important to provide an argument for the `classOfT` parameter, specifically for the `T` generic type parameter, +that matches the type of the feature flag or setting you are evaluating. Please refer to [this table](#setting-type-mapping) for the corresponding types. +::: + ## Anatomy of `getValueDetails()` `getValueDetails()` is similar to `getValue()` but instead of returning the evaluated value only, it gives more detailed information about the evaluation result. @@ -196,19 +218,23 @@ client.getValueDetailsAsync( // Use the details result }); ``` +:::caution +It is important to provide an argument for the `classOfT` parameter, specifically for the `T` generic type parameter, +that matches the type of the feature flag or setting you are evaluating. Please refer to [this table](#setting-type-mapping) for the corresponding types. +::: The details result contains the following information: -| Property | Type | Description | -| -------------------------------------- | --------------------------------------- | ----------------------------------------------------------------------------------------- | -| `getValue()` | `boolean` / `String` / `int` / `double` | The evaluated value of the feature flag or setting. | -| `getKey()` | `String` | The key of the evaluated feature flag or setting. | -| `isDefaultValue()` | `boolean` | True when the default value passed to getValueDetails() is returned due to an error. | -| `getError()` | `String` | In case of an error, this field contains the error message. | -| `getUser()` | `User` | The user object that was used for evaluation. | -| `getMatchedEvaluationPercentageRule()` | `PercentageRule` | If the evaluation was based on a percentage rule, this field contains that specific rule. | -| `getMatchedEvaluationRule()` | `RolloutRule` | If the evaluation was based on a targeting rule, this field contains that specific rule. | -| `getFetchTimeUnixMilliseconds()` | `long` | The last download time of the current config in unix milliseconds format. | +| Property | Type | Description | +|-----------------------------------| --------------------------------------- |------------------------------------------------------------------------------------------------------------| +| `getValue()` | `boolean` / `String` / `int` / `double` | The evaluated value of the feature flag or setting. | +| `getKey()` | `String` | The key of the evaluated feature flag or setting. | +| `isDefaultValue()` | `boolean` | True when the default value passed to getValueDetails() is returned due to an error. | +| `getError()` | `String` | In case of an error, this field contains the error message. | +| `getUser()` | `User` | The user object that was used for evaluation. | +| `getMatchedPercentageOption()` | `PercentageOption` | The percentage option (if any) that was used to select the evaluated value. | +| `getMatchedTargetingRule()` | `TargetingRule` | The targeting rule (if any) that matched during the evaluation and was used to return the evaluated value. | +| `getFetchTimeUnixMilliseconds()` | `long` | The last download time of the current config in unix milliseconds format. | ## User Object @@ -232,7 +258,7 @@ User user = User.newBuilder().build("john@example.com"); | `custom()` | Optional dictionary for custom attributes of a user for advanced targeting rule definitions. e.g. User role, Subscription type. | ```java -java.util.Map customAttributes = new java.util.HashMap(); +java.util.Map customAttributes = new java.util.HashMap(); customAttributes.put("SubscriptionType", "Pro"); customAttributes.put("UserRole", "Admin"); @@ -243,6 +269,49 @@ User user = User.newBuilder() .build("#UNIQUE-USER-IDENTIFIER#"); // UserID ``` +The `Custom` dictionary also allows attribute values other than `String` values: + +```java +java.util.Map customAttributes = new java.util.HashMap(); + customAttributes.put("Rating", 4.5); + customAttributes.put("RegisteredAt", new Date("2023-11-22 12:34:56 +00:00")); + customAttributes.put("Roles", new String[]{"Role1", "Role2"}); + +User user = User.newBuilder() + .email("john@example.com") + .country("United Kingdom") + .custom(customAttributes) + .build("#UNIQUE-USER-IDENTIFIER#"); +``` + +### User Object Attribute Types + +All comparators support `String` values as User Object attribute (in some cases they need to be provided in a specific format though, see below), but some of them also support other types of values. It depends on the comparator how the values will be handled. The following rules apply: + +**Text-based comparators** (EQUALS, IS ONE OF, etc.) +* accept `String` values, +* all other values are automatically converted to `String` (a warning will be logged but evaluation will continue as normal). + +**SemVer-based comparators** (IS ONE OF, <, >=, etc.) +* accept `String` values containing a properly formatted, valid semver value, +* all other values are considered invalid (a warning will be logged and the currently evaluated targeting rule will be skipped). + +**Number-based comparators** (=, <, >=, etc.) +* accept `Double` values and all other numeric values which can safely be converted to `Double`, +* accept `String` values containing a properly formatted, valid `Double` value, +* all other values are considered invalid (a warning will be logged and the currently evaluated targeting rule will be skipped). + +**Date time-based comparators** (BEFORE / AFTER) +* accept `Date` values, which are automatically converted to a second-based Unix timestamp, +* accept `Double` values representing a second-based Unix timestamp and all other numeric values which can safely be converted to `Double`, +* accept `String` values containing a properly formatted, valid `Double` value, +* all other values are considered invalid (a warning will be logged and the currently evaluated targeting rule will be skipped). + +**String array-based comparators** (ARRAY CONTAINS ANY OF / ARRAY NOT CONTAINS ANY OF) +* accept arrays and list of `String`, +* accept `String` values containing a valid JSON string which can be deserialized to an array of `String`, +* all other values are considered invalid (a warning will be logged and the currently evaluated targeting rule will be skipped). + ### Default user There's an option to set a default user object that will be used at feature flag and setting evaluation. It can be useful when your application has a single user only, or rarely switches users. @@ -595,10 +664,11 @@ Available log levels: Info level logging helps to inspect how a feature flag was evaluated: ```bash -INFO com.configcat.ConfigCatClient - [5000] Evaluating getValue(isPOCFeatureEnabled). -User object: User{Identifier=435170f4-8a8b-4b67-a723-505ac7cdea92, Email=john@example.com} -Evaluating rule: [Email:john@example.com] [CONTAINS] [@something.com] => no match -Evaluating rule: [Email:john@example.com] [CONTAINS] [@example.com] => match, returning "true" +INFO com.configcat.ConfigCatClient - [5000] Evaluating 'isPOCFeatureEnabled' for User '{"Identifier":"","Email":"configcat@example.com","Country":"US","SubscriptionType":"Pro","Role":"Admin","version":"1.0.0"}' + Evaluating targeting rules and applying the first match if any: + - IF User.Email CONTAINS ANY OF ['@something.com'] THEN 'False' => no match + - IF User.Email CONTAINS ANY OF ['@example.com'] THEN 'True' => MATCH, applying rule + Returning 'True'. ``` ### Logging Implementation diff --git a/website/docs/sdk-reference/java.md b/website/docs/sdk-reference/java.md index ff4814d7..f0c34651 100644 --- a/website/docs/sdk-reference/java.md +++ b/website/docs/sdk-reference/java.md @@ -145,6 +145,24 @@ boolean value = client.getValue( false // Default value ); ``` +:::caution +It is important to provide an argument for the `classOfT` parameter, specifically for the `T` generic type parameter, +that matches the type of the feature flag or setting you are evaluating. Please refer to the following table for the corresponding types. +::: + +
+ +| Setting Kind | Type parameter `T` | +| -------------- |-----------------------| +| On/Off Toggle | `boolean` / `Boolean` | +| Text | `String` | +| Whole Number | `int` / `Integer` | +| Decimal Number | `double` / `Double` | + +It's important to note that providing any other type for the type parameter will result in an `IllegalArgumentException`. + +If you specify an allowed type but it mismatches the setting kind, an error message will be logged and `defaultValue` will be returned. + ## Anatomy of `getValueAsync()` @@ -170,6 +188,12 @@ client.getValueAsync( }); ``` +:::caution +It is important to provide an argument for the `classOfT` parameter, specifically for the `T` generic type parameter, +that matches the type of the feature flag or setting you are evaluating. Please refer to [this table](#setting-type-mapping) for the corresponding types. +::: + + ## Anatomy of `getValueDetails()` `getValueDetails()` is similar to `getValue()` but instead of returning the evaluated value only, it gives more detailed information about the evaluation result. @@ -199,6 +223,11 @@ client.getValueDetailsAsync( }); ``` +:::caution +It is important to provide an argument for the `classOfT` parameter, specifically for the `T` generic type parameter, +that matches the type of the feature flag or setting you are evaluating. Please refer to [this table](#setting-type-mapping) for the corresponding types. +::: + The details result contains the following information: | Property | Type | Description |