# melograno/usage-tracker

Shared WordPress library for anonymous plugin usage telemetry across Melograno products (Amelia, wpDataTables, IvyForms).

## Plugin integration

After Composer autoload is loaded:

```php
$savedVersion = /* host plugin version stored before upgrade */;
$collector = new \Melograno\UsageTracker\Collectors\Plugin\AmeliaCollector();

\Melograno\UsageTracker\Core\UsageTracker::init($collector, __FILE__, $savedVersion, '1.2.3');
```

When the collector implements `ConsentNoticeCollectorInterface`, `init()` registers a deferred admin notice in `admin_footer`, enable/dismiss AJAX handlers, and calls `renderConsentAdminNotice()` on the collector when the notice should be shown. The notice is injected after the host admin UI has loaded (for SPA pages such as Amelia, it waits until the app root has mounted).

Each product collector defines `getPluginSlug()`, `getConsentOptionName()`, and (for opt-in flows) notice/migration settings via `ConsentNoticeCollectorInterface`.

Host plugin settings UI should read/write consent via `UsageTracker::getSettings()` / `UsageTracker::updateSettings()`. Enabling consent automatically dismisses the admin notice. When disabling consent from general settings, pass `armNoticeOnDisable` as `false` (default) so the notice is dismissed as a definitive opt-out. Pass `true` only for non-definitive flows such as the welcome wizard.

Pass `$savedVersion` and the current plugin version to `init()`; when they differ, consent upgrade migration runs automatically for `ConsentNoticeCollectorInterface` collectors.

New-install consent defaults are applied automatically on boot when the consent option has never been stored (`ConsentNoticeCollectorInterface` collectors only).

On Amelia admin pages that strip third-party notices, the usage notice still renders via `admin_footer` and does not need to be re-registered on `admin_notices`. For manual rendering (e.g. tests), use:

```php
\Melograno\UsageTracker\Core\UsageTracker::renderConsentAdminNotice();
```

### Build-time setup (once per plugin)

1. Add the dependency:

```json
"require": {
  "melograno/usage-tracker": "^1.0"
}
```

2. Optionally include in [Strauss](https://github.com/BrianHenryIE/strauss) `packages` if you need a prefixed copy (`AmeliaVendor\Melograno\UsageTracker\...`). Amelia loads the package **without** Strauss prefixing so `Melograno\UsageTracker` resolves via Composer autoload.

3. Run `composer install` (and Strauss if used) before packaging the plugin.

### Local path repository (development)

```json
"repositories": [
  {
    "type": "path",
    "url": "../plugin-usage-tracker"
  }
]
```

## What the library provides

- Weekly WP Cron send to `https://bi.melograno.io/v1/usage` (override with `MELOGRANO_BI_GATE_URL`)
- Per-plugin consent `wp_option` (name from collector; host UI writes it; library reads it for cron/send)
- `NoticeManager` for admin notice option state; auto-dismiss when consent is enabled
- `ConsentNoticeService` for upgrade migration and new-install consent defaults
- `ConsentNoticeCollectorInterface::renderConsentAdminNotice()` for host-branded admin notice UI
- Common collectors (WP environment, activation stats)
- Product collectors: `AmeliaCollector`, `WpDataTablesCollector`, `IvyFormsCollector`
- `sha256` site identifier (no raw site URL in payload)
- Deactivation (when `__FILE__` passed to `init`): clears scheduled cron only; consent option is kept
- Uninstall: `UsageTracker::deleteStoredOptions()` removes consent and notice options

## Development

```bash
composer install
composer test
```

## Payload schema

```json
{
  "schema_version": 1,
  "sent_at": "2026-05-19T12:00:00Z",
  "plugin": "ameliabooking",
  "site_id": "<sha256 of site_url>",
  "common": { "environment": {}, "activation": {} },
  "plugin_data": {}
}
```