Specify docsAnalytics SDK reference
Constructor, methods, captured events, and privacy posture for the optional Analytics SDK.
Coming soon
@specify-sh/advertiser-sdk is not published yet, so nothing on this page can be installed today.
You do not need it to run a campaign: conversions are measured onchain and require no integration at all. This SDK adds funnel visibility on your own site on top of that.
The Analytics SDK is an optional library you add to your own site to record funnel events: page views, wallet connections, and any product milestones you choose. Specify measures conversions onchain, so conversion measurement and billing need none of this.
Follow the setup guide for installation and consent.
Constructor
new SpecifyAnalytics({ propertyKey, privacy?, edge? })| Option | Required | Description |
|---|---|---|
propertyKey | Yes | Identifies your site. Throws if malformed. |
privacy.disableWalletDetection | No | Turns off automatic wallet detection. |
consentForEnhancedTracking()
consentForEnhancedTracking()Starts sending events, credentialed. Call on every page load where consent is granted.
revokeEnhancedTrackingConsent()
revokeEnhancedTrackingConsent()Stops sending immediately. Later events are held in memory only.
hasEnhancedTrackingConsent()
hasEnhancedTrackingConsent()Whether events are currently being sent.
identify(addressOrAddresses)
identify(addressOrAddresses)Registers wallet address(es) connected on your site, the strongest signal you can send. Call it in your wallet-connect callback (WalletConnect sessions are invisible to passive detection, so pass those here). Addresses accumulate across calls, are lowercased, and are validated for format; they ride along on every subsequent event.
logEvent(name, props?)
logEvent(name, props?)Records a product milestone, such as signup_completed or deposit_started. name is lowercase a-z, 0-9, and underscores, up to 64 characters. props is any JSON-serialisable object up to 8 KB.
getDetectedWallets()
getDetectedWallets()Addresses found by passive detection, lowercased.
destroy()
destroy()Flushes pending events and detaches all listeners. Call when tearing down an SPA view.
Captured events
Automatically:
page_view: on load and on client-side route changes in single-page apps. No configuration; duplicate views of the same URL are not re-emitted.wallet_detected/wallet_changed: the SDK passively notices wallets already connected to your page via EIP-6963 (with awindow.ethereumfallback). Detection is silent: it only reads already-connected accounts, never prompts, never opens a wallet, never requests permissions. Turn it off withprivacy.disableWalletDetection.
Manually:
logEvent(name, props?): any product milestone you choose to record.
Every event carries the page URL and referrer, a per-tab session id, the wallets known so far, and the click id (spclid) when the visit came from a Specify ad. The click id is captured from the landing URL automatically and kept for the whole session, so events after the first navigation still tie back to the ad.
Batching and network
Events are batched: flushed every few seconds, on batch fill, and when the page is hidden or closed. The SDK adds no meaningful network overhead.
If you enforce a Content-Security-Policy, add https://spfsrv.com to connect-src (and to script-src if you use the tag-manager install).
Privacy
- Consent-gated at the source. No consent means no network requests, not anonymised events, not "essential" events.
- No new data about anyone. The SDK sees only what your page already sees: its own URL, and wallets the user has already, voluntarily connected.
- Wallet detection never prompts and can be disabled entirely;
identify()andlogEvent()still work with detection off. - Nothing here affects billing. Events cannot trigger charges, and there's no incentive mechanism tied to volume.