# The integrations model (/docs/concepts/integrations-model)



An integration is how third-party functionality (reviews, analytics, loyalty, checkout add-ons) plugs into an Appbrew app. Concretely, an integration is an **npm package** (partner-built ones publish under `@app-brew/*`; integrations Appbrew maintains for third-party services ship under `@gauntlet/*`) that can export:

* **Blocks** — React components for the UI the integration adds
* **A register function** — named `register{Name}Blocks`, it adds those blocks to the app's block registry so config can place them
* **An analytics tracker** — a class that receives every app event and forwards it to the third-party service
* **Behavior extensions** — action lifecycle hooks and module providers that change what the app does ([Extending app behavior](/docs/build/extending-app-behavior))

A package can ship any combination: a pure analytics integration exports only a tracker; a reviews integration exports blocks and their register function.

Blocks reach the registry through the [`app` extension host](/docs/build/extending-app-behavior) from `@gauntlet/brewery` (platform 0.27.0 and later):

```ts
import { app } from '@gauntlet/brewery'
import { AcmeReviews } from '@app-brew/acme-reviews'

app.components.register('block', 'acme-reviews', AcmeReviews)
```

Packages keep exporting a `register{Name}Blocks` function too: that is what the app scaffold generates and what hosts on 0.26 and earlier consume.

## The manifest [#the-manifest]

Every integration package declares a manifest in its `package.json` under the `appbrew` key. The manifest makes the integration configurable without anyone reading your code. It drives the merchant-facing settings form and tells the platform how the package behaves.

```json
{
  "name": "@app-brew/acme-reviews",
  "appbrew": {
    "settings": [
      { "key": "apiKey", "title": "API key", "type": "text", "required": true, "secret": true },
      { "key": "storeId", "title": "Store ID", "type": "text", "required": true }
    ],
    "configKey": "acme-reviews",
    "requiresNativeBuild": false,
    "dynamicForm": false
  }
}
```

<TypeTable
  type="{
  settings: {
    description:
      'Merchant-facing fields. Each has key, title, type (text | number | boolean | json | select | file | time), required (default true), secret (default false), and optional placeholder and select options.',
    type: 'array',
  },
  configKey: {
    description:
      'Where the entered values land in app config: integrations.<configKey>.',
    type: 'string',
  },
  requiresNativeBuild: {
    description:
      'True when the package pulls in native modules. Default false.',
    type: 'boolean',
    default: 'false',
  },
  dynamicForm: {
    description:
      'True when the settings form is generated dynamically instead of from the static settings list. Default false.',
    type: 'boolean',
    default: 'false',
  },
}"
/>

Mark credentials with `secret: true` so the platform handles them as secrets.

## How settings reach your code [#how-settings-reach-your-code]

When a merchant fills in the form, the values are written into the app's config under `integrations.<configKey>`. Your code reads them back with the settings hooks:

```tsx
import { useIntegrationSettings } from '@gauntlet/state'

interface AcmeReviewsSettings {
  apiKey: string
  storeId: string
}

const settings = useIntegrationSettings<AcmeReviewsSettings>('acme-reviews')

if (!settings?.apiKey) return null
```

The same values are available to trackers through the app config passed at initialization.

## `requiresNativeBuild` [#requiresnativebuild]

Most integrations are pure JavaScript: enabling one is a config change, live on the next app launch. But if your package pulls in a native module (a native SDK, for instance), the app binary itself must change, so enabling it requires a **store release** rather than just a config change. Set `requiresNativeBuild: true` so the platform knows the difference. Keep integrations JS-only where you can; merchants can then adopt them instantly.

## Go deeper [#go-deeper]

* [Build an integration](/docs/build/integrations) — the end-to-end workflow
* [Manifest schema reference](/docs/reference/manifest-schema) — every field, exactly