Core SDK

The Core SDK provides a type-safe client for the GBG Go Captain API. Use it on your server to authenticate, start journeys, manage tasks, connect devices, and generate the tokens and URLs needed to embed web journeys in your apps. Both language clients are generated from the same API specification, so they expose the same resources, the same methods, and the same request and response fields. Everything on this page applies to both; only the code differs.

Language	Package	Status
TypeScript	`@gbg/go-core`	Generally available
Java	`com.gbg:go-core-sdk`	Generally available

New to a language client? See TypeScript notes or Java notes for install details, runtime requirements, and language-specific features.

Installation

npm install @gbg/go-core

implementation 'com.gbg:go-core-sdk:0.2.1'

<dependency>
    <groupId>com.gbg</groupId>
    <artifactId>go-core-sdk</artifactId>
    <version>0.2.1</version>
</dependency>

The TypeScript package ships with both CommonJS and ES module builds and includes TypeScript declarations. It supports Node.js 18+, Bun 1+, Deno 1.39+, and modern browsers. The Java client requires JDK 11 or later.

Authentication

Generate an access token with your API client credentials, then pass it to the SDK. Create API clients in the Clients tab of the Account management portal. See Manage API clients.

import { Go } from "@gbg/go-core";

// Generate a token
const go = new Go();
const token = await go.tokens.generate({
  grantType: "client_credentials",
  clientId: process.env.GO_CLIENT_ID!,
  clientSecret: process.env.GO_CLIENT_SECRET!,
  scope: "gbg.token",
});

// Use the token for subsequent calls
const authenticatedGo = new Go({
  customerAccess: token.accessToken,
});

import com.gbg.gocore.Go;
import com.gbg.gocore.models.ClientCredentialsGrantRequest;
import com.gbg.gocore.models.ClientCredentialsGrantRequestGrantType;
import com.gbg.gocore.models.Scope;
import com.gbg.gocore.models.operations.PostAsTokenOauth2Response;

// Generate a token
Go go = Go.builder().build();

PostAsTokenOauth2Response token = go.tokens().generate()
        .request(ClientCredentialsGrantRequest.builder()
            .grantType(ClientCredentialsGrantRequestGrantType.CLIENT_CREDENTIALS)
            .clientId(System.getenv("GO_CLIENT_ID"))
            .clientSecret(System.getenv("GO_CLIENT_SECRET"))
            .scope(Scope.GBG_TOKEN)
            .build())
        .call();

// Use the token for subsequent calls
Go authenticatedGo = Go.builder()
        .customerAccess(token.object().flatMap(body -> body.accessToken()).orElseThrow())
        .build();

The SDK also supports the password grant, which additionally takes a username and password. Use client_credentials unless you have been told otherwise.

In TypeScript you can set the GO_CUSTOMER_ACCESS environment variable instead of passing the token directly, and the SDK reads it automatically. The Java client has no equivalent fallback, so read the variable yourself and pass it to customerAccess().

Region selection

GBG Go is deployed across three regions. Both clients expose the same server list in the same order, so you can select a region by index or set the URL directly.

Index	Region	Server
0	Europe	`https://eu.platform.go.gbgplc.com/v2/captain`
1	Americas	`https://us.platform.go.gbgplc.com/v2/captain`
2	Australasia	`https://au.platform.go.gbgplc.com/v2/captain`

// By index
const go = new Go({
  serverIdx: 0, // 0 = Europe, 1 = Americas, 2 = Australasia
  customerAccess: process.env.GO_CUSTOMER_ACCESS,
});

// Or by URL
const go = new Go({
  serverURL: "https://eu.platform.go.gbgplc.com/v2/captain",
  customerAccess: process.env.GO_CUSTOMER_ACCESS,
});

// By index
Go go = Go.builder()
        .serverIndex(0) // 0 = Europe, 1 = Americas, 2 = Australasia
        .customerAccess(System.getenv("GO_CUSTOMER_ACCESS"))
        .build();

