Skip to content

feat: enhance SDK documentation with Dart, Rust, and Liquid support #249

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

Open
joalves wants to merge 15 commits into
base: development
Choose a base branch
from
+2,443 −104
Open

feat: enhance SDK documentation with Dart, Rust, and Liquid support #249

Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
15 commits
Select commit Hold shift + click to select a range
67a00fd
feat: update Dart/Flutter SDK initialization to simplified API
joalves Jan 28, 2026
c0943ec
feat: add Dart, Rust, and Liquid SDK documentation with updated naming
joalves Jan 28, 2026
a2c7bef
fix: update Absmartly to ABsmartly in SDK documentation
joalves Jan 28, 2026
ed66524
docs: add code snippets for 10 new SDKs across all documentation sect…
joalves Feb 24, 2026
2d72397
docs: update SDK index page with all 21 SDKs in horizontal layout
joalves Feb 24, 2026
e729310
fix: wrap SDK tabs to multiple lines and separate Flutter from Dart
joalves Feb 25, 2026
a7e1ecd
fix: add syntax highlighting for new SDK languages
joalves Feb 25, 2026
7513b59
docs: update Go SDK snippets with idiomatic field names and New() con…
joalves Feb 26, 2026
fd4f53e
docs: update Vue3 snippets to use useABSmartly() composable
joalves Feb 26, 2026
bf2a741
docs: update Kotlin snippets to use SDK wrapper pattern
joalves Feb 26, 2026
75fc4f5
docs: update C++ snippets to use SDK wrapper pattern
joalves Feb 26, 2026
6e5a032
docs: add Ruby async context creation snippet
joalves Feb 26, 2026
addce5c
docs: update Java, PHP, Scala, Android, Rust snippets with ergonomics…
joalves Feb 27, 2026
b5b29a1
fix: update Java snippet to use Builder pattern
joalves Feb 27, 2026
9a0df6c
chore: add .worktrees to .gitignore
joalves Mar 6, 2026
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
176 changes: 167 additions & 9 deletions ...-Documentation/getting-started/import-and-initialize/_import-and-initialize.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,12 @@ import RubyImport from "!!raw-loader!./ruby/import.rb";

import FlutterImport from "!!raw-loader!./flutter/import.dart";

import DartImport from "!!raw-loader!./dart/import.dart";

import RustImport from "!!raw-loader!./rust/initialize.rs";

import LiquidImport from "!!raw-loader!./liquid/initialize.liquid";

Once the SDK is installed, it can be initialized in your project.

:::info
Expand Down Expand Up @@ -102,9 +108,9 @@ directly into the Provider component, like so:

```jsx
ReactDOM.render(
<ABSmartly context={context}>
<ABsmartly context={context}>
<App />
</ABSmartly>,
</ABsmartly>,
document.getElementById("root")
);
```
Expand Down Expand Up @@ -367,18 +373,170 @@ custom event logger), it can be done as following:

</TabItem>

<TabItem value="flutter" label="Flutter/Dart">
<TabItem value="dart" label="Dart">

<CodeBlock language="dart">{DartImport}</CodeBlock>

**SDK Options**

| Config | Type | Required? | Default | Description |
| :---------------------- | :-------------------------------- | :-------: | :---------: | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| endpoint | `String` | &#9989; | `null` | The URL to your API endpoint. Most commonly `"your-company.absmartly.io"` |
| apiKey | `String` | &#9989; | `null` | Your API key which can be found on the Web Console. |
| environment | `String` | &#9989; | `null` | The environment of the platform where the SDK is installed. Environments are created on the Web Console and should match the available environments in your infrastructure. |
| application | `String` | &#9989; | `null` | The name of the application where the SDK is installed. Applications are created on the Web Console and should match the applications where your experiments will be running. |
| retries | `int` | &#10060; | `5` | The number of retries before the SDK stops trying to connect. |
| timeout | `int` | &#10060; | `3000` | An amount of time, in milliseconds, before the SDK will stop trying to connect. |
| contextEventLogger | `ContextEventLogger` | &#10060; | `null` | A callback interface which runs after SDK events. See [Using a Custom Event Logger](#using-a-custom-event-logger) below |

**Advanced Configuration**

For advanced use cases where you need custom HTTP clients or data providers, you can still use the manual configuration approach:

```dart
final clientConfig = ClientConfig()
..setEndpoint("https://your-company.absmartly.io/v1")
..setAPIKey("YOUR-API-KEY")
..setApplication("website")
..setEnvironment("development");

final httpClientConfig = DefaultHTTPClientConfig()
..setMaxRetries(3)
..setConnectTimeout(5000);

final client = Client.create(
clientConfig,
httpClient: DefaultHTTPClient.create(httpClientConfig),
);

final sdkConfig = ABsmartlyConfig.create()
..setClient(client);

final sdk = ABsmartly(sdkConfig);
```

</TabItem>

<TabItem value="flutter" label="Flutter">

<CodeBlock language="dart">{FlutterImport}</CodeBlock>

**SDK Options**

| Config | Type | Required? | Default | Description |
| :---------- | :-------------------------------- | :-------: | :---------: | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| endpoint | `string` | &#9989; | `undefined` | The URL to your API endpoint. Most commonly `"your-company.absmartly.io"` |
| apiKey | `string` | &#9989; | `undefined` | Your API key which can be found on the Web Console. |
| environment | `"production"` or `"development"` | &#9989; | `undefined` | The environment of the platform where the SDK is installed. Environments are created on the Web Console and should match the available environments in your infrastructure. |
| application | `string` | &#9989; | `undefined` | The name of the application where the SDK is installed. Applications are created on the Web Console and should match the applications where your experiments will be running. |
| Config | Type | Required? | Default | Description |
| :---------------------- | :-------------------------------- | :-------: | :---------: | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| endpoint | `String` | &#9989; | `null` | The URL to your API endpoint. Most commonly `"your-company.absmartly.io"` |
| apiKey | `String` | &#9989; | `null` | Your API key which can be found on the Web Console. |
| environment | `String` | &#9989; | `null` | The environment of the platform where the SDK is installed. Environments are created on the Web Console and should match the available environments in your infrastructure. |
| application | `String` | &#9989; | `null` | The name of the application where the SDK is installed. Applications are created on the Web Console and should match the applications where your experiments will be running. |
| retries | `int` | &#10060; | `5` | The number of retries before the SDK stops trying to connect. |
| timeout | `int` | &#10060; | `3000` | An amount of time, in milliseconds, before the SDK will stop trying to connect. |
| contextEventLogger | `ContextEventLogger` | &#10060; | `null` | A callback interface which runs after SDK events. See [Using a Custom Event Logger](#using-a-custom-event-logger) below |

**Advanced Configuration**

For advanced use cases where you need custom HTTP clients or data providers, you can still use the manual configuration approach:

```dart
final clientConfig = ClientConfig()
..setEndpoint("https://your-company.absmartly.io/v1")
..setAPIKey("YOUR-API-KEY")
..setApplication("website")
..setEnvironment("development");

final httpClientConfig = DefaultHTTPClientConfig()
..setMaxRetries(3)
..setConnectTimeout(5000);

final client = Client.create(
clientConfig,
httpClient: DefaultHTTPClient.create(httpClientConfig),
);

final sdkConfig = ABsmartlyConfig.create()
..setClient(client);

final sdk = ABsmartly(sdkConfig);
```

</TabItem>

<TabItem value="rust" label="Rust">

<CodeBlock language="rust">{RustImport}</CodeBlock>

**SDK Options**

