Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: update sdk section #49

Closed
wants to merge 16 commits into from
Closed

docs: update sdk section #49

Show file tree
Hide file tree
Changes from 14 commits
Commits
Show all changes
16 commits
Select commit Hold shift + click to select a range
9468329
docs: add development stage for all SDKs
htessaro Jan 31, 2024
64a68ee
style: update table style
htessaro Jan 31, 2024
e5f0939
docs: update android sdk content
htessaro Jan 31, 2024
51a7bfa
docs: update ios sdk information
htessaro Jan 31, 2024
6bb7246
docs: update javascript sdk information
htessaro Jan 31, 2024
f8281e2
docs: update flutter sdk information
htessaro Jan 31, 2024
83b01dd
docs: update sdk overview with features comparation
htessaro Jan 31, 2024
78343fe
docs: updates sdk overview
htessaro Feb 1, 2024
e5f6d4e
docs: remove go and nodejs pages from the menu
htessaro Feb 1, 2024
2ad446b
docs: apply reviews to all cient sdk pages
htessaro Feb 1, 2024
42e4415
docs: fix style of tables in content pages
htessaro Feb 1, 2024
0fcabd4
docs: apply reviews to sdk pages
htessaro Feb 1, 2024
780872a
docs: fix default timeout note on client side
htessaro Feb 1, 2024
8c44a2b
docs: updat tags recommendation in client SDKs
htessaro Feb 1, 2024
f20d942
docs: update not cta to info
htessaro Feb 1, 2024
c48300e
docs: apply reviews to client pages
htessaro Feb 1, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
118 changes: 108 additions & 10 deletions docs/sdk/client-side/android/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,13 +1,20 @@
---
title: Android reference
title: Android
slug: /sdk/client-side/android
toc_max_heading_level: 4
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

This category contains topics explaining how to configure Bucketeer's Android SDK.

:::tip Android SDK Version (Stable)

Bucketeer Android SDK has reached the production stage, offering you a stable and reliable experience.

:::

:::info Compatibility

The Bucketeer SDK is compatible with Android SDK versions 21 and higher (Android 5.0, Lollipop).
Expand Down Expand Up @@ -54,7 +61,9 @@ Configure the SDK config and user configuration.

:::note

The **featureTag** setting is the tag you configure when creating a Feature Flag.
The **featureTag** setting is the tag you configure when creating a Feature Flag. It will evaluate all the Feature Flags in the environment when it is not configured.

**We strongly recommend** using tags to speed up the evaluation process and reduce the cache size in the client.

:::

Expand Down Expand Up @@ -110,20 +119,19 @@ val client = BKTClient.getInstance()
</TabItem>
</Tabs>

:::note
:::info Default timeout

The initialize process immediately starts polling the latest evaluations from Bucketeer in the background using the interval `pollingInterval` configuration while the application is in the **foreground state**.
When the application changes to the **background state**, it will use the `backgroundPollingInterval` configuration.
The initialize process default timeout is 5 seconds.

:::
Once initialization is finished, all the requests in the SDK use a timeout of 30 seconds.

If you want to use the feature flag on Splash or Main views, and the user opens your application for the first time, it may not have enough time to fetch the variations from the Bucketeer server.
:::

For this case, we recommend using the `Future<BKTException?>` returned from the initialize method.
If you want to use the feature flag on Splash or Main views, the SDK cache may be old or not exist and may not have enough time to fetch the variations from the Bucketeer server. In this case, we recommend using the `Future<BKTException?>` returned from the initialize method. In addition, you can define a custom timeout.

:::note
:::caution Initialization Timeout error

Be aware that if an error is returned in the initialize process, it is regarding the fetch evaluation timeout error, not the initialize process itself.
During the initialization process, errors **are not** related to the initialization itself. Instead, they arise from a timeout request, indicating the variations data from the server weren't received. Therefore, the SDK will work as usual and update the variations in the next [polling](android#polling) request.

:::

