@smalk/astro

Smalk AI Ads for Astro static sites on Cloudflare Pages.

Smalk serves native text ads inside AI-generated answers (ChatGPT, Perplexity, Claude, …). Since AI crawlers read the HTML your server returns — not JavaScript-rendered content — the ad has to be in that HTML. A static Astro site has no per-request server, so this package injects the ad at the Cloudflare edge instead. No rebuilds, no origin server, and it fails open: if anything is slow or unavailable, your page renders exactly as built.

Compat: Astro 4+, Cloudflare Pages.

Install

npm install @smalk/astro

1. Tracker

Add the integration to your Astro config — it drops the Smalk tracker on every page at build time:

// astro.config.mjs
import { defineConfig } from "astro/config";
import smalk from "@smalk/astro";

export default defineConfig({
  integrations: [smalk({ projectKey: process.env.SMALK_PROJECT_KEY })],
});

2. Ads

Put the ad placeholder where you want the ad to appear, in your layout or page:

<div class="smalk-ads"></div>

Add the Cloudflare Pages Function (create the file if it doesn't exist):

// functions/_middleware.js
export { onRequest } from "@smalk/astro/pages-function";

Set your environment variables in Cloudflare Pages → Settings → Environment variables — the secret key is set here, in the dashboard, not in your code:

| Var | Required | Notes | |---|---|---| | SMALK_PROJECT_KEY | yes | Your project key (public) | | SMALK_API_KEY | yes | Your API key (secret) | | SMALK_EDGE_TRACKING | no | Records AI-agent visits (analytics) server-side. On by default; set to false to disable. | | SMALK_API_BASE | no | Defaults to https://api.smalk.ai. | | SMALK_ADS_ALL_PAGES | no | Ask the ad server on every page instead of only the ones Smalk lists as sold. Off by default; turn it on only if your Smalk contact tells you the URL list cannot be trusted for your site. It costs one request per page view and does not make SMALK_API_KEY optional. |

Then redeploy. Cloudflare Pages Functions only take effect on the next deployment after functions/_middleware.js is added — an already-running site won't pick it up until you deploy again.

No ad appears

The slot only fills on pages Smalk currently sells, so an empty slot is the normal state on most of your site. To see why a page you expect to be sold is still empty, watch the edge log while you load it:

npx wrangler pages deployment tail --project-name <your-pages-project>

Every failure prints a line prefixed [smalk] — a rejected key, a timeout, a missing environment variable. No [smalk] line and no ad means the page is not in your active set yet, which is a question for your Smalk contact, not a bug here.

You can check the list yourself:

curl -H "Authorization: Api-Key $SMALK_API_KEY" \
  "https://api.smalk.ai/api/v1/projects/$SMALK_PROJECT_KEY/ads/inventory/active-ad-urls/?flat=true"

A 401 means SMALK_API_KEY is wrong; a 404 means SMALK_PROJECT_KEY is.

When SMALK_EDGE_TRACKING is on (the default), a failed ad fetch is also reported to Smalk on the next page view, so your contact can see the problem without you having to send them a log.

A [smalk] tracking visit HTTP 401 line means the key is wrong even if ads are serving: with SMALK_ADS_ALL_PAGES on, ad serving no longer reads the key, but your AI-agent analytics still does.

Support

smalk.ai · api.smalk.ai/api/docs