Embed SDK & npx terradium init

The Terradium Embed SDK is a tiny script you add to your own website. It attributes which visitors arrived from an AI answer (ChatGPT, Perplexity, Gemini, Google AI Overviews), can ask visitors a one-tap source survey, and can render content blocks you manage from the dashboard — all privacy-first, with no PII collected by default.

Install with npx

From your project's root, run:

bashCopy
npx terradium init

The installer:

• adds the Terradium client package to your dependencies,
• writes your project key into your environment configuration, and
• drops a ready-to-use <Terradium /> component (or script snippet) into your app so you can paste it into your layout.

Add the component

Place the component once, high in your layout so it loads on every page:

tsxCopy
import { Terradium } from "@terradium/embed";

export default function RootLayout({ children }) {
  return (
    <>
      {children}
      <Terradium projectKey="prj_live_…" />
    </>
  );
}

Your project key is safe to ship to the browser — it only authorizes sending events and reading public embed config for that project. Find it (and rotate it) under Project settings → Embed in the dashboard.

Configure from the dashboard

The embed is remote-configured: it fetches its settings from Terradium at runtime, so you can turn features on or off without redeploying your site. Under Project settings → Embed you control:

• Passive attribution — silently classify each visitor's traffic source, including AI referrals, and record it as an attribution event. This is the core feature and needs no visitor interaction.
• Visitor survey — optionally show a small, dismissible prompt (e.g. "How did you find us?") and capture the visitor's answer. You define the questions and answer options in the dashboard.
• In-page content blocks — optionally render content slots managed in Terradium at positions you mark on your site, so you can update copy without a deploy.

The embed reads these toggles from its config endpoint (see the API reference) and behaves accordingly.

Privacy & consent

The embed is designed to be safe to deploy:

• No PII by default. It collects traffic-source signals — referrer and AI-referral classification, UTM/gclid parameters, entry path, and optional survey answers. It does not set advertising cookies, fingerprint visitors, or collect names, emails, or precise location.
• IP anonymized server-side. The ingestion endpoint anonymizes source IPs and never stores raw addresses.
• Consent mode. Configure whether the embed requires consent before sending events. When consent is required and not granted, it stays in a no-op mode.

As the operator of your site, you are the data controller for what the embed collects and Terradium is your processor. Post an accurate privacy notice and obtain any consent your visitors are entitled to. See the Privacy Policy and the Data Processing Addendum for the full data-handling details, retention, and deletion path.