// Or by URL
Go go = Go.builder()
        .serverURL("https://eu.platform.go.gbgplc.com/v2/captain")
        .customerAccess(System.getenv("GO_CUSTOMER_ACCESS"))
        .build();

Each region covers a wider area than the code in its URL suggests. For example, organisations in the United Kingdom use the Europe (eu) endpoint.

If you’re not sure which region your organisation is set up in, contact us.

Available operations

These are the resources and methods exposed by the SDK. The names are identical in both languages. TypeScript uses properties (go.tokens.generate()); Java uses accessor methods and a terminal .call() (go.tokens().generate().call()).

Resource	Method	Description
`tokens`	`generate()`	Generate an access token
`journeys`	`start()`	Start a journey instance
`journeys`	`getState()`	Get journey state
`journeys`	`getSchemas()`	Get the JSON schemas for a journey’s interactions
`journeys`	`terminate()`	Terminate a journey
`interactions`	`fetch()`	Fetch the current interaction
`interactions`	`submit()`	Submit interaction data
`interactions`	`uploadAsset()`	Upload a file for an interaction
`devices`	`add()`	Generate a connect token
`devices`	`connect()`	Connect an end-user device
`devices`	`refresh()`	Renew a device session
`devices`	`validate()`	Validate an end-user session
`instances`	`handoffToken()`	Generate a handoff token for a journey instance
`instances`	`delete()`	Delete a journey instance
`addresses`	`search()`	Search for an address
`addresses`	`retrieve()`	Retrieve a full address
`testScenarios`	`create()`, `list()`, `get()`, `put()`, `delete()`	Manage test scenarios for a journey
`tasks`	`getSchema()`	Get a task’s schema (deprecated)

Start a journey

Pass the resource ID of the journey template you want to run. The response includes the instanceId you’ll use to track the journey.

const result = await go.journeys.start({
  resourceId: "your-journey-resource-id",
  context: {
    subject: {},
    config: { delivery: "page" },
  },
});

console.log(result.instanceId); // Use this to track the journey

import com.gbg.gocore.models.operations.Config;
import com.gbg.gocore.models.operations.StartJourneyContext;
import com.gbg.gocore.models.operations.StartJourneyRequest;
import com.gbg.gocore.models.operations.StartJourneyResponse;
import com.gbg.gocore.models.operations.StartJourneyContextSubject;

StartJourneyResponse result = go.journeys().start()
        .request(StartJourneyRequest.builder()
            .resourceId("your-journey-resource-id")
            .context(StartJourneyContext.builder()
                .subject(StartJourneyContextSubject.builder().build())
                .config(Config.builder().delivery("page").build())
                .build())
            .build())
        .call();

// Use this to track the journey
result.journeyStartResponse()
        .ifPresent(body -> System.out.println(body.instanceId()));

The resourceId uses the format <id>@<version>. Use @latest to always run the current published version of the template.

Connect an end-user device

Generate a connect token on your server, then pass it to the end user’s device.

// Server: create a connect secret
const connectResult = await go.devices.add({
  instanceId: "PiIuACmx8Q8R7qPnAkLAqBAT",
  scope: ["mobile"],
});

// Device: exchange the connect token for an end-user token
const deviceResult = await go.devices.connect(
  { deviceConnect: connectResult.connectToken },
  {
    deviceInfo: {
      deviceId: "device-uuid",
      deviceName: "iPhone 15",
      deviceType: "iOS",
    },
  }
);

import com.gbg.gocore.models.operations.AddDeviceRequest;
import com.gbg.gocore.models.operations.AddDeviceResponse;
import com.gbg.gocore.models.DeviceConnectRequest;
import com.gbg.gocore.models.DeviceInfo;
import com.gbg.gocore.models.operations.AddDeviceScope;
import com.gbg.gocore.models.operations.DeviceConnectResponse;
import com.gbg.gocore.models.operations.DeviceConnectSecurity;
import java.util.List;

// Server: create a connect secret
AddDeviceResponse connectResult = go.devices().add()
        .request(AddDeviceRequest.builder()
            .instanceId("PiIuACmx8Q8R7qPnAkLAqBAT")
            .scope(List.of(AddDeviceScope.MOBILE))
            .build())
        .call();

