# Hooks and Filters (Developer API)

SmartCrawl exposes **99 documented hooks** for developers, using the `wds_` prefix. These allow programmatic control over SmartCrawl's output without modifying the plugin directly.

The complete hooks documentation is maintained in the [WPMU DEV hooks-documentation repository](https://github.com/wpmudev/hooks-documentation) in the `smartcrawl-seo-hooks-doc.html` file.

## Key Filters

### Title and Meta

```php
// Filter the SEO title output
add_filter( 'wds_title', function( $title ) {
    // Modify the title tag output
    return $title;
});

// Filter the meta description output
add_filter( 'wds_metadesc', function( $description ) {
    // Modify the meta description
    return $description;
});
```

### Open Graph

```php
// Customize Open Graph title
add_filter( 'wds_custom_og_title', function( $title ) {
    return $title;
});

// Customize Open Graph description
add_filter( 'wds_custom_og_description', function( $description ) {
    return $description;
});

// Customize Open Graph image(s)
add_filter( 'wds_custom_og_image', function( $images ) {
    // $images is an array of image URLs
    return $images;
});
```

### Defaults and Options

```php
// Filter SmartCrawl default options
add_filter( 'wds_defaults', function( $defaults ) {
    // Modify default option values
    return $defaults;
});
```

### Admin UI

```php
// Control admin bar visibility
add_filter( 'wds-admin-ui-show_bar', function( $show ) {
    // Return false to hide the SmartCrawl admin bar item
    return $show;
});
```

### Sitemap

```php
// Exclude specific taxonomy terms from sitemaps
add_filter( 'wds_terms_sitemap_include_term_ids', function( $term_ids, $taxonomy ) {
    // Remove specific term IDs
    $exclude = array( 15, 23, 42 );
    return array_diff( $term_ids, $exclude );
}, 10, 2 );

// Add extra images to sitemap entries
add_filter( 'wds_sitemap_extra_images', function( $images, $post_id ) {
    // Add additional image URLs for a post
    return $images;
}, 10, 2 );
```

## Key Actions

```php
// Fires after SmartCrawl saves post meta data
// Useful for syncing SEO data with external systems
add_action( 'wds_saved_postdata', function( $post_id ) {
    // Handle post meta save cleanup
    // SmartCrawl uses this internally to handle unchecked checkbox cleanup
});
```

## Common Use Cases

### Force a Specific Title on a Page

```php
add_filter( 'wds_title', function( $title ) {
    if ( is_page( 'special-landing-page' ) ) {
        return 'Custom Landing Page Title | Brand Name';
    }
    return $title;
});
```

### Add Custom OG Image for a Post Type

```php
add_filter( 'wds_custom_og_image', function( $images ) {
    if ( is_singular( 'product' ) ) {
        $custom_image = get_field( 'social_share_image' ); // ACF field
        if ( $custom_image ) {
            return array( $custom_image );
        }
    }
    return $images;
});
```

### Hide SmartCrawl Admin Bar for Non-Admins

```php
add_filter( 'wds-admin-ui-show_bar', function( $show ) {
    if ( ! current_user_can( 'manage_options' ) ) {
        return false;
    }
    return $show;
});
```

### Exclude a Specific Category from Sitemap

```php
add_filter( 'wds_terms_sitemap_include_term_ids', function( $term_ids, $taxonomy ) {
    if ( $taxonomy === 'category' ) {
        $exclude = array( get_cat_ID( 'Uncategorized' ) );
        return array_diff( $term_ids, $exclude );
    }
    return $term_ids;
}, 10, 2 );
```

## Hook Naming Convention

All SmartCrawl hooks follow these patterns:

- **Filters:** `wds_{feature}` — e.g., `wds_title`, `wds_metadesc`
- **Actions:** `wds_{event}` — e.g., `wds_saved_postdata`
- **UI filters:** `wds-{area}-{feature}` — e.g., `wds-admin-ui-show_bar`

## Notes

- The `wds_` prefix stands for "WPMU DEV SmartCrawl" (originally "WPMU DEV SEO")
- 96 of the 99 hooks were undocumented as of the last GitHub update — the three listed above are the most commonly used
- For the full list, inspect the plugin source code or check the hooks documentation repository
- Hook availability may vary between SmartCrawl Free and Pro versions