JavaScript

Set up with the wizard

npx @specify-sh/wizard --publisher

The wizard runs through the coding agent CLI you already use (Claude Code, Codex etc.). It inspects your codebase, proposes an integration plan for your approval, implements it as a reviewable diff, and verifies the result.

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

Manual setup

1. Install the SDK

npm i @specify-sh/publisher-sdk

2. Initialize the client

You will need a publisher key. See Publisher keys.

Create the client once and import it wherever you serve an ad. Use the publisher key via your environment.

const specifyPublisherKey = 'spk_123...' // Bring this from your environment

export const specify = new Specify({
  publisherKey: specifyPublisherKey
});

3. Connect consent

If your site has a consent management platform, connect its targeted-advertising state to the SDK on every page load. The SDK does not persist consent.

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

// Adapt this code to your cookie consent management tool
cmp.onConsentChange((consent) => {
  if (consent.targetedAdvertising) {
    specify.setCookieConsent(true);
  } else {
    specify.setCookieConsent(false);
  }
});

With consent granted, Specify recognises returning visitors across every site in our network, so a placement can fill even when the user has not connected a wallet to your app.

4. Make the first serve() call

Pass a wallet address that the user controls and choose the image format that matches your ad placement.

import { specify } from './lib/specify';
import { ImageFormat } from '@specify-sh/publisher-sdk';

try {
  const ad = await specify.serve('0x1111111111111111111111111111111111111111', {
    imageFormat: ImageFormat.LANDSCAPE
  });

  if (ad) {
    console.log('Headline:', ad.headline);
    console.log('Content:', ad.content);
    console.log('Image URL:', ad.imageUrl);
    console.log('CTA:', ad.ctaLabel, '->', ad.ctaUrl);
  } else {
    console.log('No ad found for this wallet');
  }
} catch (error) {
  console.error('Error serving ad:', error);
}

Available image formats and the fields returned in the ad can be found in the Browser SDK reference.

Network requirements

The SDK sends ad requests to https://spfsrv.com. After consent, the browser sends these requests with credentials. If your site has a Content Security Policy, add https://spfsrv.com to connect-src.

Send SDK traffic straight to Specify. Do not proxy it through your backend because a proxy strips cookies and geolocation information.

Next steps