## Integrations System

Alpha Insights uses a modular integrations system so that third-party services (e.g. Facebook Ads, Google Ads, ShipStation, Webhooks) can be presented in a single settings UI and each integration can provide its own settings form and save logic. You can add custom integrations that appear alongside the built-in ones.

### Overview

The system has two layers:

- Integration metadata – Label, description, logo, category, and optional URL. Used to show a card in the integrations grid. Registered via `wpd_ai_register_integration_metadata` so that even integrations without a loaded class (e.g. Pro integrations on the free version) can be listed.
- Integration instances – A class extending `WPDAI_Integration_Base` that provides settings UI and save handling. Registered via `wpd_ai_register_integrations`. When an instance is present, the user can open that integration and see `render_settings()` output; when they save the main settings form, `save_settings()` is called.

The Integrations Manager (`WPDAI_Integrations_Manager`) is a singleton that:

- Fires `wpd_ai_register_integration_metadata` (init priority 4) so plugins/themes can register metadata
- Fires `wpd_ai_register_integrations` (init priority 5) so integration classes can register themselves
- Auto-loads built-in integrations from `includes/integrations/register/` (free) and `includes/integrations/register/pro/` (Pro), then merges metadata with instances for display
- Renders the integrations settings page: a grid of cards (from metadata) and, when one is selected (`?integrations=slug`), the integration's settings form (from the instance)

### User Interface

The integrations page is under Alpha Insights → Settings → Integrations. The URL is the settings page with optional `integrations` query parameter:

- No parameter – Grid of all integrations (cards with label, description, logo, category, Pro/Enabled/Disabled badges). Cards link to `?integrations=slug` or to a custom `url` if set in metadata.
- ?integrations=slug – Shows that integration's settings. If an instance exists, `render_settings()` is output inside the main settings form; if the slug has metadata but no instance (e.g. Pro on free), an upsell message is shown.

Categories are derived from metadata (`category`). The UI includes search and category tabs; each card's `data-category` and `data-search` drive filtering.

### Built-in Integrations

The plugin registers metadata (and, when the code is loaded, instances) for:

- Facebook Ads (Pro) – Marketing; links to dedicated Facebook settings subpage via `url`
- Google Ads (Pro) – Marketing; links to dedicated Google Ads settings subpage
- Webhooks (free) – Data Management; settings in integrations panel
- ShipStation (Pro) – Shipping; settings in integrations panel
- StarShipIt (Pro) – Shipping; settings in integrations panel

Pro integrations in the free version appear as cards with a Pro badge and show an upsell when clicked; no class is loaded so there is no instance.

### File Locations

- Manager: `includes/integrations/WPDAI_Integrations_Manager.php`
- Base class: `includes/integrations/WPDAI_Integration_Base.php`
- Built-in registration: `includes/integrations/register/*.php` (free), `includes/integrations/register/pro/*.php` (Pro)
- Settings page: Rendered by `WPDAI_Integrations_Manager::output_integrations_page()`; the menu entry is wired in admin (e.g. subpage `integrations` under settings).

### Related Documentation

- Creating a Custom Integration – Step-by-step guide to building and registering an integration
- Integration Base Class Reference – `WPDAI_Integration_Base` methods and contract
- Hooks and Registration – `wpd_ai_register_integration_metadata`, `wpd_ai_register_integrations`, and `wpd_ai_save_settings`