@hiclimba/spot

Browser SDK for Climba Spot tracking and Shopify embedded app bootstrap.

Script Usage

<script>
  window.climbaSpotConfig = {
    appToken: 'spotpk_xxx',
    bootstrapShopify: true,
    collectWebVitals: true,
    trackPageViews: true,
  };
</script>
<script async src="https://unpkg.com/@hiclimba/spot@latest/climba-spot.js?appToken=spotpk_xxx"></script>

The default API URL is https://api.hiclimba.com. Use apiUrl or endpoint only for local, staging, or private deployments.

customerId is optional in Shopify embedded apps. Spot resolves the shop from window.shopify.config.shop first and stores browser session state in sessionStorage under toasty_spot_session.

Browser API

window.climbaSpot.track('event_name');
window.climbaSpot.page();
window.climbaSpot.bootstrapShopify();
window.climbaSpot.refreshSubscription();
window.climbaSpot.flush();
window.climbaSpot.getSession();
window.climbaSpot.configure({ debug: true });
window.climbaSpot.destroy();

Spot events are untrusted and non-billable. Verified Shopify session bootstrap may create or update Customer, AppInstallation, CustomerContact, and safe Admin-observed snapshots. The SDK must not store Shopify tokens, client secrets, raw GraphQL payloads, or raw provider responses.

Spot is a browser only SDK.

Delivery and configuration

track() queues a JSON snapshot and attempts delivery; flush() attempts the memory queue. Requests contain at most 100 events with the same captured app, API destination, customer, and session-token context. Every event retains its caller-provided idempotency key, or a key generated once when queued. Retries reuse the same payload and key even if caller-owned properties or configuration change afterwards.

A successful HTTP batch is not an acknowledgment of every event. Spot removes only individually accepted items, discards conclusive invalid/conflicting requests with safe debug diagnostics, and retains other failures or uncertain responses for the next track() or flush(). Retained items are attempted at most once per flush and do not block later batches. There is no retry timer or persistent event store. Browser reloads lose pending events, and events captured with expired credentials may remain undeliverable.

Constructor sessionToken applies before automatic events. configure() changes future events without rewriting queued identity or sending provider requests. Explicit apiUrl takes precedence over endpoint when both are passed. Changing the app, API destination, or customer clears incompatible session authority unless a replacement token is supplied. configure({ sessionToken: '' }) clears the token. Changing or clearing the configured customer starts a fresh browser session ID; queued events retain their original session. Reapplying the same customer or changing only the token preserves the browser session. Tracking enablement and debounce updates do not create an extra page view. destroy() stops route listeners and pending route callbacks.

Subscription refresh coalesces concurrent calls for the same context. Only refreshed, joined, already_fresh, and not_applicable are stored as completed for that browser session and redirect hint. failed, in_progress, invalid responses, and network failures can be retried by a later explicit refresh or normal bootstrap/redirect trigger. No automatic polling is added. Late bootstrap or refresh responses from an older configured identity are ignored. Bootstrap that changes customer or token authority starts a separate refresh context instead of joining an older in-flight request. Late results from that older request are ignored. Concurrent bootstrap calls still coalesce, and a previously completed refresh stays deduplicated for the same session and hint.