SDK Configuration

Pass configuration in the queued init call or to new window.Upsurge(config).

Required and routing options

Option	Type	Default	Description
siteId	string	—	Public site identifier. Required. The SDK exchanges it for an origin-bound runtime token.
baseUrl	string	window.location.origin	Upsurge application/API origin. Production integrations must set https://api.upsur.ge.
assetBaseUrl	string	the core's version folder when the core loads from cdn.upsur.ge, otherwise ${baseUrl}/sdk	Folder the SDK loads its feature bundles and fonts from. Leave it unset unless a script loader hides the SDK's URL; then set it to the folder of the pinned core's release, for example https://cdn.upsur.ge/sdk/2.6.0, never https://cdn.upsur.ge/sdk itself. See Pin a version.
conversionEventType	'purchase' | 'checkout_complete'	'purchase'	Event that receives is_conversion: true.
profileToken	string	—	Optional short-lived, consent-gated storefront profile token minted by your trusted server. It is kept in memory only; rotate it with setProfileToken().

Queue and retry options

Option	Type	Default	Description
batchSize	number	100	Events that trigger an immediate batch flush. The ingestion API accepts at most 100 events per batch.
flushInterval	number	10000	Milliseconds between scheduled flushes.
maxQueueSize	number	1000	Maximum queued events before overflow handling.
maxRetries	number	3	Retries for network and server failures.
retryDelay	number	1000	Initial retry delay in milliseconds.
retryBackoff	number	2	Exponential retry multiplier.
sessionTimeout	number	1800000	Inactivity in milliseconds before a new session.

Client errors and rate-limit responses are not retried automatically.

Capture and privacy options

Option	Type	Default	Description
autoTrackPageViews	boolean	true	Capture the initial page view.
autoTrackSpaNavigation	boolean	true	Capture History API navigation and refresh page-targeted overlays.
autoTrackEngagementSummaries	boolean	true	Emit one bounded dwell, scroll, and interaction summary per page lifecycle.
respectDoNotTrack	boolean	false	Disable tracking when the browser advertises DNT.
enableFingerprinting	boolean	false	Opt in to device fingerprint generation.
debug	boolean	false	Write diagnostic messages to the console.

Partner attribution options

Partner attribution is off until partnerAttribution.mode is set.

Option	Type	Default	Description
mode	'disabled' | 'advertiser' | 'publisher'	'disabled'	Capture inbound advertiser traffic or explicitly track publisher outbound clicks.
attributionWindowDays	number	30	Eligible lookback, clamped to 1–90 days.
maxTouchChainLength	number	20	First-party chain cap, clamped to 1–20 touches.
outboundAllowedHosts	string[]	[]	Exact hosts accepted by publisher URL helpers.
autoDecorateOutboundLinks	boolean	false	Decorate and track only explicitly marked publisher anchors.
voucherMappings	object	{}	Merchant-owned voucher code to provider/partner mappings.

partnerAttribution: {
  mode: 'advertiser',
  attributionWindowDays: 30,
  maxTouchChainLength: 20,
  voucherMappings: {
    CREATOR10: { provider: 'awin', partnerId: '12345' },
  },
}

Advertiser mode automatically detects AWIN awc and CJ cjevent on initialization. Provider IDs, publisher references, partner IDs, sub-IDs, and vouchers remain distinct. Arbitrary unmapped voucher query values are ignored.

Advertiser mode also resolves eligible partner-experiment assignments before campaign modules load. Publisher automatic decoration requires exact allowlisted hosts and anchors marked with data-upsurge-partner-provider plus data-upsurge-click-reference.

Revenue attribution options

Store revenue attribution is off unless the site enables it. Consent is denied until you supply it.

Option	Type	Default	Description
revenueAttribution.enabled	boolean	false	Capture the signed journey token that commerce integrations attach to carts and orders.
revenueAttribution.consent.analytics	boolean	false	Without analytics consent, only session-scoped state is retained.
revenueAttribution.consent.advertising	boolean	false	Advertising consent for attribution persistence.

Update consent at runtime with setAttributionConsent({ analytics, advertising }).

Workflow command options

Workflows can show an overlay, open a chatbot, or refresh recommendations in the visitor's browser. See Run a campaign in the visitor's browser.

Option	Type	Default	Description
workflowCommands.enabled	boolean	true	Poll for site-scoped workflow commands. Polling does no work when no commands exist.
workflowCommands.pollingIntervalMs	number	15000	Poll interval, clamped to 5–60 seconds.
workflowCommands.consent.marketing	boolean	false	Allow marketing-purpose commands.
workflowCommands.consent.personalization	boolean	false	Allow personalization-purpose commands.

Update consent at runtime with setWorkflowCommandConsent().

What the chat widget reads from the page

The chat widget needs no options of its own, but it reads these from your storefront page:

Source	What it is for
<html lang> (else the browser language)	The widget's language: English, Spanish, French or German; anything else shows English. The welcome and the assistant's replies follow it too.
<meta name="upsurge:page"> and <meta name="upsurge:product">	What the page is, for stores whose URLs don't say it, such as /p/123 or product.html?id=123. upsurge:page is home, product, collection, cart, checkout, search or other, and wins over the URL; any other value is ignored. upsurge:product is your Upsurge product ID or your store's product ID; on its own it means a product page. The product line and product suggestions appear only when Upsurge finds that product in your catalog. A page with either tag is described by its tags alone. Needs SDK 3.0.2 or later.
The first element with a data-product-id attribute	The product the welcome and the assistant talk about, on product pages whose URL doesn't name it and that have neither tag. Use your Upsurge product ID or your store's product ID. Shopify /products/<handle> and WooCommerce /product/<slug> pages don't need it, and their URL wins over the attribute. On a page whose URL isn't a product page, the attribute is ignored: it may belong to a cart drawer or a recommendation.
The cart from commerce events or setCartContext()	Sent only from cart and checkout pages: pages tagged cart or checkout, or untagged /cart and /checkout pages. Upsurge checks every item against your catalog. A cart it cannot use, for example one with more than 20 items, is left out; the chat still works.

For a product page whose URL doesn't name the product, add both tags to the page's <head>. For a cart or checkout page, add <meta name="upsurge:page" content="cart"> or content="checkout".

<meta name="upsurge:page" content="product">
<meta name="upsurge:product" content="prod_123">

Put the tags in the page before the Upsurge SDK starts, in the HTML or from your script before you call init. The widget fetches its welcome when the shopper first reaches for the chat, so tags added later miss the welcome.

The widget asks for its welcome only when a shopper opens the chat, or points at, focuses or touches the launcher. It never asks at page load.

Callbacks

Option	Signature	Runtime status
onEventQueued	(event) => void	Called after an event enters the queue.
onEventSent	(event) => void	Called once for every event accepted by batch ingestion. Failed events are requeued without invoking it.
onError	(error) => void	Called for transport or runtime errors handled by the SDK.

Production-oriented example

window.UpsurgeQueue = window.UpsurgeQueue || [];
window.UpsurgeQueue.push([
  'init',
  {
    siteId: 'site_replace_me',
    baseUrl: 'https://api.upsur.ge',
    conversionEventType: 'purchase',
    batchSize: 50,
    flushInterval: 5000,
    autoTrackPageViews: true,
    autoTrackSpaNavigation: true,
    respectDoNotTrack: true,
    enableFingerprinting: false,
    onError(error) {
      console.error('Upsurge SDK error', error);
    },
  },
]);

Do not pass the internal preloadedOverlays or preloadedChatbots test/demo options in a production storefront integration.