Skip to main content

Script Tag

Add the following tag to your page to load the Allegro SDK:

<script src="https://your-allegro-instance.com/client.js"></script>

Replace your-allegro-instance.com with your Allegro domain.

How It Works​

client.js is a tiny loader script served by Allegro. When it runs, it creates a new <script> element pointing at the compiled SDK, injects two attributes automatically (data-csrf-token and data-tenant-config), and appends it to <head>. Any attributes you add to the original tag are forwarded to the injected script.

On load the SDK:

  1. Reads configuration from the script tag attributes and window.__allegro.
  2. Creates or restores device and session identifiers.
  3. Registers the built-in web components.
  4. Fires a page_view event.
  5. Dispatches allegro:ready on window.

window.__allegro Configuration​

If you need to configure the SDK without adding attributes to the script tag, set window.__allegro to a plain object before client.js loads:

<script>
    window.__allegro = {
        debug: true,
    };
</script>
<script src="https://your-allegro-instance.com/client.js"></script>
PropertyTypeDescription
debugbooleanEnable debug mode. See Debug Mode.
apiUrlstringOverride the API base URL. Defaults to the origin of client.js. Rarely needed.
note

Security-sensitive values (csrfToken, tenant) are always injected by the server and cannot be overridden from the page.

Attributes​

AttributeInjected automaticallyDescription
data-tenant-configYesJSON object with tenant settings (enabled login providers, cookie domain, etc.).
data-debugNoEnable debug mode. Presence of the attribute (or ="true") is enough. See Debug Mode.
data-api-urlNoOverride the API base URL. Defaults to the origin of client.js. Rarely needed.

Debug Mode​

Debug mode writes verbose SDK logs to the browser console. Enable it in any of four ways:

window.__allegro (set before the script tag):

<script>window.__allegro = { debug: true };</script>
<script src="https://your-allegro-instance.com/client.js"></script>

Attribute on the script tag:

<script src="https://your-allegro-instance.com/client.js" data-debug></script>

URL parameter (persisted to localStorage for the session):

https://example.com/article?allegro_debug=1

Pass allegro_debug=0 to clear it.

Browser console (takes effect immediately, persists across page loads):

window.allegro.debug();

allegro:ready Event​

The SDK dispatches allegro:ready on window once initialization is complete. Use this if you need to interact with the SDK after it has loaded but cannot guarantee the callback queue has been set up:

window.addEventListener('allegro:ready', function () {
    window.allegro.push(function (allegro) {
        // SDK is ready
    });
});

For most use cases the event queue pattern is simpler — callbacks pushed to window.allegro before the SDK loads are replayed automatically.

Embed Snippet​

Allegro administrators can inject custom JavaScript into every page that loads client.js via Organization Settings → Embed Snippet. The snippet is appended directly to the loader and executes in the same context as the SDK, after initialization is complete.

A typical snippet uses the event queue pattern to run code once the SDK is ready:

window.allegro.push((allegro) => {
    // Runs after Allegro initializes on every page
});

The snippet is served as part of client.js and is cached for up to 5 minutes. Changes made in the admin may not appear on your site immediately — allow up to 5 minutes for the cache to expire.

Version history

Every save creates a revision. Administrators can browse diffs and restore any previous version from the Version History panel in the Embed Snippet settings page.

Async Loading​

The loader script is injected with async = true by default so it does not block page rendering. To load the SDK synchronously (for example, in a server-side rendering environment where you need it available before paint), add ?async=false to the client.js URL:

<script src="https://your-allegro-instance.com/client.js?async=false"></script>