Audience Connector setup

The Audience Connector runs in your infrastructure. Askdepth sends signed requests for schema, audience counts, and mapped candidate rows. Your database credentials stay in your environment; the selected candidate data returned by the connector is sent to Askdepth.

This is an integration with your existing audience data. It does not search the internet or automatically recruit new people.

Install

$ npm install @askdepth/audience-connector express pg

The connector exposes a Web-standard fetch(Request): Promise<Response> handler and framework shims. Run it in a Node environment with Buffer, crypto, fetch, Request, Response, and AbortController support. Install only the framework/adapter peers you use.

Express and PostgreSQL

import express from 'express';
import { Pool } from 'pg';
import { createConnector, postgresAdapter } from '@askdepth/audience-connector';
import { expressHandler } from '@askdepth/audience-connector/express';

const secret = process.env.ASKDEPTH_SECRET;
if (!secret) throw new Error('ASKDEPTH_SECRET must be configured');

const connector = createConnector({
  secret,
  adapter: postgresAdapter({
    pool: new Pool({ connectionString: process.env.DATABASE_URL }),
    table: 'users',
  }),
  // Connector configuration: canonical field -> your source column.
  fieldMapping: {
    externalId: 'id',
    email: 'email_address',
    segment: 'plan',
    signupAt: 'created_at',
    isActive: 'is_active',
  },
});

const app = express();
app.use(express.raw({ type: 'application/json' }));
app.use(expressHandler(connector));
app.listen(8080);

The default base path is /askdepth/v1; configure the platform with the complete base URL, for example https://audience.example.com/askdepth/v1.

Preserve the request bytes. Do not put express.json() before this handler unless its verify callback also captures the exact raw body as req.rawBody. The shim can consume raw streams or buffers; an already parsed object fails signature verification and causes a shim configuration error.

Use your own read-only database account and narrowly scoped table/view. The PostgreSQL adapter uses parameterized queries and read-only transactions, but your deployment remains responsible for credentials, network access, and database permissions.

Connector configuration

Configuration rejects some special-category field/attribute names and unsafe PostgreSQL identifiers. These guards are not a full classification of your data; curate the mapping and view yourself.

REST-backed audiences

restAdapter accepts fetchCandidates(query, { signal }), a required declaredSchema, optional fetchCount, and supported capability flags. Your callback receives mapped selections, AND filters, suppression IDs, page size, cursor, sampling, and a stable pull seed. Return canonical rows and an optional nextCursor.

The adapter validates returned rows and strips unmapped output. Your implementation must still enforce the requested filters, suppression, stable pagination, and any advertised random sampling. Implement exact fetchCount for paginated or large data sources; the fallback fails when it cannot derive an uncapped complete count.

Published entry points

The signing helpers and schemas are in @askdepth/audience-contract. After setup, review endpoints and mapping, signing, and run conformance before connecting production audience data.