-
Notifications
You must be signed in to change notification settings - Fork 18
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Updated Android sdk to v10.0.0 Catnip (#357)
* Updated Android sdk to v10.0.0 Catnip * Update endpoints.md with Android release * Add type CAUTION to Android and Java.
- Loading branch information
1 parent
f850e29
commit b1c64c4
Showing
4 changed files
with
134 additions
and
35 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -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. | ||
| ::: | ||
|
|
||
| <div id="setting-type-mapping"></div> | ||
|
|
||
| | 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("[email protected]"); | |
| | `custom()` | Optional dictionary for custom attributes of a user for advanced targeting rule definitions. e.g. User role, Subscription type. | | ||
|
|
||
| ```java | ||
| java.util.Map<String,String> customAttributes = new java.util.HashMap<String,String>(); | ||
| java.util.Map<String,Object> customAttributes = new java.util.HashMap<String,Object>(); | ||
| 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<String,Object> customAttributes = new java.util.HashMap<String,Object>(); | ||
| 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("[email protected]") | ||
| .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 protected]} | ||
| Evaluating rule: [Email:[email protected]] [CONTAINS] [@something.com] => no match | ||
| Evaluating rule: [Email:[email protected]] [CONTAINS] [@example.com] => match, returning "true" | ||
| INFO com.configcat.ConfigCatClient - [5000] Evaluating 'isPOCFeatureEnabled' for User '{"Identifier":"<SOME USERID>","Email":"[email protected]","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 | ||
|
|
||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters