Skip to main content

Getting Started

This page walks you through connecting your application to ABsmartly. By the end, you'll have the SDK installed, initialised, and a context ready to use for experiments.

Once you've finished here, the next page walks through a complete experiment: assigning variants, reading variables, and tracking goals. Together, these two pages give you everything you need to run your first test.

Prerequisites

Before you start, make sure you have:

  • An ABsmartly account with your Web Console set up
  • Your API key (found in Settings > API Keys in the Web Console)
  • Your application name and environment configured in the Web Console

Install the SDK​

Once your Web Console is setup and you have created some experiments, you can install our SDKs through your package manager, a CDN or by directly importing it.

npm install --save @absmartly/javascript-sdk
Other installation methods

Direct Import

<script src="https://unpkg.com/@absmartly/javascript-sdk/dist/absmartly.min.js"></script>
caution

ABsmartly’s Javascript SDK depends on support for a native ES6 promise implementation. If your environment does not support ES6 promises, you can polyfill.

Import and Initialise the SDK​

import absmartly from "@absmartly/javascript-sdk";

const sdk = new absmartly.SDK({
  endpoint: "https://your-company.absmartly.io/v1",
  apiKey: "YOUR-API-KEY",
  environment: "production",
  application: "website",
});

Every SDK requires four options:

OptionDescription
endpointYour API endpoint URL. Typically https://your-company.absmartly.io/v1
apiKeyFound in Settings > API Keys in the Web Console
environmentMust match an environment configured in the Web Console (e.g. "production", "development")
applicationMust match an application configured in the Web Console
Optional configuration

Beyond the four required options, every SDK also accepts these optional settings:

OptionDefaultDescription
retries5Number of retries before the SDK stops trying to connect
timeout3000 msHow long to wait for a response before giving up
eventLoggernoneCallback that fires on SDK events (exposures, goals, errors). See the custom event logger section below.
Language-specific differences

Most SDKs use the names and defaults above. A few differ:

  • Python: max_retries, connection_timeout (in seconds, not milliseconds), context_event_logger
  • Swift: retries defaults to 3 (not 5). Timeouts are in seconds, not milliseconds.
  • PHP: retries and timeout are int types. The event logger accepts a ContextEventLoggerCallback or any ContextEventLogger implementation.
  • Flutter/Dart: Does not expose retries, timeout, or eventLogger as top-level options. These are configured through the client config.
Using a custom event logger

The SDK fires events internally for things like exposures and goal tracking. By default these are handled automatically, but you can plug in a custom event logger if you need to:

  • Debug during development by printing events to the console
  • Send events to your own analytics pipeline alongside ABsmartly's collector
  • Monitor SDK behaviour in production for observability

The SDK can be instantiated with an event logger used for all contexts. In addition, most SDKs let you specify an event logger per context when calling createContext.

The event logger receives events with a data payload that depends on the event type. The SDK fires the following events:

EventWhenData
errorContext receives an errorError/exception object
readyContext turns readyContextData used to initialize the context
refreshrefresh() succeedsContextData used to refresh the context
publishpublish() succeedsEvent data sent to the ABsmartly collector
exposuretreatment() succeeds on first exposureExposure data enqueued for publishing
goaltrack() succeedsGoal data enqueued for publishing
close / finalizeContext is closed or finalizednull / undefined
Naming differences

Javascript, React, Vue, and Flutter use "finalize" for the close event. Python, Java, Go, Swift, .NET, PHP, and Ruby use "close". The method and event names in the code examples below match each SDK's convention.

const sdk = new absmartly.SDK({
  endpoint: "https://sandbox-api.absmartly.com/v1",
  apiKey: process.env.ABSMARTLY_API_KEY,
  environment: process.env.NODE_ENV,
  application: process.env.APPLICATION_NAME,
  eventLogger: (context, eventName, data) => {
    if (eventName == "error") {
      console.error(data);
    }
  },
});

Create a New Context Request​

A context represents a single user's session with ABsmartly. It holds their variant assignments and queues up events to send to the collector. You'll need to create one before you can check treatments or track goals.

const context = sdk.createContext({
  units: {
    user_id: "user-12345",
  },
});

await context.ready();
Using promises instead of async/await

If you're not in an async context, you can use the promise-based API:

const context = sdk.createContext({
  units: {
    user_id: "user-12345",
  },
});

context.ready().then(() => {
  const variant = context.treatment("experiment_name");
});
info

The user_id above is just an example. You can use any unit type that you've configured in your Web Console under Settings > Units (e.g. session_id, device_id, email). Pass all the units you have available for the current user. If you're not sure which ones to use, check Settings > Units in the Web Console. You'll see how these connect to experiments on the next page.

Next steps​

Your SDK is installed, initialised, and you have a context ready to go. Head over to Running Your First Experiment to learn how to assign variants, use variables, and track goals.