configure()

Configures the SDK. Must be called once, before any other SDK method.

Signature

function configure(config: EncoreConfig): boolean

Returns true on success. On invalid input it logs the validation error and returns false; it does not throw.

Configure-once: only the first successful call is honored. Subsequent calls log a warning and are ignored; reload the page to reconfigure.

Structure

interface EncoreConfig {
  apiKey: string;                          // required: your publishable key (pk_...)
  logLevel?: 'none' | 'debug';             // default 'none'
  unlockMode?: 'optimistic' | 'strict';    // default 'optimistic'
}

configure() carries connection and behavior settings only; there is no user id in it. The SDK generates an anonymous UUID on first load and persists it in localStorage (the same visitor keeps the same id across reloads); attach your real user id with identify() once you know it.

Field Reference

Field	Type	Required	Default	Description
`apiKey`	`string`	Yes	-	Publishable key (`pk_...`) from the Dashboard. Safe in client-side code.
`logLevel`	`string`	No	`'none'`	`'debug'` for verbose console logging during integration. Changeable later with `Encore.setLogLevel(level)`.
`unlockMode`	`string`	No	`'optimistic'`	When a claim counts as confirmed. `'optimistic'` confirms it at the moment of handoff to the advertiser. `'strict'` waits for the advertiser’s postback to verify it first. Session-wide, with no per-placement override, matching the native SDKs. See Unlock mode.

configure() carries connection and behavior settings only. Offer-surface copy is not set here: per-presentation copy is set via a placement’s headline / subheadline options (see placement()), and campaign copy is managed remotely per campaign.

Examples

import Encore from '@encorekit/web-sdk';

// Minimal: anonymous id auto-generated
Encore.configure({ apiKey: 'pk_live_yourpublishablekey' });

// Typical production setup
Encore.configure({
  apiKey: import.meta.env.VITE_ENCORE_API_KEY,
  logLevel: import.meta.env.DEV ? 'debug' : 'none',
});

React apps can use the provider instead (same options as props); see the React guide:

import { EncoreProvider } from '@encorekit/web-sdk/react';

<EncoreProvider apiKey={import.meta.env.VITE_ENCORE_API_KEY}>
  {children}
</EncoreProvider>

Inspecting the live configuration

function isConfigured(): boolean
function getConfiguration(): {
  apiKey: string;
  baseURL: string;
  analyticsBaseURL: string;
  logLevel: string;
} | null

getConfiguration() returns a read-only snapshot of what the SDK is actually using (including the resolved endpoint URLs), or null before a successful configure().

Encore.isConfigured();                         // true
Encore.getConfiguration()?.baseURL;            // the resolved API endpoint
Encore.getCurrentUserId();                     // the anonymous UUID, or your identify()'d id
Encore.getVersion();                           // the SDK version string

Unlock mode

unlockMode decides when the SDK treats a claim as confirmed. It is set once for the session, matching the UnlockMode axis on the native SDKs.

Mode	A claim is confirmed
`'optimistic'` (default)	At the moment of handoff to the advertiser.
`'strict'`	Once the advertiser’s postback verifies it.

Four things change in strict mode:

Offers are pre-filtered to campaigns whose postback latency can plausibly land inside the verification window, so the SDK does not serve an offer it already knows it cannot confirm in time. Such a fetch also bypasses the offer cache.
The entitlement grant is held. Optimistic mode signals a provisional grant at handoff. Strict mode signals nothing then, and a final grant once the postback verifies.
An unverified claim is retried on later page loads and on every return to the tab, for up to seven days.
Verification is reported through a callback, since it usually lands after show() has resolved. See onStrictUnlockVerified().

Encore.configure({
  apiKey: 'pk_live_yourpublishablekey',
  unlockMode: 'strict',
});

Encore.onStrictUnlockVerified((transactionId) => {
  // The advertiser postback confirmed this claim. Refresh entitlements from
  // your backend: this callback is a signal, not an authorization.
  void refreshEntitlements();
});

show() resolves 'claimed' at handoff in both modes, and ShowResult carries no verified flag. On the web the advertiser opens in a separate tab and the SDK renders nothing after a claim, so strict mode reports verification through the callback instead. Treat 'claimed' as a presentation fact in either mode, never as proof of conversion: access is server-authoritative.

An unrecognized unlockMode fails configure() rather than falling back, so a typo surfaces immediately.

identify(): attach your stable user id
show(): present offers
onStrictUnlockVerified(): strict-mode verification callback

iOS

Android

Web

Bridges

Signature

Structure

Field Reference

Examples

Inspecting the live configuration

Unlock mode

​Signature

​Structure

​Field Reference

​Examples

​Inspecting the live configuration

​Unlock mode

​Related

Signature

Structure

Field Reference

Examples

Inspecting the live configuration

Unlock mode

Related