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

Jump to bottom

add experiment docs for local evaluation cohorts #205

Merged
merged 12 commits into from
Aug 27, 2024
Merged

add experiment docs for local evaluation cohorts #205

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
12 commits
Select commit Hold shift + click to select a range
63b38e4
add experiment docs for local evaluation cohorts
bgiori Aug 5, 2024
d5ab6e4
add jvm sdk
bgiori Aug 6, 2024
61c2c4a
update all sdks
bgiori Aug 12, 2024
fa573cb
add cohort targeting article
bgiori Aug 12, 2024
9a81e7d
tabe reformatting
bgiori Aug 26, 2024
ed1f81f
update SDK versions
bgiori Aug 27, 2024
113fc1b
Update content/collections/experiment-sdks/en/experiment-go.md
bgiori Aug 27, 2024
4d0604e
Update content/collections/experiment-sdks/en/experiment-go.md
bgiori Aug 27, 2024
048f484
Update content/collections/experiment-sdks/en/experiment-jvm.md
bgiori Aug 27, 2024
e4283f0
Update content/collections/experiment-sdks/en/experiment-jvm.md
bgiori Aug 27, 2024
6ebb5e2
Update content/collections/experiment-sdks/en/experiment-jvm.md
bgiori Aug 27, 2024
795fabf
code examples and minor updates
bgiori Aug 27, 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
52 changes: 42 additions & 10 deletions content/collections/experiment-sdks/en/experiment-go.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -86,9 +86,14 @@

The SDK client can be configured on initialization.

{{partial:admonition type="info" heading="EU data center"}}
If you're using Amplitude's EU data center, configure the `ServerZone` option on initialization.
{{/partial:admonition}}

| <div class="big-column">Name</div> | Description | Default Value |
| --- | --- | --- |
| `Debug` | Set to `true` to enable debug logging. | `false` |
| `ServerZone` | The Amplitude data center to use. Either `USServerZone` or `EUServerZone`. | `USServerZone` |
| `ServerUrl` | The host to fetch flag configurations from. | `https://api.lab.amplitude.com` |
| `FlagConfigPollingInterval` | The timeout for fetching variants in milliseconds. This timeout only applies to the initial request, not subsequent retries | `500 * time.Millisecond` |
| `RetryBackoff.FetchRetries` | The number of retries to attempt if a request to fetch variants fails. | `1` |
Expand All @@ -97,10 +102,6 @@
| `RetryBackoff.FetchRetryBackoffScalar` | Scales the minimum backoff exponentially. | `1` |
| `RetryBackoff.FetchRetryTimeout` | The request timeout for retrying variant fetches. | `500 * time.Millisecond` |

{{partial:admonition type="note" heading="EU data center"}}
If you're using Amplitude's EU data center, configure the `serverUrl` option on initialization to `https://api.lab.eu.amplitude.com`
{{/partial:admonition}}

### Fetch

