Specify Publisher SDK

JavaScript SDK for Specify Publishers to serve targeted content based on wallet addresses

---

> Now in beta!

The Specify Publisher SDK enables publishers to serve targeted ad content to users based on their wallet addresses.

Installation

``bash


Using bun

`

Basic Usage

`js
import Specify, { AuthenticationError, ValidationError, NotFoundError, APIError, ImageFormat } from "@specify-sh/sdk";

// Initialize with your publisher key and enable wallet caching
const specify = new Specify({
publisherKey: "your_publisher_key",
cacheMostRecentAddress: true // Do not enable this in server environments
});

// Serve content based on wallet address
async function serveContent() {
try {
const walletAddress = "0x1234567890123456789012345678901234567890";

// Serve content with a provided wallet address. The SDK will also use the wallet cache if available.
const content = await specify.serve(walletAddress, {imageFormat: ImageFormat.LANDSCAPE, adUnitId: "header-banner-1"});

// Or; serve content solely relying on the addresses cache (Only works if you have cacheAddressesInLocalSession enabled.)
const content = await specify.serve(undefined, {imageFormat: ImageFormat.SHORT_BANNER, adUnitId: "sidebar-ad-1"});
} catch (error) {
if (error instanceof AuthenticationError) {
// Handle authentication errors
} else if (error instanceof ValidationError) {
// Handle validation errors
} else if (error instanceof NotFoundError) {
// Handle no ad found error
} else if (error instanceof APIError) {
// Handle API errors
} else {
// Handle other errors
}
}
}

serveContent();
`

Advanced Usage

$3

You can provide a list of wallet addresses and we will find the best ad across all of them. This is useful if your users have multiple wallets connected at a given time for example.

`js
// Serve content matching across multiple wallet addresses (max 50).
const addresses = [
"0x1234567890123456789012345678901234567890",
"0xabcdefabcdefabcdefabcdefabcdefabcdefabcd",
"0x9876543210987654321098765432109876543210"
];

// Serve content with multiple provided addresses + SDK memory.
const content = await specify.serve(addresses, {imageFormat: ImageFormat.LONG_BANNER, adUnitId: "ad-unit-2"});
`

API Reference

$3

Creates a new instance of the Specify client.

- config.publisherKey - Your publisher API key (required, format: spk_ followed by 30 alphanumeric characters)
- config.cacheMostRecentAddress - Optional boolean, defaults to false. Set to true to enable caching the most recent wallet data across requests in supported environments (e.g., browser localStorage).

$3

Serves content based on the provided wallet address(es).

- addressOrAddresses - Optional. Single wallet address, array of wallet addresses (max 50), or undefined if relying solely on the cached wallet data. If cacheMostRecentAddress is true, the SDK will attempt to use the cached wallet data if available, either independently or in conjunction with provided addresses.
- Format: Standard EVM address format: 0x123...
- Automatically deduplicated by the SDK
- imageFormat - Required image format from the ImageFormat enum
- adUnitId - Optional arbitrary string identifier to identify where the ad is being displayed
- Returns: Promise resolving to ad content object (returns null if no ad is found)

#### Response Object

`typescript
interface SpecifyAd {
walletAddress: string;
campaignId: string;
adId: string;
headline: string;
content: string;
ctaUrl: string;
ctaLabel: string;
imageUrl: string;
communityName: string;
communityLogo: string;
imageFormat: "LANDSCAPE" | "LONG_BANNER" | "SHORT_BANNER" | "NO_IMAGE";
adUnitId?: string;
}
`

$3

The ImageFormat enum defines the available image format options:

- ImageFormat.LANDSCAPE - 16:9 - Landscape-oriented images
- ImageFormat.LONG_BANNER - 8:1 - Long banner format
- ImageFormat.SHORT_BANNER - 16:5 - Short banner format
- ImageFormat.NO_IMAGE - No image, text-only ads

$3

- AuthenticationError - Invalid API key format or authentication failure
- ValidationError - Invalid wallet address format, or too many addresses (>50)
- NotFoundError - No ad found for the provided address(es)
- APIError - Network errors or other HTTP errors

---

Build from Source

$3

- Bun

`bash


Clone the repository

Examples

Check out our examples repository for complete implementation examples in different frameworks and environments.

License

MIT