Analytics event catalog

Events are local-first. They dispatch oilmanual:analytics, optionally push to dataLayer, and send to a network endpoint only when window.OILMANUAL_ANALYTICS_ENDPOINT is configured.

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

Payload schema

Field	Type	Meaning
`name`	string	Event name, 2-80 chars, matching `[a-z0-9_.:-]`.
`detail`	object	Sanitized event-specific fields with string/number/boolean values.
`path`	string	Current site pathname, such as `/search`.
`ts`	string	Client-side ISO timestamp.

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
`search_results`	Pagefind returns results.	query, count
`search_no_results`	Pagefind returns zero results.	query, count
`search_shortcut`	A popular-search or empty-state shortcut is selected.	query, source
`search_result_click`	A user opens a Pagefind result.	target
`source_clicked`	A user opens a primary editorial source.	source, target
`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.	record, confidence, source_tier
`correction_submit_attempt`	Correction form submit is attempted.	page, record
`correction_submit_success`	The hosted correction endpoint accepts a correction.	page
`correction_submit_fallback`	The correction endpoint is unavailable and email fallback is shown.	page
`correction_submit_validation`	Correction evidence is incomplete or the endpoint returns field errors.	page, record
`correction_mailto_opened`	The prepared correction email fallback is opened.	page, record
`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.	make, model, year, engine
`car_lookup_unresolved`	YMME lookup has no matching car record.	make, model, year, engine
`car_lookup_opened`	The resolved car record is opened.	make, model, year, engine
`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.	capacity, diy_total, shop_total
`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_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

Set an endpoint before the analytics helper loads, or bridge the local event to a tag manager. Without either snippet, analytics remains local-only.

Endpoint

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

Data layer bridge

<script>
  window.dataLayer = window.dataLayer || [];
  window.addEventListener('oilmanual:analytics', (event) => {
    window.dataLayer.push({
      event: 'oilmanual.' + event.detail.name,
      oilmanual: event.detail
    });
  });
</script>