Fetches variants for a [user](/docs/experiment/data-model#users) and returns the results. This function [remote evaluates](/docs/experiment/remote-evaluation) the user for flags associated with the deployment used to initialize the SDK client.
Expand Down Expand Up @@ -157,7 +158,13 @@

```go
// (1) Initialize the local evaluation client with a server deployment key.
client := local.Initialize("<DEPLOYMENT_KEY>", nil)
client := local.Initialize("<DEPLOYMENT_KEY>", &local.Config{
// (Recommended) Enable local evaluation cohort targeting.
CohortSyncConfig: &local.CohortSyncConfig {
ApiKey: "<API_KEY>",
SecretKey: "<SECRET_KEY>"
}
})

// (2) Start the local evaluation client.
err := client.Start()
Expand Down Expand Up @@ -199,26 +206,37 @@

The SDK client can be configured on initialization.

{{partial:admonition type="info" heading="EU data center"}}
If you're using Amplitude's EU data center, configure the `ServerZone` option on initialization.
{{/partial:admonition}}

**Config**

| <div class="big-column">Name</div> | Description | Default Value |
| --- | --- | --- |
| `Debug` | Set to `true` to enable debug logging. | `false` |
| `ServerZone` | The Amplitude data center to use. Either `USServerZone` or `EUServerZone`. | `USServerZone` |
| `ServerUrl` | The host to fetch flag configurations from. | `https://api.lab.amplitude.com` |
| `FlagConfigPollingInterval` | The interval to poll for updated flag configs after calling [`Start()`](#start) | `30 * time.Second` |
| `FlagConfigPollerRequestTimeout` | The timeout for the request made by the flag config poller | `10 * time.Second` |
| `AssignmentConfig` | Configuration for automatically tracking assignment events after an evaluation. | `nil` |
| `CohortSyncConfig` | Configuration to enable cohort downloading for [local evaluation cohort targeting](#local-evaluation-cohort-targeting). | `nil` |

**AssignmentConfig**

| <div class="big-column">Name</div> | Description | Default Value |
| --- | --- | --- |
| `cacheCapacity` | The maximum number of assignments stored in the assignment cache | `524288` |
| `CacheCapacity` | The maximum number of assignments stored in the assignment cache | `524288` |
| [`Config`](/docs/sdks/analytics/go/go-sdk#configuration) | Options to configure the underlying Amplitude Analytics SDK used to track assignment events | |

{{partial:admonition type="note" heading="EU data center"}}
If you're using Amplitude's EU data center, configure the `serverUrl` option on initialization to `https://api.lab.eu.amplitude.com`
{{/partial:admonition}}
**CohortSyncConfig**

| <div class="big-column">Name</div> | Description | Default Value |
| --- | --- | --- |
| `ApiKey` | The analytics API key and NOT the experiment deployment key | *required* |
| `SecretKey` | The analytics secret key | *required* |
| `MaxCohortSize` | The maximum size of cohort that the SDK will download. Cohorts larger than this size won't download. | `2147483647` |

Check warning on line 238 in content/collections/experiment-sdks/en/experiment-go.md

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Amplitude.Will] Future tense! Avoid using 'will download'.

Raw Output:
{"message": "[Amplitude.Will] Future tense! Avoid using 'will download'.", "location": {"path": "content/collections/experiment-sdks/en/experiment-go.md", "range": {"start": {"line": 238, "column": 61}}}, "severity": "WARNING"}

Check warning on line 238 in content/collections/experiment-sdks/en/experiment-go.md

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Amplitude.Will] Future tense! Avoid using 'won't download'.

Raw Output:
{"message": "[Amplitude.Will] Future tense! Avoid using 'won't download'.", "location": {"path": "content/collections/experiment-sdks/en/experiment-go.md", "range": {"start": {"line": 238, "column": 106}}}, "severity": "WARNING"}
| `CohortPollingIntervalMillis` | The interval, in milliseconds, to poll Amplitude for cohort updates (60000 minimum). | `60000` |

### Start

Expand Down Expand Up @@ -277,4 +295,18 @@
} else {
// Flag is off
}
```
```

### Local evaluation cohort targeting

Since version `1.7.0`, the local evaluation SDK client supports downloading cohorts for local evaluation targeting. Configure the `CohortSyncConfig` option with the analytics `ApiKey` and `SecretKey` on initialization to enable this support.

```go
client := local.Initialize("<DEPLOYMENT_KEY>", &local.Config{
// (Recommended) Enable local evaluation cohort targeting.
CohortSyncConfig: &local.CohortSyncConfig {
ApiKey: "<API_KEY>",
SecretKey: "<SECRET_KEY>"
}
})
```
87 changes: 74 additions & 13 deletions content/collections/experiment-sdks/en/experiment-jvm.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,6 @@

This documentation has separate sections for [remote](/docs/experiment/remote-evaluation) and [local](/docs/experiment/local-evaluation) evaluation:


## Remote evaluation

Implements fetching variants for a user via [remote evaluation](/docs/experiment/remote-evaluation).
Expand Down Expand Up @@ -156,21 +155,29 @@

The SDK client can be configured on initialization.

{{partial:admonition type="info" heading="EU data center"}}
If you're using Amplitude's EU data center, configure the `serverZone` option on initialization.
{{/partial:admonition}}

| <div class="big-column">Name</div> | Description | Default Value |
| --- | --- | --- |
| `debug` | Set to `true` to enable debug logging. | `false` |
| `serverZone` | The Amplitude data center to use. Either `ServerZone.US` or `ServerZone.EU`. | `ServerZone.US` |
| `serverUrl` | The host to fetch flag configurations from. | `https://api.lab.amplitude.com` |
| `fetchTimeoutMillis` | The timeout for fetching variants in milliseconds. This timeout only applies to the initial request, not subsequent retries | `500` |
| `fetchRetries` | The number of retries to attempt if a request to fetch variants fails. | `1` |
| `fetchRetryBackoffMinMillis` | The minimum (initial) backoff after a request to fetch variants fails. This delay is scaled by the `fetchRetryBackoffScalar` | `0` |
| `fetchRetryBackoffMaxMillis` | The maximum backoff between retries. If the scaled backoff becomes greater than the max, the max is used for all subsequent requests | `10000` |
| `fetchRetryBackoffScalar` | Scales the minimum backoff exponentially. | `1` |
| `assignmentConfiguration` | Configuration for automatically tracking assignment events after an evaluation. | `null` |

**CohortSyncConfig**

{{partial:admonition type="info" heading="EU data center"}}
If you're using Amplitude's EU data center, configure the `serverUrl` option on initialization to `https://api.lab.eu.amplitude.com`
{{/partial:admonition}}
| <div class="big-column">Name</div> | Description | Default Value |
| --- | --- | --- |
| `apiKey` | The analytics API key and NOT the experiment deployment key | *required* |
| `secretKey` | The analytics secret key | *required* |
| `maxCohortSize` | The maximum size of cohort that the SDK will download. Cohorts larger than this size won't download. | `2147483647` |

Check warning on line 179 in content/collections/experiment-sdks/en/experiment-jvm.md

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Amplitude.Will] Future tense! Avoid using 'will download'.

