Skip to main content
Version: Current platform

Public Methods

After initialization, use window.upsurge. Calls made earlier belong in window.UpsurgeQueue as arrays whose first item is the method name.

Lifecycle​

init(): void​

Initializes session state, auto-capture, the event queue, and eligible feature runtimes. Queued initialization calls invoke this automatically.

ready(): Promise<SdkRuntimeSnapshot>​

Initializes the tracker once when necessary and waits for the shared runtime-token bootstrap. The result contains status, expiry, capabilities, and App Check configuration only; it never exposes the bearer token.

getDiagnostics(): SdkDiagnosticsSnapshot​

Returns redacted integration state for a control room: SDK/runtime status, queue counts, campaign counts, consent, App Check, attribution, partner, and workflow readiness. Runtime/profile tokens, user/device identifiers, URLs, PII, and partner click identifiers are omitted.

flush(): Promise<FlushResult>​

Sends queued events immediately. The result contains processed, succeeded, and failed counts.

const result = await window.upsurge.flush();
if (result.failed > 0) {
  console.warn('Some Upsurge events failed', result);
}

shutdown(): Promise<void>​

Stops capture, flushes pending events, and destroys active feature runtimes. Call it before permanently replacing the tracker in a long-lived application.

isInitialized(): boolean​

Returns whether initialization completed and tracking is active.

Generic tracking​

track(eventType, properties?): void​

Queues a supported canonical event.

window.upsurge.track('page_view', { page_category: 'sale' });

trackCustom(eventName, properties?): void​

Queues the canonical custom event and places your name in properties.event_name.

window.upsurge.trackCustom('hero_cta_clicked', {
  placement: 'home_hero',
});

Identity and session​

identify(userId, traits?): void​

Associates subsequent events with a merchant-scoped authenticated user ID. Do not use an email address as the ID or put raw personal data in traits.

reset(): void​

Clears the identified user and rotates the session for a logout or account switch. It retains the current random or fingerprint-derived device ID; use clearFingerprint() when consent withdrawal also requires replacing a fingerprint-derived ID.

Identity getters​

getUserId(), getSessionId(), and getDeviceId() return current runtime identifiers. The SDK always creates a random device ID; opt-in fingerprinting can replace it with a fingerprint-derived ID.

Overlay lifecycle​

  • refreshOverlays() destroys current overlay triggers and fetches configuration for the current URL.
  • resetOverlays() destroys active overlay runtime state without fetching replacement configuration.

SPA navigation refreshes overlay configuration automatically when autoTrackSpaNavigation is enabled.

Commerce and product methods​

Typed helper payloads are documented in Event tracking. Widget runtimes emit most overlay, quiz, and chatbot lifecycle events automatically; avoid duplicating those calls in storefront code.

setCartContext(cart?): void​

Replaces the first-party cart snapshot supplied to chatbot turns on cart and checkout pages without emitting an analytics event. Use it when a commerce integration can read the current cart directly but should not synthesize a checkout event. Passing no cart, or a cart with no valid items, clears the snapshot.

window.upsurge.setCartContext({
  cart_id: 'cart_123',
  currency: 'USD',
  total: 148,
  items: [
    { product_id: 'product_123', product_name: 'Summit Board', quantity: 1, price: 148, currency: 'USD' },
  ],
});

getRecommendations(request): Promise<GetRecommendationsResponse>​

Fetches a custom recommendation surface through the SDK's existing authenticated transport. The SDK supplies its current device/user identity and optional in-memory profile token, so callers cannot override those values.

const result = await window.upsurge.getRecommendations({
  context: 'product_page',
  product_id: 'product_123',
  limit: 6,
});

for (const product of result.recommendations) {
  window.upsurge.trackRecommendationShown({
    recommendation_id: result.meta.recommendation_id,
    campaign_id: result.meta.campaign_id,
    product_id: product.product_id,
    position: product.position,
    experiment: result.meta.experiment,
    attribution_delivery_token: result.meta.attribution_delivery_token,
  });
}

