Analytics SDK setup

Use this guide to install the Analytics SDK, wire up consent, and start capturing funnel events on your own site. For the full API and what the SDK captures, see the Analytics SDK reference.

Use the setup wizard: The wizard runs through the coding-agent CLI you already use, including Claude Code, Codex, Cursor, Gemini CLI, and others. It inspects your codebase, suggests the funnel events worth tracking based on what it finds there, proposes a plan for your approval, then implements and verifies it. If it cannot find an agent CLI, it prints the complete manual instructions.

npx @specify-sh/wizard --advertiser

The manual steps below remain the canonical setup path.

Quick start

npm install @specify-sh/advertiser

import { SpecifyAnalytics } from '@specify-sh/advertiser';
 
const analytics = new SpecifyAnalytics({ propertyKey: 'adv_…' });
 
// 1. Wire consent from your CMP / consent banner, on every page load:
onConsentChange((granted) =>
  granted
    ? analytics.consentForEnhancedTracking()
    : analytics.revokeEnhancedTrackingConsent(),
);
 
// 2. Tell Specify when a wallet connects on your site:
onWalletConnect((addresses) => analytics.identify(addresses));
 
// 3. Log the milestones you care about:
analytics.logEvent('signup_completed', { plan: 'pro' });

You’ll receive your adv_ property key when we set up funnel analytics for your campaign. It identifies your site, the same way a publisher key identifies a publisher.

Page views and wallet connections are captured automatically (see below), so for many sites steps 1 and 2 are the whole integration.

Consent comes first, literally

Nothing leaves the page without consent. Until your consent banner reports approval and you call consentForEnhancedTracking(), events are held in memory only. Never sent, never stored, gone when the tab closes. Granting consent releases the held events in order, so the landing-page view that happened moments before the user clicked “Accept” still makes it into the funnel. Revoking consent stops sending immediately.

Consent is deliberately not persisted by the SDK. It lives on the instance for the lifetime of the page, which keeps your CMP the single source of truth: call the gate on every page load where the user has consented, and a withdrawal takes effect on the very next pageview.

analytics.hasEnhancedTrackingConsent(); // -> boolean

With consent granted, the SDK sends credentialed requests, which is what lets Specify recognise the visitor as the same person who saw the ad on a publisher site: the cross-site link that makes the funnel joinable. The SDK itself never sees or handles that identifier; the mechanism is the same server-side identity used by Enhanced Tracking  on the publisher side.

Retargeting your visitors

The most valuable audience in advertising is the one that already came to you: people who saw your ad, visited your site, maybe connected a wallet, and left without converting. The Analytics SDK turns that audience into one your campaigns can reach again.

When a visitor connects a wallet on your site, passed through identify() or picked up by passive detection, that wallet becomes part of what Specify knows about your funnel. Because Specify serves ads by wallet across the whole network, those visitors can be retargeted wherever they show up next: on the wallets, explorers, and dapps where Specify serves, your campaign can specifically reach the users who visited but didn’t convert. For consenting users, Enhanced Tracking  extends that reach further. They can be recognised even on network pages where no wallet is connected at all.

The same signal works in reverse, and this is where it quietly pays for itself. Combined with exclusion targeting, visitors who did convert stop being shown your acquisition ads, so your budget concentrates on the warm middle of the funnel instead of people who are already users.

Talk to us about enabling a retargeting segment for your campaign. Because it’s built from your own visitors, it’s typically the highest-intent audience a campaign can run against.

Installing through a tag manager

If you’d rather not touch your bundle, the same feature set is available as a script through Google Tag Manager or any CMS that lets you add HTML:

<script>window.specifyAnalytics=window.specifyAnalytics||function(){(window.specifyAnalytics.q=window.specifyAnalytics.q||[]).push(arguments)};</script>
<script async src="https://spfsrv.com/sdk/advertiser/v1.js"></script>

Then use commands anywhere on the page, before or after the script loads; calls are queued and replayed in order:

<script>
  specifyAnalytics('init', { propertyKey: 'adv_…' });
  specifyAnalytics('consent');                          // from your CMP tag
  specifyAnalytics('identify', ['0xabc…']);             // on wallet connect
  specifyAnalytics('event', 'signup_completed', { plan: 'pro' });
</script>

Commands: init, consent, revokeConsent, identify, event. Tag ordering doesn’t matter. Commands fired before init are buffered and run once it arrives.

For the full method list, what gets captured, and the privacy posture, see the Analytics SDK reference.