Raw Output:
{"message": "[Amplitude.Will] Future tense! Avoid using 'will download'.", "location": {"path": "content/collections/experiment-sdks/en/experiment-jvm.md", "range": {"start": {"line": 179, "column": 61}}}, "severity": "WARNING"}

Check warning on line 179 in content/collections/experiment-sdks/en/experiment-jvm.md

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Amplitude.Will] Future tense! Avoid using 'won't download'.

Raw Output:
{"message": "[Amplitude.Will] Future tense! Avoid using 'won't download'.", "location": {"path": "content/collections/experiment-sdks/en/experiment-jvm.md", "range": {"start": {"line": 179, "column": 106}}}, "severity": "WARNING"}
| `cohortPollingIntervalMillis` | The interval, in milliseconds, to poll Amplitude for cohort updates (60000 minimum). | `60000` |

### Fetch

Expand Down Expand Up @@ -260,7 +267,7 @@

### Install

Install the JVM Server SDK using Gradle.
Install the JVM Server SDK using Maven or Gradle.

{{partial:tabs tabs="Groovy, Kotlin"}}
{{partial:tab name="Groovy"}}
Expand All @@ -275,17 +282,23 @@
{{/partial:tab}}
{{/partial:tabs}}


{{partial:admonition type="tip" heading="Quick start"}}
1. [Initialize the local evaluation client.](#initialize-local)
2. [Start the local evaluation client.](#start)
3. [Evaluate a user.](#evaluate)

{{partial:tabs tabs="Kotlin, Java"}}
{{partial:tab name="Kotlin"}}

```kotlin
// (1) Initialize the local evaluation client with a server deployment key.
val experiment = Experiment.initializeLocal("<DEPLOYMENT_KEY>")
val experiment = Experiment.initializeLocal(
"<DEPLOYMENT_KEY>",
// (Recommended) Enable local evaluation cohort targeting.
LocalEvaluationConfig.builder()
.cohortSyncConfig(CohortSyncConfig("<API_KEY>", "<SECRET_KEY>"))
.build()
)

// (2) Start the local evaluation client.
experiment.start()
Expand All @@ -302,7 +315,11 @@
{{partial:tab name="Java"}}
```java
// (1) Initialize the local evaluation client with a server deployment key.
LocalEvaluationClient experiment = Experiment.initializeLocal("<DEPLOYMENT_KEY>");
LocalEvaluationClient experiment = Experiment.initializeLocal("<DEPLOYMENT_KEY>",
// (Recommended) Enable local evaluation cohort targeting.
LocalEvaluationConfig.builder()
.cohortSyncConfig(new CohortSyncConfig("<API_KEY>", "<SECRET_KEY>"))
.build());

// (2) Start the local evaluation client.
experiment.start();
Expand Down Expand Up @@ -360,14 +377,21 @@

You can configure the SDK client on initialization.

{{partial:admonition type="info" heading="EU data center"}}
If you're using Amplitude's EU data center, configure the `serverZone` option on initialization.
{{/partial:admonition}}

**LocalEvaluationConfig**

| <div class="big-column">Name</div> | Description | Default Value |
| --- | --- | --- |
| `debug` | Set to `true` to enable debug logging. | `false` |
| `serverZone` | The Amplitude data center to use. Either `ServerZone.US` or `ServerZone.EU`. | `ServerZone.US` |
| `serverUrl` | The host to fetch flag configurations from. | `https://api.lab.amplitude.com` |
| `flagConfigPollingIntervalMillis` | The interval to poll for updated flag configs after calling [`Start()`](#start) | `30000` |
| `flagConfigPollerRequestTimeoutMillis` | The timeout for the request made by the flag config poller | `10000` |
| `assignmentConfiguration` | Enable automatic assignment tracking for local evaluations. | `null` |
| `cohortSyncConfig` | Configuration to enable cohort downloading for [local evaluation cohort targeting](#local-evaluation-cohort-targeting). | `null` |

**AssignmentConfiguration**

Expand All @@ -379,9 +403,14 @@
| `eventUploadPeriodMillis` | `setEventUploadPeriodMillis()` in the underlying [Analytics SDK](/docs/sdks/analytics/java/jre-java-sdk#configuration) | `10000` |
| `useBatchMode` | `useBatchMode()` in the underlying [Analytics SDK](/docs/sdks/analytics/java/jre-java-sdk#configuration) | `true` |

{{partial:admonition type="info" heading="EU data center"}}
If you're using Amplitude's EU data center, configure the `serverUrl` option on initialization to `https://api.lab.eu.amplitude.com`
{{/partial:admonition}}
**CohortSyncConfig**

| <div class="big-column">Name</div> | Description | Default Value |
| --- | --- | --- |
| `apiKey` | The analytics API key and NOT the experiment deployment key | *required* |
| `secretKey` | The analytics secret key | *required* |
| `maxCohortSize` | The maximum size of cohort that the SDK will download. Cohorts larger than this size won't download. | `2147483647` |

Check warning on line 412 in content/collections/experiment-sdks/en/experiment-jvm.md

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Amplitude.Will] Future tense! Avoid using 'will download'.

Raw Output:
{"message": "[Amplitude.Will] Future tense! Avoid using 'will download'.", "location": {"path": "content/collections/experiment-sdks/en/experiment-jvm.md", "range": {"start": {"line": 412, "column": 61}}}, "severity": "WARNING"}

Check warning on line 412 in content/collections/experiment-sdks/en/experiment-jvm.md

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Amplitude.Will] Future tense! Avoid using 'won't download'.

Raw Output:
{"message": "[Amplitude.Will] Future tense! Avoid using 'won't download'.", "location": {"path": "content/collections/experiment-sdks/en/experiment-jvm.md", "range": {"start": {"line": 412, "column": 106}}}, "severity": "WARNING"}
| `cohortPollingIntervalMillis` | The interval, in milliseconds, to poll Amplitude for cohort updates (60000 minimum). | `60000` |

### Start

Expand Down Expand Up @@ -482,4 +511,36 @@
}
```
{{/partial:tab}}
{{/partial:tabs}}
{{/partial:tabs}}

### Local evaluation cohort targeting

Since version `1.4.0`, the local evaluation SDK client supports downloading cohorts for local evaluation targeting. Configure the SDK using `cohortSyncConfig` with the analytics `apiKey` and `secretKey` on initialization to enable this support.

{{partial:tabs tabs="Kotlin, Java"}}
{{partial:tab name="Kotlin"}}

```kotlin
val experiment = Experiment.initializeLocal(
"<DEPLOYMENT_KEY>",
// (Recommended) Enable local evaluation cohort targeting.
LocalEvaluationConfig.builder()
.cohortSyncConfig(CohortSyncConfig("<API_KEY>", "<SECRET_KEY>"))
.build()
)
```

{{/partial:tab}}
{{partial:tab name="Java"}}

```java
// (1) Initialize the local evaluation client with a server deployment key.
LocalEvaluationClient experiment = Experiment.initializeLocal("<DEPLOYMENT_KEY>",
// (Recommended) Enable local evaluation cohort targeting.
LocalEvaluationConfig.builder()
.cohortSyncConfig(new CohortSyncConfig("<API_KEY>", "<SECRET_KEY>"))
.build());
```

{{/partial:tab}}
{{/partial:tabs}}
Loading
Loading