Getting Started

You need early access before any call works. Apply through Early Access first, then come back here.

1. Load the SparkLoop script

Add the SparkLoop embed script to your page, using your publication ID:

<script async src="https://js.sparkloop.app/embed.js?publication_id=pub_YOUR_PUBLICATION_UUID" data-sparkloop></script>

2. Turn on client mode

Set the SparkLoop mode to client in its own script tag:

<script>
  window.SL = { mode: "client" };
</script>

This script does not need to sit above the embed tag: the embed loads asynchronously and waits for DOMContentLoaded plus a short delay (800ms by default, configurable via window.sparkloop_delay) before it reads window.SL.mode.

In client mode SparkLoop never renders the managed signup-flow widget — your code is fully in charge of the UI.

3. Wait until SparkLoop is ready

Once the script has initialized, it fires an sl:ready event on document. That's your signal to start making calls:

<script>
  window.SL = { mode: "client" };

  document.addEventListener("sl:ready", async () => {
    const recommendations = await SL.client.recommendations.generate({ limit: 5 });
    // render the recommendations in your UI
  });
</script>

Test mode

While you build, turn on test mode so your calls don't count as real traffic: add test_mode: true to your config or ?test_mode=true to your page's URL. You get the same responses, but nothing is recorded. Read more in Testing Your Integration.

Using the npm package

If you bundle your frontend, you can install SparkLoop from npm instead of loading the script tag:

npm i sparkloop

Then initialize it with your publication ID and client mode — this replaces steps 1 and 2:

import sparkloop from "sparkloop";

sparkloop("pub_YOUR_PUBLICATION_UUID", { mode: "client" });

Everything else works exactly the same: the sl:ready event fires on document, the SDK lives at SL.client, and any configuration option goes in the same options object — for example test mode:

sparkloop("pub_YOUR_PUBLICATION_UUID", { mode: "client", test_mode: true });

Next steps

• Recommendations — generate recommendations and subscribe your readers to them.

• Offers — generate offers and claim them.

• Testing Your Integration — run every call in test mode while you build.

• Errors & Warnings — error handling and the rules you must follow.