Settings Configuration

This file defines all configurable settings required to integrate the Teads AI Chatbot SDK in different environments (Development, Staging, and Production).

1. Overview

The SDK requires a set of environment-specific keys, widget identifiers, and configuration parameters to connect securely with Teads and Partner APIs.
Settings should be stored in environment variables or secure configuration files — never hardcoded in public codebases.

2. Environment Structure

Environment	Purpose	Notes
Development	Local QA testing	Uses `testMode=true` and sandbox keys
Staging	Pre-production validation	Uses real endpoints with limited traffic
Production	Live traffic and reporting	Requires verified keys and approved placements

3. Core Settings

Setting	Description	Example
`TEADS_BASE_URL`	Base URL for Teads endpoints	`https://mv.outbrain.com`
`TEADS_BASE_PATH`	Common API path	`/Multivac/api/platforms`
`TEADS_FORMAT`	Response format	`vjnc`
`TEADS_CORS`	CORS flag for browser calls	`true`
`TEADS_IDX`	Default slot index	`0`
`TEADS_TEST_MODE`	Development flag	`true`
`TEADS_TIMEOUT_MS`	Request timeout in milliseconds	`3000`

Measurement Flow

Setting	Description	Example
`TEADS_MEASUREMENT_API_KEY`	API key for event signaling	`abcd1234-measurement`
`TEADS_MEASUREMENT_WIDGET_ID`	Widget ID for measurement flow	`widget-measure-01`

Publisher (Organic) Flow

Setting	Description	Example
`TEADS_CONTENT_API_KEY`	API key for content retrieval	`abcd1234-content`
`TEADS_ORGANIC_WIDGET_ID`	Widget ID for organic placements	`widget-organic-01`

Marketer (Paid) Flow

Setting	Description	Example
`TEADS_PAID_WIDGET_ID`	Widget ID for paid placements	`widget-paid-01`
`TEADS_INSTALLATION_KEY`	Used for Outbrain JS widget rendering	`inst-key-123`

5. Environment Variable Example

`.env` (Local Development)

# Teads SDK Configuration
TEADS_BASE_URL=https://mv.outbrain.com
TEADS_BASE_PATH=/Multivac/api/platforms
TEADS_FORMAT=vjnc
TEADS_CORS=true
TEADS_IDX=0
TEADS_TEST_MODE=true
TEADS_TIMEOUT_MS=3000

# API Keys & Widget IDs
TEADS_MEASUREMENT_API_KEY=abcd1234-measurement
TEADS_MEASUREMENT_WIDGET_ID=widget-measure-01
TEADS_CONTENT_API_KEY=abcd1234-content
TEADS_ORGANIC_WIDGET_ID=widget-organic-01
TEADS_PAID_WIDGET_ID=widget-paid-01
TEADS_INSTALLATION_KEY=inst-key-123

`.env.production`

# Production (real traffic)
TEADS_BASE_URL=https://mv.outbrain.com
TEADS_BASE_PATH=/Multivac/api/platforms
TEADS_FORMAT=vjnc
TEADS_CORS=true
TEADS_IDX=0
TEADS_TEST_MODE=false
TEADS_TIMEOUT_MS=3000

# Securely provisioned keys
TEADS_MEASUREMENT_API_KEY=${PROD_MEASUREMENT_KEY}
TEADS_MEASUREMENT_WIDGET_ID=${PROD_MEASUREMENT_WIDGET_ID}
TEADS_CONTENT_API_KEY=${PROD_CONTENT_KEY}
TEADS_ORGANIC_WIDGET_ID=${PROD_ORGANIC_WIDGET_ID}
TEADS_PAID_WIDGET_ID=${PROD_PAID_WIDGET_ID}
TEADS_INSTALLATION_KEY=${PROD_INSTALLATION_KEY}

⚠️ Security Note: Never commit .env files to version control. Use CI/CD secrets or environment managers (e.g., AWS Secrets Manager, Google Secret Manager, Vercel Environment Variables).

6. JavaScript Configuration Example

export const teadsConfig = {
  baseUrl: process.env.TEADS_BASE_URL,
  basePath: process.env.TEADS_BASE_PATH,
  format: process.env.TEADS_FORMAT || "vjnc",
  cors: process.env.TEADS_CORS === "true",
  idx: Number(process.env.TEADS_IDX || 0),
  testMode: process.env.TEADS_TEST_MODE === "true",
  timeout: Number(process.env.TEADS_TIMEOUT_MS || 3000),
  keys: {
    measurement: process.env.TEADS_MEASUREMENT_API_KEY,
    content: process.env.TEADS_CONTENT_API_KEY
  },
  widgets: {
    measurement: process.env.TEADS_MEASUREMENT_WIDGET_ID,
    organic: process.env.TEADS_ORGANIC_WIDGET_ID,
    paid: process.env.TEADS_PAID_WIDGET_ID
  },
  installationKey: process.env.TEADS_INSTALLATION_KEY
};

7. Proxy Configuration (Optional but Recommended)

For secure integrations, proxy all Teads API requests through your server:

https://yourdomain.com/api/teads-proxy?flow=measurement&event=unit_load

Example Express.js Middleware

app.get("/api/teads-proxy", async (req, res) => {
  const { flow, ...params } = req.query;
  const url = new URL(`${process.env.TEADS_BASE_URL}${process.env.TEADS_BASE_PATH}`);
  Object.entries(params).forEach(([key, val]) => url.searchParams.append(key, val));

  try {
    const response = await fetch(url.toString(), { method: "GET" });
    const data = await response.json();
    res.json(data);
  } catch (err) {
    res.status(500).json({ error: "Proxy request failed", details: err.message });
  }
});

8. Recommended Defaults

Parameter	Default Value	Rationale
`format`	`vjnc`	Ensures structured JSON responses
`cors`	`true`	Required for browser/chatbot environments
`idx`	`0`	Single-slot standard
`testMode`	`true` in Dev, `false` in Prod	Prevents test traffic pollution
`timeout`	`3000` ms	Balances latency and reliability

9. Versioning

When deploying SDK updates, version configuration should align with release tags.

SDK Version	Compatible Config Schema	Notes
`v1.0.0`	`config-v1`	Initial release
`v1.1.0`	`config-v1`	Added timeout and testMode options
`v2.0.0`	`config-v2`	Upcoming with AI adaptive content control

10. Troubleshooting

Issue	Cause	Fix
API 403	Invalid or missing key	Check environment variables
Empty content	Wrong widget ID or flow type	Verify widget IDs and flow params
TestMode ignored	Env var not boolean	Ensure `TEADS_TEST_MODE=true`
Timeout	Network delay or large payload	Increase `TEADS_TIMEOUT_MS`

Settings Configuration

1. Overview​

2. Environment Structure​

3. Core Settings​

4. API Credentials and Widget IDs​

Measurement Flow​

Publisher (Organic) Flow​

Marketer (Paid) Flow​

5. Environment Variable Example​

.env (Local Development)​

.env.production​

6. JavaScript Configuration Example​

7. Proxy Configuration (Optional but Recommended)​

Example Express.js Middleware​

8. Recommended Defaults​

9. Versioning​

10. Troubleshooting​