Specify docsNode.js SDK
Reference for the Node.js SDK.
Serves ads from a server: a route handler, a server component, a background job.
Use the browser SDK where you can
Serving from a server costs you signal, and some of it is not recoverable:
- No identity cookie, so a visitor who connected a wallet elsewhere on the network cannot be recognised. You will fill only against the addresses you pass.
- Geolocation doesn't work, so geofenced / geo-targeted campaigns will not be served correctly.
Use it when a browser call is genuinely not an option. Otherwise reach for the Browser SDK.
1. Install
npm install @specify-sh/publisher-sdk2. Serve an ad
import { serve, ImageFormat } from '@specify-sh/publisher-sdk/server';
const ad = await serve({
publisherKey: process.env.SPECIFY_PUBLISHER_KEY,
walletAddresses: ['0x1111111111111111111111111111111111111111'],
imageFormat: ImageFormat.LANDSCAPE,
adUnitId: 'sidebar'
});
if (ad) {
render(ad);
}Options
| Option | Required | Description |
|---|---|---|
publisherKey | yes | Your key, spk_ followed by 30 characters |
walletAddresses | yes | One to 50 addresses, 0x plus 40 hex characters |
imageFormat | yes | LANDSCAPE, LONG_BANNER, SHORT_BANNER or NO_IMAGE |
adUnitId | no | An id of your choosing, so you can compare placements in reporting |
Image formats and SpecifyAd
Identical to the browser SDK: see image formats and SpecifyAd. Both entry points return the same shape.
Errors
ValidationError is thrown for invalid input before making a request:
- a publisher key that is not
spk_followed by 30 characters - an address that is not
0xplus 40 hex characters - an empty address list, or more than 50 unique addresses
Everything else returns null.
import { serve, ValidationError } from '@specify-sh/publisher-sdk/server';
try {
const ad = await serve({ publisherKey, walletAddresses, imageFormat });
} catch (error) {
if (error instanceof ValidationError) {
console.error(error.message);
}
}