| Config | Type | Required? | Default | Description |
| :---------- | :----------------------------------- | :-------: | :-------------------------------------------------------------------: | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| endpoint | `&str` or `String` | &#9989; | `undefined` | The URL to your API endpoint. Most commonly `"your-company.absmartly.io"` |
| api_key | `&str` or `String` | &#9989; | `undefined` | Your API key which can be found on the Web Console. |
| environment | `&str` or `String` | &#9989; | `undefined` | The environment of the platform where the SDK is installed. Environments are created on the Web Console and should match the available environments in your infrastructure. |
| application | `&str` or `String` | &#9989; | `undefined` | The name of the application where the SDK is installed. Applications are created on the Web Console and should match the applications where your experiments will be running. |
| retries | `u32` | &#10060; | `5` | The number of retries before the SDK stops trying to connect. |
| timeout_ms | `u64` | &#10060; | `3000` | An amount of time, in milliseconds, before the SDK will stop trying to connect. |
| agent | `String` | &#10060; | `None` | Custom user agent string for HTTP requests. |

**Builder Pattern**

The Rust SDK supports a fluent builder pattern for optional configuration:

```rust
let config = SDKConfig::new(
"https://your-company.absmartly.io/v1",
"YOUR-API-KEY",
"website",
"development",
)
.with_timeout(5000)
.with_retries(3)
.with_agent("my-app/1.0");

let sdk = ABsmartly::new(config)?;
```

</TabItem>

<TabItem value="liquid" label="Liquid (Shopify)">

<CodeBlock language="liquid">{LiquidImport}</CodeBlock>

**SDK Options**

| Config | Type | Required? | Default | Description |
| :---------- | :----------------------------------- | :-------: | :-------------------------------------------------------------------: | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| endpoint | `string` | &#9989; | `undefined` | The URL to your API endpoint. Most commonly `"your-company.absmartly.io"` |
| apiKey | `string` | &#9989; | `undefined` | Your API key which can be found on the Web Console. |
| environment | `"production"` or `"development"` | &#9989; | `undefined` | The environment of the platform where the SDK is installed. Environments are created on the Web Console and should match the available environments in your infrastructure. |
| application | `string` | &#9989; | `undefined` | The name of the application where the SDK is installed. Applications are created on the Web Console and should match the applications where your experiments will be running. |
| units | `object` | &#9989; | `{}` | An object containing unit identifiers (e.g., session_id, customer_id) used for experiment assignment. |

**Server-Side Rendering**

For Shopify Liquid templates, ABsmartly can be integrated server-side to pre-fetch context data:

```liquid
{% comment %}
Render the ABsmartly initialization snippet
This can be used to embed pre-fetched context data
{% endcomment %}
{% render 'absmartly-init',
session_id: request.cookie.session_id,
customer_id: customer.id
%}
```

**Using ABsmartly in Templates**

Once initialized, you can use ABsmartly treatments in your Liquid templates:

```liquid
{% if absmartly.treatment.banner_color == 1 %}
<div class="banner banner-red">Special Offer!</div>
{% else %}
<div class="banner banner-blue">Special Offer!</div>
{% endif %}
```

</TabItem>

Expand Down
10 changes: 10 additions & 0 deletions docs/APIs-and-SDKs/SDK-Documentation/getting-started/import-and-initialize/dart/import.dart
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
import 'package:absmartly_sdk/absmartly_sdk.dart';

