Skip to main content

Client API Reference

These are all the methods that are available in the Cartesian function. You can use either:

  1. The snippet provided: window.Cartesian

or

  1. The npm module:
import { Cartesian } from '@cartesianio/agent-sdk';

Event Subscription​

The Cartesian event system allows you to subscribe to various system events using the 'subscribe' method. This enables you to respond to important state changes and lifecycle events within the Cartesian agent.

window.Cartesian('subscribe', event, callback);

Parameters

  • event (string): The name of the event to subscribe to
  • callback (Function): The function to execute when the event occurs

Available Events:​

load​

Triggered when the agent Javascript is fully loaded and initialized.

load: () => void;

ready​

Triggered when the agent is ready to start or is already running (if autoStart is true).

ready: () => void;

stopped​

Triggered when the agent stops, including optional error information.

stopped: (error?: Error) => void;

sidebar:visibility-changed​

Triggered when sidebar visibility state changes.

'sidebar:visibility-changed': (isVisible: boolean) => void;

Agent Management​

agent-id:get​

Retrieve the current agent identifier.

const agentId = window.Cartesian('agent-id:get');

agent-id:set​

Configure the agent identifier.

window.Cartesian('agent-id:set', agentId);

Settings Management​

settings:get​

Retrieve specific setting values. Currently supports autoStart.

const autoStart = window.Cartesian('settings:get', 'autoStart');

settings:set​

Configure agent settings. Accepts partial settings objects.

window.Cartesian('settings:set', {
  autoStart: true,
});

Telemetry Configuration​

telemetry:set​

Control whether OpenTelemetry instrumentation is enabled for the agent. By default, telemetry is enabled. You can disable it by calling this method with false.

By default, the Agent sends operational telemetry data to Cartesian to help us improve the service and provide better support. This includes performance metrics, usage patterns, and diagnostic information. No sensitive customer data is included in telemetry.

info

This method must be called before the agent loads to take effect. Place it in your initialization code, before or immediately after the agent snippet.

// Optionally disable telemetry
window.Cartesian('telemetry:set', false);

Parameters:

  • enabled (boolean): true to enable telemetry, false to disable it

Default behavior:

  • If you don't call this method, telemetry is enabled by default
  • You only need to call this method if you want to explicitly disable telemetry

Module Control​

module:enable​

Enable specific functionality modules.

window.Cartesian('module:enable', 'moduleName');

module:disable​

Disable specific functionality modules.

window.Cartesian('module:disable', 'moduleName');

User Authentication​

user:login​

Configure user authentication with optional status callback. See Authentication for more information.

window.Cartesian('user:login',
	() => Promise<string>,
	(error?: Error) => void
);

Agent Lifecycle Control​

start​

Initialize and start the agent. This will throw an error if the agent is already running or if the 'user:login' callback is not set.

window.Cartesian('start');

stop​

Terminate agent operations.

window.Cartesian('stop');