Custom Placements – Wbcom Designs Docs

WB Ad Manager includes 14+ built-in placement options (before/after content, sidebar, header, footer, popup, sticky, and more), but you can create your own custom placements to display ads in any location on your site. Custom placements integrate with the plugin’s targeting engine, rotation logic, and analytics tracking.

This guide shows you how to implement the Placement_Interface, hook into your theme or plugin, and register your placement with the engine.

Creating a Custom Placement

To create a custom placement, implement the Placement_Interface. The interface defines methods for identification, availability checks, hook registration, and ad display:

use WBAM\Modules\Placements\Placement_Interface;

class Custom_Placement implements Placement_Interface {

    /**
     * Get placement ID.
     */
    public function get_id() {
        return 'my_custom_placement';
    }

    /**
     * Get placement label.
     */
    public function get_label() {
        return __( 'My Custom Placement', 'my-plugin' );
    }

    /**
     * Get placement description.
     */
    public function get_description() {
        return __( 'Displays ads in a custom location.', 'my-plugin' );
    }

    /**
     * Get placement group for admin UI.
     */
    public function get_group() {
        return 'custom';
    }

    /**
     * Check if placement is available.
     */
    public function is_available() {
        return true; // Add conditions if needed
    }

    /**
     * Register the placement hooks.
     */
    public function register() {
        add_action( 'my_custom_hook', array( $this, 'display' ) );
    }

    /**
     * Display ads for this placement.
     */
    public function display() {
        $engine = \WBAM\Modules\Placements\Placement_Engine::get_instance();
        $ads = $engine->get_ads_for_placement( $this->get_id() );

        if ( empty( $ads ) ) {
            return;
        }

        // Pick random ad or implement rotation
        $ad_id = $ads[ array_rand( $ads ) ];

        echo $engine->render_ad( $ad_id, array( 'placement' => $this->get_id() ) );
    }
}

Interface Methods

Method	Return Type	Description
`get_id()`	`string`	Unique identifier for the placement (e.g., `'my_custom_placement'`).
`get_label()`	`string`	Human-readable label shown in the admin placement selector.
`get_description()`	`string`	Short description of where the placement displays ads.
`get_group()`	`string`	Group name for organizing placements in the admin UI (e.g., `'content'`, `'sidebar'`, `'custom'`).
`is_available()`	`bool`	Returns whether this placement is available in the current environment. Use this to check for required themes, plugins, or conditions.
`register()`	`void`	Registers the WordPress hooks that trigger ad display. Called during placement initialization.
`display()`	`void`	Fetches and renders the ads assigned to this placement.

Registering the Placement

Use the wbam_register_placements action to register your custom placement with the engine:

add_action( 'wbam_register_placements', function( $engine ) {
    $engine->register_placement( new Custom_Placement() );
} );

Once registered, your custom placement will appear in the placement selector when editing ads. Users can assign ads to your placement and configure targeting rules just like any built-in placement.

Tips

Conditional availability: Use is_available() to hide placements that depend on a specific theme or plugin. For example, return function_exists('buddypress') for a BuddyPress-only placement.
Placement groups: Use standard group names (content, sidebar, header, footer, popup, custom) to keep the admin UI organized.
Rotation: The get_ads_for_placement() method returns all qualifying ads. You can implement custom rotation logic (random, weighted, sequential) in your display() method.
Multiple hooks: You can register multiple WordPress hooks in register() if your placement needs to display ads in several locations.