Connect a Storefront

Upsurge hosts the production browser SDK and platform APIs. The SDK loads from cdn.upsur.ge; event, configuration, and widget requests go to the API at api.upsur.ge. Register the storefront domain first so platform traffic can be associated with the correct site.

Get the site ID

Use the path that matches your workspace state.

During setup

Complete the five-step setup wizard. The success screen shows the site ID and a ready-to-paste installation snippet.

Add another site

Open Dashboard → Sites, select Add site, and complete the site form. The new site ID is safe to place in storefront code. See Sites and API keys.

Server API access

Open Dashboard → API Keys only for server-to-server REST integrations. These keys are never used by the browser SDK.

The site ID is public. Browser security comes from the short-lived, origin-bound runtime token that the SDK obtains automatically—not from keeping the site ID secret or relying on CORS.

Add the browser script

Replace site_replace_me with the site ID from the dashboard. The production CDN and dashboard origins are fixed platform addresses.

Shopify stores can follow the illustrated Shopify app setup guide to install the app and configure its theme embed and app blocks instead of editing theme code. WooCommerce stores can use the Upsurge WordPress plugin.

Add this as early as practical in the storefront <head>:

storefront.html

<script>
  window.UpsurgeQueue = window.UpsurgeQueue || [];
  window.UpsurgeQueue.push([
    'init',
    {
      siteId: 'site_replace_me',
      baseUrl: 'https://api.upsur.ge',
      conversionEventType: 'purchase',
      respectDoNotTrack: true,
    },
  ]);
</script>
<script
  async
  src="https://cdn.upsur.ge/sdk/upsurge.min.js"
></script>

Keep the CDN and API origins separate

Load the script from https://cdn.upsur.ge, but set baseUrl to https://api.upsur.ge. If baseUrl is omitted, the SDK defaults to the merchant storefront and incorrectly attempts to call /api/v1/* there.

If the storefront sends a Content Security Policy, allow the CDN and API origins as described in Content Security Policy.

Queue calls made before the script loads

Because the script is asynchronous, add early calls as arrays:

<script>
  window.UpsurgeQueue.push([
    'trackProductView',
    {
      product_id: 'SKU-TRAIL-123',
      product_name: 'Trail Runner',
      product_price: 129.0,
      currency: 'USD',
    },
  ]);
</script>

After initialization, the tracker is available as window.upsurge and you can call its methods directly.

Optional initialization choices

• conversionEventType can be purchase (default) or checkout_complete.
• respectDoNotTrack defaults to false; enable it when your consent policy requires browser DNT to disable tracking.
• enableFingerprinting defaults to false and should remain opt-in.
• automatic initial page-view and single-page-app navigation tracking are enabled by default.

Continue to Send and verify the first event.