void main() async {
final sdk = ABsmartly.create(
endpoint: 'https://your-company.absmartly.io/v1',
apiKey: 'YOUR-API-KEY',
application: 'website',
environment: 'development',
);
}
17 changes: 7 additions & 10 deletions ...APIs-and-SDKs/SDK-Documentation/getting-started/import-and-initialize/flutter/import.dart
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,11 +1,8 @@
void main() async{
final ClientConfig clientConfig = ClientConfig()
..setEndpoint("https://your-company.absmartly.io/v1")
..setAPIKey("YOUR API KEY")
..setApplication("website")
..setEnvironment("development");

final ABSmartlyConfig sdkConfig = ABSmartlyConfig.create()
.setClient(Client.create(clientConfig));
final ABSmartly sdk = ABSmartly(sdkConfig);
void main() async {
final sdk = ABsmartly.create(
endpoint: 'https://your-company.absmartly.io/v1',
apiKey: 'YOUR-API-KEY',
application: 'website',
environment: 'development',
);
}
29 changes: 29 additions & 0 deletions ...and-SDKs/SDK-Documentation/getting-started/import-and-initialize/liquid/initialize.liquid
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,29 @@
{% comment %}
Initialize the ABsmartly SDK in your Shopify theme
Add this to your theme.liquid layout file, typically in the <head> section
{% endcomment %}

<script>
window.absmartlyConfig = {
endpoint: 'https://your-company.absmartly.io/v1',
apiKey: 'YOUR-API-KEY',
application: '{{ shop.name }}',
environment: 'production',
units: {
session_id: '{{ request.cookie.session_id }}',
{% if customer %}customer_id: {{ customer.id }}{% endif %}
}
};
Comment on lines +6 to +16

@coderabbitai coderabbitai Bot Jan 30, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

⚠️ Potential issue | 🟠 Major

Escape Liquid output to keep JS valid and avoid injection.
shop.name, request.cookie.session_id, and customer.id are interpolated without JSON encoding; quotes or special characters can break the script or introduce XSS. Use the json filter to safely serialise values.

Proposed fix 
-  window.absmartlyConfig = {
-    endpoint: 'https://your-company.absmartly.io/v1',
-    apiKey: 'YOUR-API-KEY',
-    application: '{{ shop.name }}',
-    environment: 'production',
-    units: {
-      session_id: '{{ request.cookie.session_id }}',
-      {% if customer %}customer_id: {{ customer.id }}{% endif %}
-    }
-  };
+  window.absmartlyConfig = {
+    endpoint: 'https://your-company.absmartly.io/v1',
+    apiKey: 'YOUR-API-KEY',
+    application: {{ shop.name | json }},
+    environment: 'production',
+    units: {
+      session_id: {{ request.cookie.session_id | json }}{% if customer %},
+      customer_id: {{ customer.id | json }}{% endif %}
+    }
+  };
🤖 Prompt for AI Agents 
In
`@docs/APIs-and-SDKs/SDK-Documentation/getting-started/import-and-initialize/liquid/initialize.liquid`
around lines 6 - 16, The Liquid template embeds unescaped values into
window.absmartlyConfig (application, units.session_id, units.customer_id) which
can break JS or enable XSS; update the template to JSON-encode those
interpolations using the Liquid json filter (e.g. application: {{ shop.name |
json }}, session_id: {{ request.cookie.session_id | json }}, and customer_id: {{
customer.id | json }}) so the values are safely serialized for inclusion in the
script.

</script>

{% comment %}
Include the ABsmartly client-side SDK
This should be loaded before any code that uses the ABsmartly context
{% endcomment %}
<script src="https://cdn.absmartly.com/absmartly.min.js"></script>

<script>
ABSmartly.createContext(window.absmartlyConfig).then(function(context) {
window.absmartlyContext = context;
});
</script>
2 changes: 1 addition & 1 deletion docs/APIs-and-SDKs/SDK-Documentation/getting-started/import-and-initialize/ruby/import.rb
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
Absmartly.configure_client do |config|
ABsmartly.configure_client do |config|
config.endpoint = "https://your-company.absmartly.io/v1"
config.api_key = "YOUR-API-KEY"
config.application = "website"
Expand Down
15 changes: 15 additions & 0 deletions .../APIs-and-SDKs/SDK-Documentation/getting-started/import-and-initialize/rust/initialize.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
use absmartly_sdk::{ABsmartly, SDKConfig};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
let config = SDKConfig::new(
"https://your-company.absmartly.io/v1",
"YOUR-API-KEY",
"website",
"development",
);

let sdk = ABsmartly::new(config)?;

Ok(())
}