How to Redirect Your Plugin After Activation. The Right Way.

You Can Go Your Own Way
You Can Go Your Own Way

I’ve had a few plugins of mine professionally reviewed at this point. I wanted an unbiased no B.S. review, and a sticking point kept coming up.

Hover over settings and click on the Simple Comment Editing link. A quick word on this, I don’t believe Ronald wanted a complex setup process and has tried to make the plugin less intrusive compared to other plugins.

That said, some might think that SCE isn’t working; I’m talking brand new users, not people who’ve got experience with WordPress.

Ben of LayerWP

What Ben was referring to is that after the activation of a plugin, the plugin should “do” something. Show the user what’s next. Show the user what settings there are to configure.

Me being me, I settled for the less obtrusive route, which is just to link to my settings in the plugin row.

Settings Shortcut in the Plugin Row of a Plugin
Settings Shortcut in the Plugin Row of a Plugin

But this begs the question… after activation, now what? Is the user supposed to magically guess what this new plugin addition can do? Shall I do yet another admin notice?

The answer is likely no. The user will need to hunt for the settings, and that’ll just be another barrier to entry for the onboarding of my plugin.

Photograph with numerous road signs
Decisions, decisions.

How about redirecting your users after activation?

One thing you can code into your plugin is a redirect after plugin activation. WordPress itself uses this technique when you upgrade major releases, and you are redirected to a welcome screen.

WordPress Welcome Screen
WordPress Welcome Screen

Plugin authors can do the same. It could be a redirect to a welcome screen, admin options, or perhaps a wizard. You get the idea.

But…

There are vocal opponents to this technique. If implemented incorrectly, it will interrupt users, especially developers.

The tweet above mentions redirecting even when there are multiple activations. Fortunately, there’s a simple way around this.

The arguments for redirection

Arguments for redirecting users are:

It improves onboarding

Say, for example, a user installs a membership plugin. With redirection, the user can be sent to a wizard that helps them set up their membership site.

It can provide an introduction to the plugin

Jetpack Welcome Screen After Activation
Jetpack Welcome Screen After Activation

Redirecting to a welcome screen for some plugins to give users an idea of what they just installed is a nice touch.

From there, the user can be introduced to its features, especially if they aren’t apparent.

It aids in user experience

Most of us aren’t developers, so it’s usually activating plugins one at a time. A redirect saves the user from searching for your options after activation.

The arguments against redirection

It interrupts the user

Interrupting the User
Interrupting the User – License: Adobe Stock

If you’re a developer activating plugins, redirects will get in your way. But it’s easy to disable redirects for developers.

For non-developers, redirecting after activation can be a jarring experience. A confusing admin panel or salesy welcome page could detract from the user experience.

Loss of control

Redirecting after activation takes the decision-making out of the equation for the user in order for them to save a step. This can frustrate users and can impact your plugin negatively.

Security

Redirects are always a security hazard for WordPress sites. Malicious redirects are a possibility if the redirects are implemented poorly.

How to redirect users after activation

You’re now familiar with the pros and drawbacks of redirection. Let’s go ahead and show you how to add redirection to your plugin after activation.

First, let’s set up a sample plugin that will demonstrate redirection.

Setting up the plugin’s headers

Let’s call our fancy new plugin MembershipsPlus. We’ll be setting the headers for this plugin in this section.

<?php
/**
 * Plugin Name:       MembershipsPlus
 * Plugin URI:        https://dlxplugins.com/plugins/
 * Description:       A Pro membership plugin.
 * Version:           1.0.0
 * Requires at least: 5.8
 * Requires PHP:      7.2
 * Author:            DLX Plugins
 * Author URI:        https://dlxplugins.com
 * License:           GPL v2 or later
 * License URI:       https://www.gnu.org/licenses/gpl-2.0.html
 *
 * @package MembershipsPlus
 */
Code language: PHP (php)

At this point, we have something we can activate, but let’s go ahead and create a very simple admin panel for the plugin.

Adding the admin panel

We’ll just add a barebones admin panel that’ll demonstrate the redirect when it occurs.

/**
 * Callback for adding an admin menu.
 */
function memberships_plus_add_admin_menu() {
	add_options_page(
		'Memberships Plus',
		'Memberships Plus',
		'manage_options',
		'memberships-plus',
		'memberships_plus_options_page'
	);
}
add_action( 'admin_menu', 'memberships_plus_add_admin_menu' );

/**
 * Callback for the admin panel options.
 */
function memberships_plus_options_page() {
	?>
	<div class="wrap">
		<h1>Memberships Plus</h1>
		<p>Welcome to Memberships Plus.</p>
	</div>
	<?php
}Code language: PHP (php)