String connectToken = connectResult.deviceStartResponse().orElseThrow().connectToken();

// Device: exchange the connect token for an end-user token
DeviceConnectResponse deviceResult = go.devices().connect()
        .request(DeviceConnectRequest.builder()
            .deviceInfo(DeviceInfo.builder()
                .deviceId("device-uuid")
                .deviceName("iPhone 15")
                .deviceType("iOS")
                .build())
            .build())
        .security(DeviceConnectSecurity.builder()
            .deviceConnect(connectToken)
            .build())
        .call();

devices.connect uses the connect token as its credential rather than your customer access token, because it runs on the end-user device. In TypeScript you pass it as the first argument; in Java you pass it with .security().

Error handling

Every SDK call raises a single base error type carrying the HTTP status code and the response body.

import { Go } from "@gbg/go-core";
import * as errors from "@gbg/go-core/models/errors";

try {
  const result = await go.journeys.start({
    resourceId: "...",
    context: { config: { delivery: "page" } },
  });
} catch (error) {
  if (error instanceof errors.GoError) {
    console.error(`API error ${error.statusCode}: ${error.message}`);
    console.error("Response body:", error.body);
  }
}

import com.gbg.gocore.models.errors.GoException;
import java.io.UncheckedIOException;

try {
    StartJourneyResponse result = go.journeys().start()
            .request(StartJourneyRequest.builder()
                .resourceId("...")
                .context(StartJourneyContext.builder()
                    .config(Config.builder().delivery("page").build())
                    .build())
                .build())
            .call();
} catch (GoException ex) {
    // All SDK exceptions inherit from GoException
    System.err.printf("API error %d: %s%n", ex.code(), ex.message());
    System.err.println("Response body: " + ex.bodyAsString());
} catch (UncheckedIOException ex) {
    // Connection failure, timeout, and other I/O errors
}

The base error is called GoError in TypeScript and GoException in Java. In Java, network failures surface separately as UncheckedIOException rather than as an SDK error.

Retries

Configure retry behaviour when you build the client. Both languages use the same backoff strategy and the same parameters.

const go = new Go({
  customerAccess: process.env.GO_CUSTOMER_ACCESS,
  retryConfig: {
    strategy: "backoff",
    backoff: {
      initialInterval: 1,
      maxInterval: 50,
      exponent: 1.1,
      maxElapsedTime: 100,
    },
    retryConnectionErrors: false,
  },
});

import com.gbg.gocore.utils.BackoffStrategy;
import com.gbg.gocore.utils.RetryConfig;
import java.util.concurrent.TimeUnit;

Go go = Go.builder()
        .customerAccess(System.getenv("GO_CUSTOMER_ACCESS"))
        .retryConfig(RetryConfig.builder()
            .backoff(BackoffStrategy.builder()
                .initialInterval(1, TimeUnit.MILLISECONDS)
                .maxInterval(50, TimeUnit.MILLISECONDS)
                .baseFactor(1.1)
                .maxElapsedTime(100, TimeUnit.MILLISECONDS)
                .retryConnectError(false)
                .build())
            .build())
        .build();

Language-specific guides

Some features exist in only one client. These pages cover installation in detail and everything that has no counterpart in the other language.

TypeScript notes

Runtime support, standalone functions for tree-shaking, custom HTTP client, and debugging.

Java notes

Gradle and Maven setup, asynchronous calls, Optional handling, Jackson configuration, and logging.

SDKs

Installation

Authentication

Region selection

Available operations

Start a journey

Connect an end-user device

Error handling

Retries

Language-specific guides

TypeScript notes

Java notes

Further reading

​Installation

​Authentication

​Region selection

​Available operations

​Start a journey

​Connect an end-user device

​Error handling

​Retries

​Language-specific guides

TypeScript notes

Java notes

​Further reading

Installation

Authentication

Region selection

Available operations

Start a journey

Connect an end-user device

Error handling

Retries

Language-specific guides

Further reading