PHP SDK

Deactivation survey

Off by default. Turned on, it asks the site owner why they are deactivating your plugin, in a popup on the Plugins screen, and sends the answer with the plugin_deactivated event:

Insights::init([
    // ...your existing options...
    'plugin_file'         => __FILE__,   // required for the popup: it finds your row by it
    'deactivation_survey' => true,
]);

true asks the built-in reasons, in this order:

Key Label
no_longer_needed I no longer need it
found_better I found a better plugin
broke_site It broke my site
missing_feature It is missing a feature I need
temporary It is only temporary
other Other

Or pass your own list, which replaces the built-in one. Translate the labels in your own text domain:

'deactivation_survey' => ['reasons' => [
    'missing_import' => __('I need an import feature', 'acme-gallery'),
    'too_slow'       => __('It was too slow', 'acme-gallery'),
    'other'          => __('Other', 'acme-gallery'),
]],

Each key must match ^[a-z0-9_]{1,40}$, each label must be a non-empty string, and the list holds 1 to 12 reasons. Anything else (a bad key, an empty label, no reasons, more than 12, a wrong type) turns the survey off and records why in errors(). It never throws. Without plugin_file the default popup is not shown, and errors() says so too.

When the popup shows. All four must hold:

  1. the survey is on;
  2. the site owner has consented (consent()->isGranted()) — an answer that could not be sent is never asked for;
  3. the screen is the single-site Plugins screen, not the network admin;
  4. the current user can deactivate plugins (activate_plugins).

Clicking your plugin’s Deactivate link then opens the popup instead: the reasons, an optional comment box (at most 300 UTF-16 code units, which is what its maxlength counts: a character outside the Basic Multilingual Plane, such as most emoji, takes 2, so the box holds as few as 150 of those; with the notice “Please don’t include personal information.”), and Submit & deactivate, Skip & deactivate and Cancel. Submit and Skip post to your site’s own admin-ajax.php, never to Plugie, and then deactivate — when that request finishes or fails, or after 3 seconds, whichever comes first — so the survey never stands between an owner and deactivating. Cancel deactivates nothing. The popup is inline markup, CSS and script printed into that screen’s footer: nothing is enqueued and nothing is loaded from anywhere else.

What is sent. Every plugin_deactivated event from this SDK carries feedback, whether the survey is on or not:

feedback.status When Also carries
answered The owner picked a reason reason (the key, not the label) and comment, if they wrote one
skipped The owner chose Skip & deactivate —
not_asked No answer is waiting for this user —

The comment is cleaned (sanitize_textarea_field), trimmed, cut to 300 UTF-16 code units (DeactivationSurvey::fitComment counts a character outside the Basic Multilingual Plane, such as most emoji, as 2, so a comment made only of those keeps at most 150), and dropped when empty. It travels in a POST body, never in a URL, so it never lands in the site’s access logs. The answer is held for this plugin and this user for 10 minutes, and leaves the site only inside the deactivation event that follows. No other event carries it.

not_asked is also what a deactivation records when nobody could be asked: a bulk deactivation, WP-CLI, a network deactivation, a browser with JavaScript off, or more than 10 minutes between answering and deactivating.

Your own popup. If your plugin already asks why it is being deactivated, keep your UI and set 'deactivation_survey_ui' => false, or your users see two popups. Then answer through the facade from your own AJAX handler, before you deactivate:

$survey = $insights->deactivationSurvey();

$survey->isEnabled();   // the survey is on AND consent is granted: only then is anything stored
$survey->reasons();     // ['found_better' => 'I found a better plugin', ...]

// In your handler, after your own nonce and capability checks:
$survey->answer($reason, $comment);   // false if nothing was stored: a key not in reasons(), not enabled, no logged-in user
$survey->skip();

// ...then deactivate. The deactivation event takes the answer.

answer() and skip() store the same answer the default popup does, for the current user, and return whether they stored it. On a facade whose init() failed, reasons() is [] and isEnabled(), answer() and skip() answer false. The custom API does not need plugin_file, but the SDK sends plugin_deactivated by itself only when plugin_file is set.

The default popup’s comment box carries the notice “Please don’t include personal information.” (Popup.php). answer() cannot show that notice for you — it only stores what your own UI collects — so if your comment box lets a site owner write free text, show the same notice next to it. Nothing here enforces that; it is asked of you the way the built-in reasons’ translations are.

The popup’s own wording is English in this release: “Quick feedback”, its prompt, the notice and the three button labels. The reasons are yours, in your text domain.