Aller au contenu principal
Version: Plateforme actuelle

SDK Installation

Install the browser SDK on every storefront page where you want tracking, overlays, recommendations, or chatbot campaigns to run.

Script install​

Upsurge hosts the production SDK and API on separate platform domains. Load the core script from cdn.upsur.ge, set baseUrl to the API origin, and replace the public site ID placeholder.

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

The SDK exchanges the site ID for a 15-minute runtime token in memory and refreshes it automatically.

https://cdn.upsur.ge/sdk/upsurge.min.js always serves the current SDK release. When Upsurge releases a new version, storefronts pick it up within five minutes, with no change to your snippet.

Do not use the merchant or CDN origin as baseUrl

baseUrl controls API traffic and must be https://api.upsur.ge in production. The CDN hostname serves only the SDK files, and the merchant storefront hosts neither the SDK nor the Upsurge APIs.

Content Security Policy​

If your storefront sends a Content-Security-Policy header, allow these sources:

DirectiveSourceWhy
script-srchttps://cdn.upsur.ge, plus a nonce or hash for the inline snippetThe core script, the Smart Search script if you add it, and the feature bundles the core loads on demand: overlays, chatbot, attribution and others.
style-srchttps://cdn.upsur.ge 'unsafe-inline'The overlay font stylesheet, the <style> elements overlays, the chatbot and Smart Search add to their widgets, and style attributes in custom-HTML overlay blocks.
font-srchttps://cdn.upsur.geThe fonts overlays and the chatbot use.
connect-srchttps://api.upsur.geAuthentication, events, campaign configuration, recommendations and search.
img-src, media-srchttps://firebasestorage.googleapis.com, and your product image hostImages and videos from the Upsurge media library, and the product images recommendations, the chatbot and Smart Search show.

The install snippet's first <script> is inline, so a policy without 'unsafe-inline' in script-src blocks it, and the SDK then never starts. Give that tag the nonce your policy issues, allow its 'sha256-…' hash, or move its contents into a file on your own domain loaded by a plain <script src> placed before the SDK tag.

Content-Security-Policy: script-src 'self' 'nonce-{per-response nonce}' https://cdn.upsur.ge; style-src 'self' 'unsafe-inline' https://cdn.upsur.ge; font-src 'self' https://cdn.upsur.ge; connect-src 'self' https://api.upsur.ge; img-src 'self' https://firebasestorage.googleapis.com; media-src 'self' https://firebasestorage.googleapis.com

Merge these sources into your existing policy rather than replacing it. If your style-src already uses a nonce or hash, browsers ignore 'unsafe-inline' there, and the SDK's widgets lose their styles. In that case, keep style-src free of nonces and hashes.

If you load the SDK from the API instead (https://api.upsur.ge/sdk/upsurge.min.js), allow https://api.upsur.ge in script-src, style-src, font-src and connect-src: the SDK then loads its bundles and fonts from the API origin.

If App Check is enabled for your site, the SDK also loads Google reCAPTCHA Enterprise. Allow the sources in Google's reCAPTCHA CSP guidance, and https://content-firebaseappcheck.googleapis.com in connect-src.

Pin a version​

Each release is also published, unchanged forever, under its own version folder. To control when your storefront moves to a new release, load the core from that folder, and Smart Search too if you use it:

<script async src="https://cdn.upsur.ge/sdk/2.6.0/upsurge.min.js"></script>
<script async src="https://cdn.upsur.ge/sdk/2.6.0/upsurge-search.min.js"></script>

A pinned core loads its feature bundles and fonts from the same folder, so with both tags pinned every file comes from one release. A pinned storefront receives no fixes until you change the version in the snippet. On a page with the queue snippet, window.upsurge.getDiagnostics().sdk_version reports the version running.

Script loaders that hide the script URL​

The SDK finds its version folder from its own <script> URL, when that URL is on cdn.upsur.ge. Script loaders such as Cloudflare Rocket Loader or Partytown hide the URL, and an inlined, re-bundled or self-hosted copy of the core has another one. The SDK then loads its bundles and fonts from baseUrl (https://api.upsur.ge/sdk/). That still works, but your Content Security Policy must then allow the API origin in script-src, style-src and font-src.

To keep those files on the CDN, pin the core and set assetBaseUrl to the same version folder:

window.UpsurgeQueue.push([
  'init',
  {
    siteId: 'site_replace_me',
    baseUrl: 'https://api.upsur.ge',
    assetBaseUrl: 'https://cdn.upsur.ge/sdk/2.6.0',
  },
]);

Change the core URL and assetBaseUrl together. A folder from another release logs a console warning, because its bundles don't match the core. https://cdn.upsur.ge/sdk without a version holds no bundles, so never use it as assetBaseUrl.

Validation checklist​

  • The script loads with a 200 response.
  • The site ID belongs to the storefront domain you are testing.
  • The browser console has no initialization errors.
  • A test event appears in analytics after sending your first tracking call.