Skip to content
Docs menu Websites

Install the JavaScript SDK

Add the SDK to your site in the page head or through Google Tag Manager. Both load the same script from cdn.sfere.io and record page views right away

On this page

Before you start#

  • A website source in the dashboard and its browser write key. See Quickstart.
  • Access to your site’s HTML templates or to its Google Tag Manager container.

Use one method per page. Loading the SDK in the head and in Google Tag Manager on the same page sends every event twice.

Choose an install method#

Paste the loader once, anywhere before the closing </head> tag of every page, and replace YOUR_WRITE_KEY.

index.htmlHTML
<script>
  !(function (w, d) {
    if (w.sfere) return;
    var q = (w.sfere = []);
    ["track", "page", "identify", "group", "alias", "reset", "setConsent"].forEach(function (m) {
      q[m] = function () {
        q.push([m].concat([].slice.call(arguments)));
        return q;
      };
    });
    var s = d.createElement("script");
    s.async = true;
    s.src = "https://cdn.sfere.io/sdk/v0.4/sfere.min.js";
    s.setAttribute("data-write-key", "YOUR_WRITE_KEY");
    s.setAttribute("data-host", "https://events.sfere.io");
    d.head.appendChild(s);
    q.page();
  })(window, document);
</script>

The loader creates window.sfere straight away and queues every call until the SDK finishes loading, so sfere.track() works anywhere on the page.

  1. In Google Tag Manager, open your container and select Tags > New.
  2. Choose Tag Configuration > Custom HTML.
  3. Paste the loader below and replace YOUR_WRITE_KEY.
  4. Under Triggering, choose All Pages.
  5. Name the tag Sfere SDK, save it, then select Preview and load your site. The Sfere SDK tag should show as fired.
  6. Select Submit to publish the container.
Custom HTML tagHTML
<script>
  !(function (w, d) {
    if (w.sfere) return;
    var q = (w.sfere = []);
    ["track", "page", "identify", "group", "alias", "reset", "setConsent"].forEach(function (m) {
      q[m] = function () {
        q.push([m].concat([].slice.call(arguments)));
        return q;
      };
    });
    var s = d.createElement("script");
    s.async = true;
    s.src = "https://cdn.sfere.io/sdk/v0.4/sfere.min.js";
    s.setAttribute("data-write-key", "YOUR_WRITE_KEY");
    s.setAttribute("data-host", "https://events.sfere.io");
    d.head.appendChild(s);
    q.page();
  })(window, document);
</script>

To send custom events from other GTM tags, add Custom HTML tags that call window.sfere.track(...), fired by the trigger you need. Tags that run before the SDK loads are queued, not lost.

Pick a script URL#

URL Follows Use it when
https://cdn.sfere.io/sdk/v0.4/sfere.min.js Every 0.4.x release Default. You get fixes without changing your tag.
https://cdn.sfere.io/sdk/v0.4.1/sfere.min.js That exact version, never changes You pin a version with Subresource Integrity. The integrity hash is in manifest.json in the same folder.
https://cdn.sfere.io/sdk/latest/sfere.min.js Every stable release The tag lives somewhere you can never edit again.

Script tag options#

The loader sets data-write-key and data-host on the script it adds. To turn on batching, add s.setAttribute("data-batching", "true"); next to them.

Attribute Required What it does
data-write-key Yes The source’s browser key, keyId:secret.
data-host Yes https://events.sfere.io.
data-batching No "true" sends events in batches of up to 10, or every 5 seconds.

Debug logging is off by default. To see every event in the browser console while testing, load the SDK from npm with debug: true. See npm package.

Content Security Policy#

If your site sends a Content-Security-Policy header, allow the script host and the event host:

HTTP
Content-Security-Policy: script-src 'self' cdn.sfere.io; connect-src 'self' https://events.sfere.io;

If you use a nonce, put it on the loader’s <script nonce="..."> tag and keep cdn.sfere.io in script-src, or use 'strict-dynamic'.

Confirm it works#

  1. Open your site with the browser’s developer tools on the Network tab.
  2. Look for a request to https://events.sfere.io/api/s/p. The response is {"ok":true}.
  3. In the dashboard, open Live events and select your source.

Next steps#