Analytics event catalog

Events dispatch oilmanual:analytics locally. On oilmanual.com, after analytics consent is granted, the shared helper sends one Google tag event command and a sanitized dataLayer observation. An optional configured endpoint receives the same safe payload. Local and preview hosts never send these events to production analytics.

Debug overlay: turn on analytics debug or turn it off.

Payload schema

Field	Type	Meaning
`name`	string	A name from the event catalog; unknown names are discarded.
`detail`	object	Allowlisted categories, booleans, bounded counts and internal paths only.
`path`	string	Current site pathname, such as `/search`.
`ts`	string	Client-side ISO timestamp.

Raw search terms, manual/bottle excerpts, vehicle selections, correction form values, source URLs, notes, and cost amounts are excluded from these custom payloads. Search records a length band and result count. Google’s automatic measurement is configured separately in GA4.

Events

Event	Trigger	Fields
`tool_opened`	A tracked interactive tool enters the viewport.	tool
`tool_started`	A user first changes or submits a tracked interactive tool.	tool
`search_query`	A user enters a Pagefind query.	query_length
`search_results`	Pagefind returns results.	query_length, count
`search_no_results`	Pagefind returns zero results.	query_length, count
`search_shortcut`	A popular-search or empty-state shortcut is selected.	query_length, source
`search_result_click`	A user opens a Pagefind result.	target
`source_clicked`	A user opens a primary editorial source.	source
`language_changed`	A language option link is activated.	from, to, target
`consent_accepted`	The visitor grants analytics consent.	none
`consent_declined`	The visitor declines analytics consent.	none
`label_decoder_opened`	The static oil-label decoder enters the viewport.	tool
`low_confidence_vehicle_warning_viewed`	A provisional vehicle warning enters the viewport.	confidence, source_tier
`correction_submit_attempt`	Correction form submit is attempted.	none
`correction_submit_success`	The hosted correction endpoint accepts a correction.	none
`correction_submit_fallback`	The correction endpoint is unavailable and email fallback is shown.	none
`correction_submit_validation`	Correction evidence is incomplete or the endpoint returns field errors.	none
`correction_mailto_opened`	The prepared correction email fallback is opened.	none
`manual_evidence_generated`	Manual evidence builder creates an evidence packet.	has_source, has_spec, has_capacity
`manual_evidence_copy`	A manual evidence packet is copied.	none
`manual_evidence_copy_failed`	Copying a manual evidence packet fails.	none
`manual_evidence_print`	A manual evidence packet is printed.	none
`car_lookup_resolved`	YMME lookup resolves to a car record.	none
`car_lookup_unresolved`	YMME lookup has no matching car record.	none
`car_lookup_opened`	The resolved car record is opened.	none
`spec_checker_result`	Oil spec checker returns a compatibility result.	status, has_manual_excerpt, has_bottle_excerpt
`spec_checker_copy`	An oil spec result is copied.	none
`spec_checker_copy_failed`	Copying an oil spec result fails.	none
`spec_checker_print`	An oil spec result is printed.	none
`triage_result`	Wrong-oil triage returns a branch.	status
`triage_copy`	A wrong-oil triage result is copied.	none
`triage_copy_failed`	Copying a wrong-oil triage result fails.	none
`triage_print`	A wrong-oil triage result is printed.	none
`saved_garage_add`	A local garage record is saved.	has_date
`saved_garage_opened`	Saved Garage opens with existing records.	saved_count, due_count
`saved_garage_due_viewed`	A saved interval due state is shown.	due_count
`saved_garage_delete`	A local garage record is deleted.	none
`saved_garage_copy`	A saved garage card is copied.	none
`saved_garage_copy_failed`	Copying a garage card fails.	none
`saved_garage_print`	A saved garage card is printed.	none
`kit_checklist_copy`	An oil-change kit checklist is copied.	none
`kit_checklist_print`	An oil-change kit checklist is printed.	none
`cost_estimator_result`	The cost estimator calculates DIY and shop totals.	none
`cost_estimator_print`	A cost estimate is printed.	none
`cost_estimator_copy`	A cost estimate is copied.	none
`cost_estimator_copy_failed`	Copying a cost estimate fails.	none
`oil_consumption_result`	The consumption calculator normalizes a measured top-up interval.	amount_unit, distance_unit, has_manual_limit, comparison
`oil_consumption_copy`	A consumption result is copied.	none
`oil_consumption_copy_failed`	Copying a consumption result fails.	none
`oil_consumption_print`	A consumption result is printed.	none
`oil_consumption_save_evidence`	A consumption result is handed to the evidence builder.	none
`oil_consumption_save_evidence_failed`	The consumption-to-evidence handoff cannot save locally.	none
`oil_evidence_add`	An oil-change or top-up record is saved.	event_type
`oil_evidence_delete`	An oil evidence record is deleted.	none
`oil_evidence_export`	Oil evidence is exported.	format
`oil_evidence_copy`	Oil evidence handoff text is copied.	none
`oil_evidence_print`	Oil evidence is printed.	none
`oil_evidence_clear`	All local oil evidence is cleared.	none
`tool_state_share`	A supported tool creates a versioned fragment share link.	tool, outcome
`tool_state_restore`	A supported tool restores or rejects fragment state.	tool, outcome, reason
`next_action_click`	A next-best-action link is selected.	action, target
`chart_embed_copy`	Versioned chart embed code is copied.	version
`chart_asset_download`	A chart download link is clicked; this does not confirm a completed file transfer.	format, version
`chart_embed_copy_failed`	Copying chart embed code fails and manual selection is shown.	version
`substitution_result_copy`	A substitution decision card is copied.	risk, use, instead_of
`substitution_result_copy_failed`	Copying a substitution decision card fails.	risk, use, instead_of
`substitution_result_share`	A substitution page link is copied.	risk, use, instead_of
`substitution_result_share_failed`	Copying a substitution page link fails.	risk, use, instead_of
`substitution_result_print`	A substitution decision card is printed.	risk, use, instead_of

Launch snippets

The Google tag transport is built in; do not add another bridge that sends the same event. Custom events are not buffered or replayed when consent changes. Debug mode adds debug_mode to Google tag events after consent, and remains local without consent.

Endpoint

<script>
  window.OILMANUAL_ANALYTICS_ENDPOINT = 'https://analytics.example.com/oilmanual';
</script>

Local observation

<script>
  window.addEventListener('oilmanual:analytics', (event) => {
    console.log(event.detail.name, event.detail.detail);
  });
</script>