Aller au contenu principal
Version: Plateforme actuelle

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.

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.