## Hooks and Registration

The integrations system uses two actions for registration and one filter for saving. All run in the WordPress admin context when the integrations page is available.

### wpd_ai_register_integration_metadata

Type: Action
Fired by: `WPDAI_Integrations_Manager::register_default_integration_metadata()` on `init` priority 4.
Arguments: `$manager` (WPDAI_Integrations_Manager) – The singleton manager instance.

Use this to register metadata only (label, description, logo, category, optional URL). Metadata is used to display integration cards even when no class is loaded (e.g. Pro integrations on the free version).

On the manager, call:

`$manager->register_integration_metadata( $slug, $args );`

$slug (string): Unique key (e.g. `'my-integration'`). Sanitized with `sanitize_key()`.

$args (array):

- `label` (string) – Display name for the card.
- `description` (string) – Short description.
- `is_pro` (bool) – Whether to show the Pro badge and upsell when no instance is loaded.
- `logo_url` (string, optional) – Full URL to logo image. Escaped with `esc_url_raw()`.
- `category` (string, optional) – Category for sidebar filter (e.g. "Marketing", "Shipping"). Sanitized with `sanitize_text_field()`.
- `url` (string, optional) – Override destination when the card is clicked. If empty, the link is `?integrations=<slug>` on the integrations base URL. Escaped with `esc_url_raw()`.

Returns: `true` on success, `false` if slug is empty or invalid.

Example:

    add_action( 'wpd_ai_register_integration_metadata', function( $manager ) {
        $manager->register_integration_metadata( 'my-service', array(
            'label'       => __( 'My Service', 'alpha-insights-pro' ),
            'description' => __( 'Connect to My Service for sync.', 'alpha-insights-pro' ),
            'is_pro'      => false,
            'logo_url'    => 'https://example.com/logo.png',
            'category'    => __( 'Custom', 'alpha-insights-pro' ),
        ) );
    }, 10, 1 );

### wpd_ai_register_integrations

Type: Action
Fired by: `WPDAI_Integrations_Manager::register_default_integrations()` on `init` priority 5.
Arguments: `$manager` (WPDAI_Integrations_Manager) – The singleton manager instance.

Use this to register an integration instance (a class extending `WPDAI_Integration_Base`). The manager will show that integration's settings when the user selects it. You can load your class file and instantiate it inside the callback.

On the manager, call:

`$manager->register_integration( $slug, $instance );`

$slug (string): Must match the slug used in metadata (if any) and the value returned by `$instance->get_slug()`. Sanitized with `sanitize_key()`.

$instance (WPDAI_Integration_Base): An instance of your integration class.

Returns: `true` on success, `false` if slug is empty or instance does not extend `WPDAI_Integration_Base`.

Example:

    add_action( 'wpd_ai_register_integrations', function( $manager ) {
        require_once MY_PLUGIN_PATH . 'includes/class-my-integration.php';
        $manager->register_integration( 'my-service', new My_Service_Integration() );
    }, 10, 1 );

The plugin itself uses this hook in `register_core_integrations()` to run `load_and_register_from_directory()` on `includes/integrations/register/` and `register/pro/`, which require PHP files and auto-register any class that extends `WPDAI_Integration_Base`.

### wpd_ai_save_settings

Type: Filter
Applied in: The main settings save handler (e.g. when the user clicks "Save Changes" on the settings page that includes the integrations form).
Arguments: `$saved` (array) – Associative array of "label" => success (bool).

Integrations do not need to add this filter manually: `WPDAI_Integration_Base::setup_hooks()` adds `save_settings` to this filter. Your integration's `save_settings( $saved )` receives `$saved`, should add an entry (e.g. `$saved['My Integration'] = update_option( ... );`), and return the modified array.

See the main filter doc wpd_ai_save_settings in the developers filters section for full details and examples from other parts of the plugin.

### Other Filters (Display)

The manager also applies these when building the list for the UI (you can use them to change what is shown):

- wpd_ai_integration_metadata – Filters the full metadata array (slug => args) before merging with instances.
- wpd_ai_registered_integrations – Filters the registered instances array (slug => WPDAI_Integration_Base).
- wpd_ai_all_integrations_for_display – Filters the merged list used for the grid (slug => array( 'metadata' => ..., 'instance' => ... )).

### Related Documentation

- Integrations Overview – How metadata and instances are used together
- Creating a Custom Integration – Where to hook registration
- Integration Base Class Reference – `save_settings` contract
- Filter: wpd_ai_save_settings – Full filter documentation