Inject a step into the setup wizard from an add-on

Premium Intermediate

Add-ons inject additional steps into the Setup Wizard by hooking into the steps array before the wizard runs. The wizard re-evaluates which steps are active whenever its state changes, so steps can be conditional — shown only when a specific feature is enabled.

Timing: this hook is most useful for add-ons installed before or alongside the initial setup. If an add-on is installed after the wizard has already been completed, the injected step will not surface on its own — the wizard does not re-run itself.

Resetting the wizard while you build the step. Rather than rebuilding a site to see your step again, reset the wizard to its first-run state: a Reset Wizard panel appears in Benecaster → Settings → Tools, and the same thing is available over REST as POST /benecaster/v1/wizard/reset. Both clear the completion and dismissal flags, the recorded show, and every per-step marker, then fire benecaster_setup_wizard_reset.

The reset is a development affordance, not a customer-facing one. It is offered only on local, development and staging environments, or wherever WP_DEBUG is on, and returns 403 anywhere else — so do not design a step that depends on the podcaster being able to run the wizard a second time.

When to Use This

Use this recipe when:

Your add-on needs the podcaster to complete a configuration step before they can use the plugin effectively
You want to surface the configuration in the familiar wizard flow rather than asking the podcaster to find it separately after setup
Your step should only appear under a specific condition (e.g. only after a subscription plugin has been connected)

How It Works

The filter receives the ordered array of step definitions. Find your insertion point by searching the array for a Benecaster step ID, then splice your own definition in at that position — inserting after subscription, for example, places your step immediately following the bridge picker.

The React component you name in the definition must be registered on window.BenecasterExtensions before the wizard loads. This is typically done in an enqueued JavaScript file that runs on the wizard page.

Step Definition Keys

Key	Type	Description
`id`	string	Unique slug for this step. Used in completion tracking and wizard state.
`component`	string	React component name registered on `window.BenecasterExtensions`.
`required`	bool	When `true`, the Skip button is disabled for this step.
`condition`	string\|null	State flag that must be `true` for the step to appear. `null` = always shown.

Benecaster Step IDs

The full ordered list, for finding your insertion point:

language, show-name, artwork, description, category, details, subscribers, migration, ssp-import, subscription, tiers, import, limit-enforcement, permalink, done

done is the last entry, so appending to the array puts your step after the finish screen. Splice at a named index instead of pushing onto the end.

Note that subscribers and subscription are two different steps: subscribers is where the podcaster chooses how subscriptions work, subscription is the bridge picker.

Condition Flags

Six flags are available. A step declaring one appears only while that flag is true:

Flag	True when
`bridge_connected`	Any membership option is selected for the show, Built-in membership included.
`builtin_chosen`	Built-in membership is the selected option. Core’s Stripe-keys and first-tier steps use it.
`external_bridge_connected`	A membership plugin other than Built-in is selected. Core’s level-mapping step uses it.
`ssp_or_powerpress_detected`	Seriously Simple Podcasting or PowerPress was found on the site.
`license_active`	The show has an active license.
`license_limited`	The license is active but on a plan carrying a show limit.

bridge_connected is true whenever any option is selected, not only yours — check the selected bridge slug inside your component if your step should be specific to it. A step that maps or reads an external plugin’s membership levels should use external_bridge_connected instead, because Built-in membership has no external levels.

A step with an unrecognised condition string defaults to hidden — safe to deploy before the flag-setting logic exists.

Notes

required: false is the standard default. Mark a step required only when it blocks the add-on from functioning at all. The wizard’s design philosophy is that skipped steps surface as dashboard tips — podcasters can return to them after setup.

Components register at boot time. Enqueue your JavaScript on the wizard page (body_class contains benecaster-wizard) and use window.BenecasterExtensions.registerComponent('MyAddonWizardStep', MyComponent) before the wizard app mounts.

Combine with benecaster_setup_wizard_bridge_options to add a custom bridge card to the Subscription step. When the user selects your bridge, bridge_connected becomes true and this step appears. See Add a Custom Bridge Card to the Wizard Subscription Step.

Setup Wizard Walkthrough — customer-facing wizard documentation

Code

<?php
add_filter( 'benecaster_setup_wizard_steps', function ( array $steps ): array {
    // Insert after the 'subscription' step.
    $insert_after = array_search( 'subscription', array_column( $steps, 'id' ), true );
    if ( false !== $insert_after ) {
        array_splice( $steps, $insert_after + 1, 0, [[
            'id'        => 'my-addon-config',
            'component' => 'MyAddonWizardStep',
            'required'  => false,
            'condition' => 'bridge_connected',
        ]] );
    }
    return $steps;
} );

View on GitHub →

Hooks Used

benecaster_setup_wizard_steps

Need this built rather than just documented? See our services →