Skip to content
adscapi

Getting started

Install the package, set platform tokens, verify they work, and fire one conversion event to every configured destination.

1. Install

shell
npm install adscapi
# or run the CLI without installing:
npx adscapi platforms

2. Set platform tokens

A platform is active only when its required secrets are present in the environment. List every destination and the exact secret names:

shell
npx adscapi platforms

Or walk through setup interactively (writes a .env):

shell
npx adscapi init

Per-platform guides under /docs/platforms show where each token comes from.

3. Verify

check confirms secrets are present; verify hits each platform’s API to confirm the token is valid. Prefer verify before you trust production traffic.

shell
npx adscapi check
npx adscapi verify

4. Track a conversion

One call. adscapi maps the event name, SHA-256 hashes identity fields, and dispatches to every configured platform. Pass raw email/phone — never pre-hash. Consent is required.

ts
import { createAdscapi } from 'adscapi';

const ads = createAdscapi(); // reads platform tokens from the environment

const results = await ads.conversions.track({
  name: 'purchase',
  value: 49,
  currency: 'USD',
  user: { email: 'jane@example.com' },   // raw — adscapi hashes advanced-matching fields per platform
  clickIds: { fbclid: '…', gclid: '…' }, // captured server-side
  consent: { adUserData: true, adPersonalization: true }, // optional: gppString, tcfString, limitedDataUse
});

// results: [{ platform: 'meta', ok: true }, { platform: 'tiktok', ok: false, error: '…' }, …]

Useful options on the second argument:

  • dryRun: true — log the fan-out without sending
  • testEventCodes: { meta: 'TESTxxxxx' } — send a real event to that platform’s Test Events view
  • destinations: { meta: false } — skip a platform for this call

5. Wire it at the conversion point

Call track from your backend when the conversion happens (signup, purchase, checkout). Send every identity field you have — firstName, city, state, zip, country, dateOfBirth, gender, externalId, ip, userAgent, fbc/fbp — more match keys raise match rate and lower CAC.

Canonical event names: page_view, lead, signup_start, signup, checkout_created, purchase, reply_generated, upgrade_clicked.

Next