Tracking events

Once initialized, the SDK exposes a single track() call.

packedge.track('feature_used', { feature: 'export', format: 'pdf' });

Naming events

PackEdge reserves these top-level event prefixes for system events and they are filtered out of the Feature Usage view:

• license.*
• update.*
• release.*
• product.*
• site.*

Pick any other name — feature_used, export_clicked, onboarding_started, error_occurred. Snake case keeps the URLs and aggregations consistent across your codebase, but the SDK doesn't enforce a convention.

Common patterns

Event	Suggested properties
feature_used	{ feature: 'export', format: 'pdf' }
plugin_activated	{ version: '1.2.0' }
plugin_deactivated	{ reason: 'switching', feedback: '…' }
settings_changed	{ setting: 'theme', value: 'dark' }
error_occurred	{ code: 'E001', message: '…' }

Attributing events to a customer

Pass licenseKey to init() once your product knows the license, then every subsequent track() carries it:

packedge.init('pk_…', { licenseKey: 'MYPLUGIN-XXXX-XXXX-XXXX-XXXX' });

If you didn't have the key at init time — for example, the user activates mid-session — update it without re-initializing:

packedge.setLicense('MYPLUGIN-XXXX-XXXX-XXXX-XXXX');

Events without a license still record (license_id is null), but the Top licenses panel and the per-feature Licenses using this feature list only count attributed events. Adoption rate (unique licenses ÷ active licenses) also depends on attribution.

Site / domain

By default the SDK uses window.location.hostname as the event's site. If you'd rather report a different identifier (e.g. multi-site WordPress network):

packedge.init('pk_…', { site: 'subdomain.example.com' });
// or later:
packedge.setSite('shop.example.com');

The site field powers the Top domains panel and the heatmap's domain filter.

Properties

Anything serializable. Strings, numbers, booleans, arrays, nested objects.

packedge.track('export', {
  format: 'csv',
  rows: 1234,
  filters: { status: 'active', plan: 'pro' },
  user: { team: 't_abc' },
});

There's no schema enforcement: the payload is stored as JSONB on the events row. Future drilldowns (planned) will let you filter and group by property values from the console — pick property names you'd want to slice by.

Privacy

• Events are anonymous unless you pass licenseKey.

• The SDK does not auto-collect cookies, user agents, screen size, or geolocation — only what you put in properties.

• Respect end-user consent before calling track() if you're subject to GDPR/CCPA. A common pattern:

  if (userHasConsentedToAnalytics()) {
    packedge.init('pk_…');
    packedge.track('feature_used', { … });
  }

REST fallback

If you can't ship a JS package — e.g. server-side rendering, edge workers, or PHP — the SDK is just sugar over POST /public/v1/event. See Track Event for the raw API.