PHP SDK

Initialise

In your main plugin file, at load time (not inside a hook — the SDK registers admin_init, shutdown, activation, deactivation and uninstall hooks itself and needs to run before they fire):

use Plugie\Insights\Insights;

$insights = Insights::init([
    'plugin_id'       => 'acme-gallery',   // required — as registered in the dashboard
    'plugin_version'  => ACME_GALLERY_VERSION,
    'plugin_file'     => __FILE__,         // required for lifecycle events
    'consent_version' => '1',              // the version of your consent notice
    'site_url'        => home_url(),       // for moved-vs-cloned detection
]);

plugin_id must be the public id you registered on the dashboard’s Products screen: lowercase letters, digits and hyphens, at most 64 characters. Any other value makes init() do nothing — no hooks, no sends — and record why in errors().

plugin_file is separate from plugin_id because WordPress keys register_activation_hook, register_deactivation_hook and register_uninstall_hook on your main file, and a Composer package cannot derive it (__FILE__ inside the package names something in vendor/). Omit it and the SDK still measures and snapshots, but sends no activation, deactivation or uninstall events.

Call it once per plugin id per request. A second init() for the same id in one request is refused (the returned facade measures nothing) and the reason is recorded. Keep the returned object — a global, a static, a container — and hand that one around. Two different plugins each calling init() with their own id is the normal case and works.

Every option

Key Default Notes
plugin_id — Required. ^[a-z0-9-]+$, ≤ 64 chars.
plugin_version '0.0.0' Reported on every payload.
plugin_file '' Your main plugin file. Without it, no lifecycle events and no plugin list (see inventory).
consent_version '1' The version of the notice the owner accepted. Raise it when the notice changes; see Consent.
inventory off ['plugins' => true, 'theme' => true] shares the slugs of the other plugins on the site and of its parent theme. Each half is separate, and only a literal true turns it on. Raise consent_version in the same release; see Share plugin and theme inventory.
deactivation_survey off true asks the built-in reasons when a site owner deactivates your plugin; ['reasons' => ['key' => 'Label', …]] asks your own. Anything malformed turns it off and says why in errors(). See Deactivation survey.
deactivation_survey_ui true false hides the default popup, for a plugin that draws its own and answers through deactivationSurvey().
site_url '' Pass home_url(). It is hashed to detect a moved or cloned site; left empty, the hash never changes and conflict detection never fires.
interval 604800 (weekly) Seconds between snapshots, until the server says otherwise. Values below 1 are refused.
endpoint https://app.insights.plugie.io/v1 Point at your own instance in development.
timeout 5 Seconds, for blocking requests. Event sends are non-blocking regardless.
environment detected ['wordpress' => …, 'php' => …, 'environment_type' => …] to override $wp_version, PHP_VERSION and wp_get_environment_type().
store OptionStore An object implementing Plugie\Insights\Storage\Store, for tests or non-WordPress hosts.