SDKWebJavaScript SDK

Methods and options

Methods and options of the Sidekick browser client.

Client options

create()

const ads = Sidekick.create({
  platformId: "plt_example",
  onError: (error) => console.error(error.message)
});

Parameter	Type	Description
`platformId`required	string	Public platform ID.
`baseUrl`	string	HTTPS API origin without a path. Defaults to https://sidekick-ads.com.
`visitorId`	string	Visitor ID, 16–128 characters. The SDK generates and persists it when omitted.
`storage`	string	local persists the ID in the browser; memory retains it for the client lifetime. Defaults to local.
`timeoutMs`	number	Request timeout, 100–30,000 ms. Defaults to 8,000.
`appearance`	object	Appearance for all cards
`onError`	function	Request and media error callback.

Required fields.

Methods

Method	Description
`create({ platformId, … })`	Creates a client.
`requestAd({ target, requestId, … })`	Requests and renders an ad. Returns Promise<{filled, fromCache?}>.
`fetchAd({ requestId, … })`	Returns Promise<ad \| null> for custom rendering.
`trackView(ad)`	Custom rendering: confirms the view once at least half of the card has been on screen for at least one second. The impression is paid only then.
`interact(ad, action)`	Returns Promise<ad \| null> with the next consent or quiz scene.
`setAppearance(options)`	Updates appearance without requesting a new ad.
`setScreenActive(active)`	Controls media playback on the screen.
`unmount(target)`	Removes the card from its container, retaining the client cache.
`dispose()`	Cancels requests and releases client resources.

Request options

Parameter	Type	Description
`target`required	HTMLElement	Card container. Required for requestAd().
`requestId`required	string	Ad slot ID within a message, 1–128 characters. Reuse it on rerenders.
`placement`	string	Placement name. Defaults to chat.
`languageCode`	string	Ad language. Defaults to the page language or en.
`acceptFormats`	string[]	Accepted formats; defaults to all six.
`context`	object	Context: conversation, article, feed or static.
`test / testFormat`	boolean / string	Test mode and test ad format.
`appearance`	object	Per-card appearance in requestAd().
`onFill / onNoFill`	function	requestAd() result callbacks.

Required fields.

Context fields →

Results and errors

requestAd() returns filled: true when the card is accepted for rendering, or filled: false on no-fill or request failure. fromCache: true indicates a cached result. The SDK confirms the view separately once the card is visible.

Request errors are passed to onError. fetchAd() returns null on failure. Invalid create() options throw an exception.

The cache belongs to one client and does not survive a page reload. A repeated HTTP request is a new issuance. The SDK does not automatically retry network failures.