Expand Down Expand Up @@ -158,6 +166,96 @@ viewLifecycleOwner.lifecycleScope.launch {
</TabItem>
</Tabs>

#### Polling

The initialize process immediately starts polling the latest evaluations from the Bucketeer server in the background using the interval `pollingInterval` configuration while the application is in the **foreground state**.
When the application changes to the **background state**, it will use the `backgroundPollingInterval` configuration.

#### Polling retry behavior

The Bucketeer SDK regularly polls the latest evaluations from the server based on the pollingInterval parameter. By default, the `pollingInterval` is set to 10 minutes, but you can adjust it to suit your needs.

If a polling request fails, the SDK initiates a retry procedure. The SDK attempts a new polling request every minute up to 5 times. If all five retry attempts fail, the SDK sends a new polling request once the `pollingInterval` time elapses. The table below shows this scenario:

<div className="center-table">
<table>
<thead>
<tr>
<th>Polling Time</th>
<th>Retry Time</th>
<th>Request Status</th>
</tr>
</thead>
<tbody>
<tr>
<td>10:00</td>
<td>-</td>
<td>Fail</td>
</tr>
<tr>
<td>- </td>
<td>10:01</td>
<td>Fail</td>
</tr>
<tr>
<td>- </td>
<td>10:02</td>
<td>Fail</td>
</tr>
<tr>
<td>- </td>
<td>10:03</td>
<td>Fail</td>
</tr>
<tr>
<td>-</td>
<td>10:04</td>
<td>Fail</td>
</tr>
<tr>
<td>-</td>
<td>10:05</td>
<td>Fail</td>
</tr>
<tr>
<td>10:10</td>
<td>-</td>
<td>Successful</td>
</tr>
</tbody>
</table>
</div>

The polling counter, which uses the `pollingInterval` information, resets in case of a successful retry. The table below shows the described scenario.
<div className="center-table">
<table>
<thead>
<tr>
<th>Polling Time</th>
<th>Retry Time</th>
<th>Request status</th>
</tr>
</thead>
<tbody>
<tr>
<td>10:00</td>
<td>-</td>
<td>Fail</td>
</tr>
<tr>
<td>- </td>
<td>10:01</td>
<td>Successful</td>
</tr>
<tr>
<td>10:11</td>
<td>-</td>
<td>Successful</td>
</tr>
</tbody>
</table>
</div>

## Supported features

### Evaluating user
Expand Down
134 changes: 125 additions & 9 deletions docs/sdk/client-side/flutter/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,13 +1,22 @@
---
title: Flutter reference
title: Flutter
slug: /sdk/client-side/flutter
toc_max_heading_level: 4
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

This category contains topics explaining how to configure Bucketeer's Flutter SDK.

:::caution Flutter SDK Version (Beta)
cre8ivejp marked this conversation as resolved.
Show resolved Hide resolved

The Flutter JS SDK is currently in its Beta stage.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
The Flutter JS SDK is currently in its Beta stage.
The Flutter SDK is currently in its Beta stage.


If you find any issues or have suggestions for improvement, feel free to open an [issue](https://github.com/bucketeer-io/flutter-client-sdk/issues).
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
If you find any issues or have suggestions for improvement, feel free to open an [issue](https://github.com/bucketeer-io/flutter-client-sdk/issues).
If you find any issues or have suggestions for improvement, feel free to open an [issue](https://github.com/bucketeer-io/flutter-client-sdk/issues).
The SDK doesn't support Flutter Web yet. All contributions are welcome!


:::

## Getting started

Before starting, ensure that you follow the [Getting Started](/getting-started) guide.
Expand Down Expand Up @@ -47,7 +56,9 @@ Configure the SDK config and user configuration.

:::note

The **featureTag** setting is the tag you configure when creating a Feature Flag.
The **featureTag** setting is the tag you configure when creating a Feature Flag. It will evaluate all the Feature Flags in the environment when it is not configured.

**We strongly recommend** using tags to speed up the evaluation process and reduce the cache size in the client.

:::

Expand Down Expand Up @@ -105,30 +116,135 @@ final client = BKTClient.instance;
</TabItem>
</Tabs>

:::note
:::info Default timeout

The initialize process default timeout is 5 seconds.

The initialize process immediately starts polling the latest evaluations from Bucketeer in the background using the interval `pollingInterval` configuration while the application is in the **foreground state**. When the application changes to the **background state**, it will use the `backgroundPollingInterval` configuration.
Once initialization is finished, all the requests in the SDK use a timeout of 30 seconds.

:::

If you want to use the feature flag on Splash or Main views, and the user opens your application for the first time, it may not have enough time to fetch the variations from the Bucketeer server.
If you want to use the feature flag on Splash or Main views, the SDK cache may be old or not exist and may not have enough time to fetch the variations from the Bucketeer server. For this case, we recommend using the `timeout` option in the initialize method. It will block until the SDK receives the latest user variations.
htessaro marked this conversation as resolved.
Show resolved Hide resolved

:::caution Initialization Timeout error

For this case, we recommend using the `timeout` option in the initialize method. It will block until the SDK receives the latest user variations.
During the initialization process, errors **are not** related to the initialization itself. Instead, they arise from a timeout request, indicating the variations data from the server weren't received. Therefore, the SDK will work as usual and update the variations in the next [polling](flutter#polling) request.

:::

<Tabs>
<TabItem value="dart" label="Dart">

```dart showLineNumbers
/// It will unlock without waiting until the fetching variation process finishes
int timeout = 1000;
int timeout = 5000;

await BKTClient.initialize(config: config, user: user, timeoutMillis: timeout);
final client = BKTClient.instance;
if (result.isSuccess) {
htessaro marked this conversation as resolved.
Show resolved Hide resolved
final client = BKTClient.instance;
if (showNewFeature) {
/// The Application code to show the new feature
} else {
/// The code to run if the feature is off
}
} else {
/// Handle the error when there is no cache or the cache is not updated
}
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@cre8ivejp, the original code didn't use a conditional to treat timeout errors. I tried to adapt the code from the update section. However, I don't know if it's correct.

```

</TabItem>
</Tabs>

#### Polling

The initialize process immediately starts polling the latest evaluations from the Bucketeer server in the background using the interval `pollingInterval` configuration while the application is in the **foreground state**.
When the application changes to the **background state**, it will use the `backgroundPollingInterval` configuration.

#### Polling retry behavior

The Bucketeer SDK regularly polls the latest evaluations from the server based on the pollingInterval parameter. By default, the `pollingInterval` is set to 10 minutes, but you can adjust it to suit your needs.

If a polling request fails, the SDK initiates a retry procedure. The SDK attempts a new polling request every minute up to 5 times. If all five retry attempts fail, the SDK sends a new polling request once the `pollingInterval` time elapses. The table below shows this scenario:

<div className="center-table">
<table>
<thead>
<tr>
<th>Polling Time</th>
<th>Retry Time</th>
<th>Request Status</th>
</tr>
</thead>
<tbody>
<tr>
<td>10:00</td>
<td>-</td>
<td>Fail</td>
</tr>
<tr>
<td>- </td>
<td>10:01</td>
<td>Fail</td>
</tr>
<tr>
<td>- </td>
<td>10:02</td>
<td>Fail</td>
</tr>
<tr>
<td>- </td>
<td>10:03</td>
<td>Fail</td>
</tr>
<tr>
<td>-</td>
<td>10:04</td>
<td>Fail</td>
</tr>
<tr>
<td>-</td>
<td>10:05</td>
<td>Fail</td>
</tr>
<tr>
<td>10:10</td>
<td>-</td>
<td>Successful</td>
</tr>
</tbody>
</table>
</div>

The polling counter, which uses the `pollingInterval` information, resets in case of a successful retry. The table below shows the described scenario.
<div className="center-table">
<table>
<thead>
<tr>
<th>Polling Time</th>
<th>Retry Time</th>
<th>Request status</th>
</tr>
</thead>
<tbody>
<tr>
<td>10:00</td>
<td>-</td>
<td>Fail</td>
</tr>
<tr>
<td>- </td>
<td>10:01</td>
<td>Successful</td>
</tr>
<tr>
<td>10:11</td>
<td>-</td>
<td>Successful</td>
</tr>
</tbody>
</table>
</div>

## Supported features

### Evaluating user
Expand Down Expand Up @@ -203,7 +319,7 @@ if (result.isSuccess) {
/// The code to run if the feature is off
}
} else {
/// The code to run if the feature is off
/// Handle the error when there is no cache or the cache is not updated
}
```

Expand Down
Loading
Loading