Docs

SDK, REST, three formats.

Install the SDK, request ads, and report impressions and clicks. Text, card, and banner share one endpoint.

TypeScript SDK

Typed API, React hooks, drop-in ad component.

REST API

Request ads. Track impressions and clicks.

Formats

Text, card, banner. Same endpoint, one parameter.

How does a publisher request an ad?

POST /api/ads with a bot id and optional topic. Then POST /api/track/impression or /api/track/click. Use clickUrl for the button, not ctaUrl. Keys stay on the server.

import { PrismAds } from "@prismpublication/sdk";

const prism = new PrismAds({
  apiKey: process.env.PRISM_API_KEY,
  botId: "my-chatbot",
  adFormat: "card",
});

const ad = await prism.displayAd({ topic: "notes", userId: "u-123", frequencyWindow: 5 });
if (ad) await prism.trackImpression(ad.id, "u-123");

How does Google Ad Manager call this API?

A Google Ad Manager custom creative runs in a sandboxed iframe. It can send a Bearer SDK key. It cannot compute HMAC signatures. POST https://v1.prismpublication.com/api/ads accepts that Bearer key when REQUIRE_SDK_HMAC is not set to true. HMAC headers stay optional for SDK clients that can sign.

Create a Custom creative in GAM. Paste the snippet. Use your bot id and the key you were given. The response is { "success": true, "data": [ { "id", "title", "description", "ctaText", "clickUrl", "imageUrl" } ] } or an empty data array. Then POST /api/track/impression or /api/track/click with the same key.

fetch("https://v1.prismpublication.com/api/ads", {
  method: "POST",
  headers: {
    "content-type": "application/json",
    "authorization": "Bearer YOUR_SDK_KEY"
  },
  body: JSON.stringify({ botId: "YOUR_BOT_ID", format: "text" })
}).then(function (res) { return res.json(); })
  .then(function (body) {
    var ad = body.data && body.data[0];
    if (!ad) return;
    document.getElementById("title").textContent = ad.title;
    document.getElementById("desc").textContent = ad.description;
    var link = document.getElementById("cta");
    link.textContent = ad.ctaText;
    link.href = ad.clickUrl;
  });

Email [email protected] for a key. Do not put a production key in a public repo. The GAM creative already exposes the key to anyone who inspects the line item.