Skip to content

Add analytics POC infrastructure (activation-funnel custom events)#1187

Merged
udil-cloudinary merged 1 commit into
developfrom
feature/analytics-poc-infra
Jun 24, 2026
Merged

Add analytics POC infrastructure (activation-funnel custom events)#1187
udil-cloudinary merged 1 commit into
developfrom
feature/analytics-poc-infra

Conversation

@udil-cloudinary

Copy link
Copy Markdown

Phase 1 POC scaffolding for plugin analytics — see the POC definition and implementation plan.

This is PR #1 of 2 — the infrastructure only. It introduces the custom-events framework but wires no funnel event call-sites yet; that is PR #2.

Approach

The plugin already posts deactivation feedback to Cloudinary's analytics collector (analytics-api.cloudinary.com). This PR reuses that same collector under a new feature (wp_plugin_event), so no backend changes are required.

  • Analytics component (php/class-analytics.php) — the single egress. Builds the global parameter envelope (mandatory params on every event; cloud_name + plan once an account is connected), generates event_id/event_timestamp/session_id (sha256(wp_get_session_token())), and emits via non-blocking wp_remote_post (1s timeout, no retries). Wrapped in try/catch — a collector outage or any error never disrupts wp-admin.
  • Internal REST bridge (cloudinary/v1/events) — client-side events post here and are enriched with the server-side envelope, sidestepping the collector's GET-only CORS. Admin-gated + nonce.
  • JS module (src/js/components/analytics.js) — exposes a fail-silent track() helper on window.cloudinary. Self-inits; reads config from cldData.analytics. (Bundle rebuilt: js/cloudinary.js.)
  • Flag-gated smoke eventcloudinary_analytics_smoke_test (default off) emits a one-off poc_smoke_test event to validate the collector path end-to-end during the POC. Throttled to once / 5 min.

Why PHP-side egress: most mandatory params and all contextual params are server-known, and most funnel events (activation, save-wizard, first sync, first API call) fire in PHP. The JS bridge exists only for the wizard's client-only signals.

Dormant by default: nothing emits in production until either a funnel event is wired (PR #2) or the smoke flag is turned on.

QA notes

  1. With the plugin active, load any wp-admin page — confirm no JS console errors and no measurable page-load regression.
  2. Turn the smoke flag on: add_filter( 'cloudinary_analytics_smoke_test', '__return_true' );
  3. Load a wp-admin page; confirm a wp_plugin_event with event_name=poc_smoke_test reaches the collector with the mandatory params (and cloud_name/plan if connected).
  4. Block/break the collector (e.g. firewall the host) and confirm wp-admin stays fully usable — no fatals, no hang (non-blocking, 1s timeout, fail-silent).
  5. npm run lint:js and npm run lint:php pass.

Test matrix (full QA in PR #2 once events are wired): WP 5.6 / 6.9.x / 7.0, PHP 7.4 / 8.x, single + multisite, classic + block.

Phase 1 POC scaffolding for plugin analytics. Adds a fail-silent,
server-side custom-events emitter and a client-side bridge, reusing the
existing Cloudinary analytics collector (analytics-api.cloudinary.com) —
the same endpoint already used for deactivation feedback. No funnel event
call-sites are wired yet; that follows in a separate PR.

- New Analytics component: builds the global parameter envelope (mandatory
  params always, cloud_name/plan once connected), emits via non-blocking
  wp_remote_post, and never disrupts wp-admin on failure.
- Internal REST route (cloudinary/v1/events) so client-side events are
  enriched server-side, avoiding the collector's GET-only CORS.
- JS analytics module exposing a fail-silent track() helper.
- Flag-gated smoke-test event (cloudinary_analytics_smoke_test, off by
  default) to validate the collector path end-to-end during the POC.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@udil-cloudinary udil-cloudinary merged commit 613ec5b into develop Jun 24, 2026
8 checks passed
@udil-cloudinary udil-cloudinary deleted the feature/analytics-poc-infra branch June 24, 2026 15:03
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants