⁜ Obelism Improve
Getting started

Javascript

For a complete overview of features in the Javascript SDK check out the docs regarding those. For getting started read on.

Install

npm i @obelism/improve-sdk

Setup

Server setup

Configure the client

import { ImproveServerSDK } from '@obelism/improve-sdk'
 
const improveSdk = new ImproveServerSDK({
	organizationId: process.env.IMPROVE_ORGANIZATION_ID,
	environment: process.env.IMPROVE_ENVIRONMENT,
	token: process.env.IMPROVE_API_TOKEN,
})

Get the visitor ID

In the request handler it's possible to generate a visitor ID with the function;

improveSdk.generateVisitorId()

It's recommended to save this value in a cookie so it's possible to keep track of specific visitors and server them the same version of the AB test for each request. This could look like this;

export const GET = async (request: Request) => {
	const visitorCookieName = improveSdk.getVisitorCookieName()
	const visitorId =
		request.cookies.get(visitorCookieName)?.value ||
		improveSdk.generateVisitorId()
 
 // ...
 
	return new Response('...', {
		headers: {
			'Set-Cookie': `${visitorCookieName}=${visitorId}; Secure; Max-Age=2592000`,
		},
	})
}

We're not marking the cookie HttpOnly, this way we can read the value from the client and use it for analytic tracking

Get the visitor value

Now that we know who the visitor is on the server we can get them a value for AB test that we're running;

const userAgent = request.headers.get('userAgent')
improveSdk.getTestValue('example-test-slug', visitorId, userAgent)

Serverless

Running serverless you need to also set the test value in a response cookie, the next request the same user makes to your serverless function it might hit a different instance which has no recollection of the given value.

export const GET = async (request: Request) => {
    // ...
 
    const userAgent = request.headers.get('userAgent')
    const value = request.cookies.get('example-test-slug')?.value ||
        improveSdk.getTestValue('example-test-slug', visitorId, userAgent)
 
    // Alter the response based on the value
    const responseMessage = value === 'b' ? "alteration" : "original"
 
    return new Response(responseMessage, {
        headers: {
            'Set-Cookie': `example-test-slug=${value}; Secure; Max-Age=2592000`,
        },
    })
}

Serverfull

When having a long running server, you can utilize the cache within the SDK, this way setting the response cookie is not required. However if you want to send analytic events from the client your probably still want to.

export const GET = async (request: Request) => {
    // ...
 
    const userAgent = request.headers.get('userAgent')
    const value = improveSdk.getTestValue('example-test-slug', visitorId, userAgent)
 
    // Alter the response based on the value
    const responseMessage = value === 'b' ? "alteration" : "original"
 
    return new Response(responseMessage)
}

Client setup

Configure the client

Sync loading

import { ImproveClientSDK } from '@obelism/improve-sdk'
 
const client = new ImproveClientSDK({
	organizationId: process.env.IMPROVE_ORGANIZATION_ID,
	environment: process.env.IMPROVE_ENVIRONMENT,
})

Async loading

const { ImproveClientSDK } = await import('@obelism/improve-sdk/client')
 
const client = new ImproveClientSDK({
	organizationId: process.env.IMPROVE_ORGANIZATION_ID,
	environment: process.env.IMPROVE_ENVIRONMENT,
})

Get the visitor ID

Now that the client is setup it's time to get the config and setup the visitor. This will grab the values from the cookies and use them internally in the client.

await client.fetchConfig()
client.setupVisitor(window.navigator.userAgent)

(optional) Consume the test value

Getting the value for a test in the client is usually only needed for client side test where you can skip the Server setup. However it can happen that for a server test you want a tiny adjustment in some client side logic.

const value = client.getTestValue('example-test-slug')

Post an analytic message

Last up is pushing analytic messages, these are required for the monitoring. Make sure you're sending the events that are configured in the test setup to be able to get the conversion value.

client.postAnalytic('example-test-slug', 'pageView')

Previous

Getting Started

Next

React

On this page