# Integrations

The `integrations` field in `writedocs.json` turns on a third-party provider by name — you supply the ID your account gave you, writedocs renders that provider's own install snippet on every page.

```json
{
  "integrations": {
    "ga4": { "measurementId": "G-XXXXXXXXXX" }
  }
}
```

That's the whole setup for Google Analytics 4. No `scripts` field, no snippet to paste in yourself. Turn on any subset of the seven supported providers — including several analytics providers at once if you're migrating from one to another.

## `ga4`

```json
{
  "integrations": {
    "ga4": { "measurementId": "G-XXXXXXXXXX" }
  }
}
```

`measurementId` is the `G-XXXXXXXXXX` ID from your GA4 property's data stream settings.

## `googleTagManager`

```json
{
  "integrations": {
    "googleTagManager": { "containerId": "GTM-XXXXXXX" }
  }
}
```

`containerId` is the `GTM-XXXXXXX` ID from your Tag Manager container. If you're already using GTM to manage GA4 and other tags, use this instead of `ga4` — don't turn both on together, or GA4 will load twice.

## `plausible`

```json
{
  "integrations": {
    "plausible": { "domain": "docs.example.com" }
  }
}
```

`domain` is the site domain you registered in Plausible. If you're on a self-hosted Plausible instance, point `src` at your own instance's script URL:

```json
{
  "integrations": {
    "plausible": {
      "domain": "docs.example.com",
      "src": "https://plausible.example.com/js/script.js"
    }
  }
}
```

## `fathom`

```json
{
  "integrations": {
    "fathom": { "siteId": "ABCDEFGH" }
  }
}
```

`siteId` is the site ID from your Fathom dashboard.

## `posthog`

```json
{
  "integrations": {
    "posthog": { "apiKey": "phc_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" }
  }
}
```

`apiKey` is your project API key. If your PostHog project is on the EU cloud (or self-hosted), set `apiHost` too — it defaults to the US cloud host:

```json
{
  "integrations": {
    "posthog": {
      "apiKey": "phc_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "apiHost": "https://eu.i.posthog.com"
    }
  }
}
```

## `umami`

```json
{
  "integrations": {
    "umami": { "websiteId": "11111111-2222-3333-4444-555555555555" }
  }
}
```

`websiteId` is the UUID Umami assigned your site. If you're self-hosting Umami, point `src` at your own instance's script:

```json
{
  "integrations": {
    "umami": {
      "websiteId": "11111111-2222-3333-4444-555555555555",
      "src": "https://umami.example.com/script.js"
    }
  }
}
```

## `askAi`

```json
{
  "integrations": {
    "askAi": { "id": "yourTeamId/yourBotId" }
  }
}
```

Turns on an "Ask AI" chat widget, backed by [DocsBot](https://docsbot.ai), so readers can ask questions and get answers sourced from your own docs content without leaving the page.

`id` is the combined `teamId/botId` string from your bot's own embed snippet in the DocsBot dashboard (Settings → Embeddable Widget) — it's one opaque value, not two separate fields. The field is named `askAi` rather than `docsbot` deliberately: it's the feature name as it appears on your site, independent of which provider sits behind it.

### Setting the id through an environment variable

You can also provide the id through the `WRITEDOCS_ASK_AI_ID` environment variable in the environment that runs the build (CI, your hosting platform's env settings, or your shell):

```bash
WRITEDOCS_ASK_AI_ID="yourTeamId/yourBotId" writedocs build
```

If `WRITEDOCS_ASK_AI_ID` is set, it takes precedence over `integrations.askAi.id` in `writedocs.json`. If it's unset or empty, the value from `writedocs.json` is used. Setting only the environment variable is enough to turn the widget on — you don't need an `askAi` entry in `writedocs.json` at all. This is useful when you want a different bot per deployment, or want to keep the id out of your checked-in content.

<Callout type="warning">
  The id isn't a secret either way: it's embedded in plain text in every built page's HTML, where any visitor can read it. The environment variable changes where the value is configured, not whether it's public.
</Callout>

The widget loads last on the page (after everything else, including your own `scripts.body` entries) — it's a floating chat bubble, not something else on the page depends on, so there's no reason to load it any earlier.

<Callout type="note">
  This is a third-party integration (DocsBot crawls/indexes your published site), not a self-hosted RAG pipeline over your MDX source — the self-hosted alternative remains a separate, not-yet-started line of work.
</Callout>

## What this doesn't cover

There's no per-page opt-out, no consent-banner gating, and no page-feedback (thumbs up/down) widget yet — the feedback widget in particular has no storage backend to save responses to, so it hasn't been built. If your site needs cookie-consent gating before analytics scripts load, or a provider not listed here, use the generic [`scripts`](/docs/configuration/site-config/) field instead and paste in that provider's own snippet (wrapped in whatever consent-check logic you need) directly.

<Callout type="tip">
  See `docs.json-examples/00-kitchen-sink/` in the Writedocs repo for a complete, buildable example with all seven providers turned on at once (using fake test IDs, just to show the shape).
</Callout>