# 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:

```bash
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:

```tsx
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](/docs/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](/privacy) and the [Data Processing Addendum](/dpa) for the full
data-handling details, retention, and deletion path.