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. |