JavaScript

Set up with the wizard

npx @specify-sh/wizard --advertiser

The wizard runs through the coding agent you already use (Claude Code, Codex etc.). It inspects your codebase, proposes which events to capture and implements them as a reviewable diff.

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

Manual setup

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.

import Specify from '@specify-sh/advertiser-sdk';

export const specify = new Specify({
  advertiserKey: process.env.SPECIFY_ADVERTISER_KEY
});

3. Connect consent

Pass your consent manager's answer for advertising on every page load, and again whenever it changes. Nothing is sent until the first call, so make it as soon as the answer is known. Pass false when the visitor declines: their events still count.

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.

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.

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: after the consent call, requests to spfsrv.com/v1/identify and spfsrv.com/v1/events should return 200. Development keys never record events, so nothing appears in your dashboard yet.

Network requirements

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

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