Preserve meta.experiment and meta.attribution_delivery_token unchanged on impression and click events so experiment and revenue attribution remain canonical.

Embedded overlays​

mountEmbeddedOverlay({campaignId, container, placementId}): EmbeddedOverlayMountHandle​

Renders an active embedded overlay campaign inside an element you own, instead of as a floating popup. Embedded overlays skip launch triggers and frequency caps, but still respect campaign status, targeting, and experiment suppression.

const handle = window.upsurge.mountEmbeddedOverlay({
  campaignId: 'overlay_123',
  placementId: 'pdp-below-price',
  container: document.querySelector('#upsurge-embed'),
});

const status = await handle.ready; // 'mounted' | 'ineligible' | 'failed'
// Later, for example on SPA route change:
handle.destroy();

Mounting the same campaign into the same container again returns the existing handle.

Revenue attribution and profile tokens​

getJourneyToken(): string | undefined​

Returns the opaque, signed journey token that a commerce integration attaches to the cart or order. It returns undefined when revenue attribution is disabled or no token has been issued for the journey yet.

setAttributionConsent({analytics, advertising}): void​

Updates attribution consent. Consent is denied by default. Without analytics consent, only session-scoped attribution state is retained.

setProfileToken(profileToken?): void​

Rotates or clears the short-lived profile token minted by your server. The token is never written to browser storage. Overlays, chatbots, recommendations and Smart Search use what they know about a signed-in customer only when the browser holds a valid token. Tokens last five minutes; set a fresh one before the current one expires. See Signed-in customers.

Profile personalization​

updateProfilePersonalization(properties): void​

Queues a profile_personalization_updated event that upserts curated, consented personalization fields. Raw email, phone, address, location, and IP-shaped fields are removed before queueing. See Identity and privacy.

Clears the listed fields, or all personalization fields when none are listed. Without explicit consent metadata, the call is recorded as consent withdrawal for merchant personalization.

Workflow commands​

setWorkflowCommandConsent({marketing, personalization}): void​

Updates the consent used to decide which workflow commands may run in this browser. Both purposes are denied by default.

refreshWorkflowCommands(): Promise<void>​

Checks for pending workflow commands immediately instead of waiting for the next poll. Commands only run when workflowCommands.enabled is not false.

Privacy​

isFingerprintingEnabled(): boolean​

Reports whether opt-in fingerprinting is active.

clearFingerprint(): void​

Removes the fingerprint-derived device ID and replaces it with a random one. Call it after consent withdrawal.

Partner attribution​

capturePartnerInboundTouch(url?): PartnerTouchV1[]​

Parses a supported advertiser landing URL, stores newly deduplicated touches, and schedules delivery. init() calls this automatically in advertiser mode.

decoratePartnerUrl(provider, destinationUrl, reference): string​

Returns an allowlisted network URL with AWIN clickref or CJ sid. Decoration does not record a click. The exact destination host must appear in partnerAttribution.outboundAllowedHosts.

const href = window.upsurge.decoratePartnerUrl(
  'awin',
  'https://www.awin1.com/cread.php?awinmid=1001',
  'article-9',
);

trackPartnerOutboundClick(provider, destinationUrl, reference, options?): PartnerTouchV1 | null​

Records a publisher-mode outbound touch after destination validation. Options may include partnerId, voucherCode, campaignId, contentId, placementId, creativeId, subIds, and occurredAt.

getPartnerExperimentAssignments(): PartnerExperimentAssignment[]​

Returns the stable partner-experiment assignments active for the current advertiser session, including arm and suppressed/delivered campaign IDs.

isPartnerExperimentCampaignSuppressed(campaignId): boolean​

Returns true when a control assignment requires a custom campaign surface to stay suppressed. Built-in overlay and chatbot loading already applies assignment suppression.

getPartnerTouches(): PartnerTouchV1[]​

Returns the non-expired, bounded first-party touch chain.

clearPartnerAttribution(): void​

Deletes the first-party chain. Call it when consent withdrawal or a merchant deletion request requires attribution state removal.