Configuration

This page is the reference for every option you can pass when initializing and rendering the SDK.

`MarkUpSDK.init(options)`

init validates your options and constructs the SDK singleton. It throws a ConfigurationError if publicKey or markupId is missing, or if markupId is not a valid UUID.

Option	Type
publicKey	string	Your SDK installation public key. See Create an SDK installation.
markupId	string	The MarkUp resource ID to load comments for. Must be a valid UUID.
onTokenNeeded optional	() => Promise<string>	Returns a signed JWT for bring-your-own-token auth. Omit to use the built-in Sign in with MarkUp flow.
sessionStorage optional	"memory" \| "sessionStorage" \| "localStorage"	Where to persist the resolved session. Default: `"memory"`.
debug optional	boolean	Enables `debug`-level console logging. Default: `false`.

Full init example


import {MarkUpSDK} from "@ceros/markup-sdk/ui";
 
const markup = MarkUpSDK.init({
    publicKey: "<YOUR_PUBLIC_KEY>",
    markupId: "<YOUR_MARKUP_ID>",
    sessionStorage: "localStorage",
    debug: false
});

`markup.render(options?)`

render mounts the shadow-DOM container, toolbar, pins, and panels, then runs the authentication gate to resolve a session and load live data. It throws an SDKStateError if the SDK isn’t initialized, and is a no-op (with a warning) if called twice. It returns the SDK instance, so calls can be chained.

render() is only available on the @ceros/markup-sdk/ui entry point. The headless @ceros/markup-sdk entry has no UI to mount.

Option	Type
position optional	"bottom-center" \| "bottom-right" \| "bottom-left" \| "top-center" \| "top-right" \| "top-left"	Toolbar anchor. Default: `"bottom-center"`.
offset optional	{x: number; y: number}	Pixel offset from the chosen anchor. Default: `{x: 16, y: 16}`.
theme optional	"light" \| "dark" \| "auto" \| "inverted"	Color theme for the SDK UI. Default: `"auto"`.
collapsed optional	boolean	Start the toolbar collapsed. Default: `false`.
draggable optional	boolean	Allow the user to drag the toolbar. Default: `true`.
persistPosition optional	boolean	Persist the dragged position across reloads. Default: `false`.
container optional	HTMLElement \| string	Mount point for the shadow-DOM host; a string is treated as a CSS selector. Default: `document.body`.
zIndex optional	number	z-index for the shadow container. Tune it if the SDK covers your overlays. Default: a very large value.
keyboardShortcuts optional	boolean	Enable global shortcuts (e.g. press `C` to toggle commenting mode). Default: `true`.

Full render example


markup.render({
    position: "bottom-right",
    offset: {x: 24, y: 24},
    theme: "auto",
    draggable: true,
    keyboardShortcuts: true
});

Toggle shortcuts at runtime after render():

Toggle shortcuts at runtime


markup.setKeyboardShortcutsEnabled(false);

Entry points

Import	`render()` available?	Notes
`@ceros/markup-sdk/ui`	Yes	Full UI: toolbar, pins, commenting mode. Bundles Preact.
`@ceros/markup-sdk`	No	Headless API only: services, auth, events. Render your own UI.

Everything else — init, on/off/once, the projects / threads / comments / uploads services, and destroy — is identical on both entries.

Logging

Configure the SDK’s logger globally with configureLogger. Useful for routing SDK logs into your own telemetry or quieting them in production.

configureLogger


import {configureLogger} from "@ceros/markup-sdk/ui";
 
configureLogger({
    level: "warn",          // "debug" | "info" | "warn" | "error" — default "warn"
    prefix: "[MarkupSDK]",  // prefix on every log line
    enabled: true           // set false to silence the SDK entirely
});

Field	Type	Description
`level`	`"debug" \| "info" \| "warn" \| "error"`	Minimum level to output. Default `"warn"`.
`prefix`	`string`	Prefix for all log messages. Default `"[MarkupSDK]"`.
`enabled`	`boolean`	Enable or disable logging entirely. Default `true`.

Passing debug: true to MarkUpSDK.init() is a shortcut that raises the log level to debug for that instance.

Next steps

API reference — methods, services, events, and errors.
Authentication — what onTokenNeeded returns.