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 --advertiserThe 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-sdk2. 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:
VITE_SPECIFY_ADVERTISER_KEY=sak_your_key_hereimport 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.
3. Connect consent
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.
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: 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.