Specify docs

JavaScript

Track conversions on your site with the browser SDK.

Set up with the wizard

Make sure your coding agent (such as Claude Code or Codex) is installed and signed in, then run this from your project directory:

npx @specify-sh/wizard --advertiser

The wizard uses your coding agent to inspect the project and plan the SDK integration. Review the plan and choose which events to capture before it makes changes.

After it finishes, review the uncommitted changes and replace sak_your_key_here with your advertiser key in the env file it names. Then follow the verification steps below.

Prefer to do it by hand? The manual steps below are the same setup.

Manual setup

Runnable example

vanilla-typescript is this guide as a working Vite app.

1. Install the SDK

npm i @specify-sh/advertiser-sdk

2. Create the client

You will need an advertiser key. See Advertiser keys.

Create the client once and import it wherever you need it. Load it on every page of your site, including the pages your ads link to.

This example uses Vite. Put your key in .env.local and restart the dev server:

.env.local
VITE_SPECIFY_ADVERTISER_KEY=sak_your_key_here
lib/specify.js
import Specify from '@specify-sh/advertiser-sdk';

export const specify = new Specify({
  advertiserKey: import.meta.env.VITE_SPECIFY_ADVERTISER_KEY
});

If you use another build tool, follow its instructions for exposing environment variables to the browser. For Next.js, follow the Next.js guide.

Pass your consent manager's answer for advertising on every page load, and again whenever it changes. It decides only whether Specify's cookie is used.

The SDK can still send events without cookies for visitors identified by a user ID, wallet address or ad click. See how consent works.

consent.js
import { specify } from './lib/specify';

// Adapt this to your consent manager
specify.setCookieConsent(cmp.getConsent().advertising);

cmp.onConsentChange((consent) => {
  specify.setCookieConsent(consent.advertising);
});

4. Identify the visitor

Identify visitors when they sign in, and on every page load while they're signed in. Use your own user ID, the one your server would use for them, not an email address.

identity.js
import { specify } from './lib/specify';

// After sign-in, and on every page load while signed in
specify.identify(user.id);

// When a wallet connects
specify.identify(walletAddress);

// On sign-out
specify.reset();

Give each person their own ID. A shared placeholder such as "guest" would count strangers as one visitor.

5. Capture conversions

Capture an event once the action has succeeded, such as after the sign-up request returns.

signup.js
import { specify } from './lib/specify';

await createAccount(form);
specify.capture('signup');

Use short, stable names such as signup or purchase. We agree with you which events count as conversions before your campaign launches.

If your server is what confirms the conversion, such as a payment clearing, capture it there instead and keep steps 1 to 4 on your site.

6. Check it works

Use a development key and open your browser's network panel. Go through your flow: requests to spfsrv.com/v1/identify and spfsrv.com/v1/events should return 200, and each event you capture appears in the event log on the Integration page within a few seconds. Development events never count towards your results.

Once your organization is approved, switch to a production key, run one test conversion yourself and confirm the Integration page shows it as your last production event.

Install with a script tag

For a site without a bundler, add this to every page instead of installing the npm package. Replace sak_your_key_here with your advertiser key:

<script>
  window.specifyAdvertiser = window.specifyAdvertiser || function () {
    (window.specifyAdvertiser.q = window.specifyAdvertiser.q || []).push(arguments);
  };
  window.specifyAdvertiser('init', { advertiserKey: 'sak_your_key_here' });
</script>
<script async src="https://spfsrv.com/sdk/advertiser.js"></script>

Follow steps 3 to 5 for consent, identity and conversions, using window.specifyAdvertiser() instead of client methods:

window.specifyAdvertiser('setCookieConsent', consentGiven);
window.specifyAdvertiser('identify', userId);
window.specifyAdvertiser('capture', 'signup');

// On sign-out
window.specifyAdvertiser('reset');

Commands sent before the script loads are queued. Initialize the SDK once per page. For Google Tag Manager, follow the GTM guide.

Network requirements

The SDK sends requests to https://spfsrv.com. If your site has a Content Security Policy, add it to connect-src.

If you use the script-tag installation, also add https://spfsrv.com to script-src and allow the inline initialization snippet in your policy.

Send requests straight to Specify rather than through a proxy on your backend. Behind a proxy, Specify can't recognise visitors who came from your ads.

Next steps

On this page