Using the action admin_menu, I use a callback function and use add_options_page to add the admin menu item. The slug I use is memberships-plus, so our admin URL will be: https://domain.local/wp-admin/options-general.php?page=memberships-plus

The admin panel itself is output in the memberships_plus_options_page callback function.

Memberships Plus Admin Panel
Memberships Plus Admin Panel

Adding the plugin activation hook

Assuming we’re in the base plugin file, we’ll need a reference to the file that will be used for activation. In this case, we’ll just use the __FILE__ global, which will provide a reference to the plugin file.

register_activation_hook( __FILE__, 'memberships_plus_plugin_activate' );Code language: PHP (php)

Now when a user activates the plugin, a callback function memberships_plus_plugin_activate will be called.

We’ll be using this callback to set an option that we can read in later for the redirect.

/**
 * Add an option upon activation to read in later when redirecting.
 */
function memberships_plus_plugin_activate() {
	add_option( 'memberships_plus_plugin_do_activation_redirect', sanitize_text_field( __FILE__ ) );
}Code language: PHP (php)

One issue with the above approach is that it’ll set a redirect option every single time the plugin is activated. This isn’t necessarily a problem, but we want to avoid setting this option if the user is a developer.

Let’s create a new function that will determine if we can skip the redirection.

Add a developer exclude function

We’ll want to exclude developers, if possible, from the redirect. Let’s test for WP_DEBUG, multisite activation, and also if the user is bulk-activating plugins.

/**
 * Determine if a user can be redirected or not.
 *
 * @return true if the user can be redirected. false if not.
 */
function memberships_plus_can_redirect_on_activation() {
	// If plugin is activated in network admin options, skip redirect.
	if ( is_network_admin() ) {
		return false;
	}

	// Skip redirect if WP_DEBUG is enabled.
	if ( defined( 'WP_DEBUG' ) && WP_DEBUG ) {
		return false;
	}

	// Determine if multi-activation is enabled.
	$maybe_multi = filter_input( INPUT_GET, 'activate-multi', FILTER_VALIDATE_BOOLEAN );
	if ( $maybe_multi ) {
		return false;
	}

	// All is well. Can redirect.
	return true;
}Code language: PHP (php)

In the above snippet, we test for a multisite activation using is_network_admin. If it’s a multisite activation, we return false since we don’t want to redirect a Network Admin user.

We also test for the WP_DEBUG constant. If this is set, the redirect is skipped. Likewise, if the $_GET attribute activate-multi is set, which means there are multiple plugins that are being activated.

We’ll modify the activation function to reflect this new conditional.

/**
 * Add an option upon activation to read in later when redirecting.
 */
function memberships_plus_plugin_activate() {
	if ( memberships_plus_can_redirect_on_activation() ) {
		add_option( 'memberships_plus_plugin_do_activation_redirect', sanitize_text_field( __FILE__ ) );
	}
}Code language: PHP (php)

Add the redirection

We’ll hook into admin_init to perform the redirect. This callback will read in the option and, if set, will perform the redirect.

add_action( 'admin_init', 'memberships_plus_plugin_activate_redirect' );
/**
 * Redirect a user to the admin panel after activation.
 */
function memberships_plus_plugin_activate_redirect() {
	if ( memberships_plus_can_redirect_on_activation() && is_admin() ) {
		// Read in option value.
		if ( __FILE__ === get_option( 'memberships_plus_plugin_do_activation_redirect' ) ) {

			// Delete option value so no more redirects.
			delete_option( 'memberships_plus_plugin_do_activation_redirect' );

			// Get redirect URL.
			$redirect_url = admin_url( 'options-general.php?page=memberships-plus' );
			wp_safe_redirect(
				esc_url( $redirect_url )
			);
			exit;
		}
	}
}
Code language: PHP (php)

We’ll again make sure the user can be redirected, check if the option is set, delete the option, and finally, redirect. That’s it for redirection.

Redirection Conclusion

There are pros and cons of redirecting after activation. I urge you to evaluate the risks and determine if redirecting after activation makes sense for your plugin.

The solution I presented attempts to avoid interruptions for developers activating plugins and provides a secure way to redirect.

Please comment below if you have any questions and I’ll be happy to respond.

Like this tutorial? There's more like it. Subscribe today!

Name(Required)

Ronald Huereca
By: Ronald Huereca
Published On: on February 12, 2023

Ronald Huereca founded DLX Plugins in 2022 with the goal of providing deluxe plugins available for download. Find out more about DLX Plugins, check out some tutorials, and check out our plugins.

Leave Your Valuable Feedback

Your email address will not be published. Required fields are marked *

Shopping Cart
  • Your cart is empty.
Scroll to Top