GA4 Analytics Tracking

The <Analytics /> component (mounted automatically by <ThemeProviders />) injects the GTM script when globalConfig.externalScripts.analytics.gtmId is set. From there themes opt in to specific GA4 events using the components and utilities below.

Page views

Mount <PageView /> on each page template you want tracked. It fires a single ga4_pageview event on mount with brand name, page template identifier, and optional property/branch context. It waits for the user provider to finish loading before pushing so user info is included when the visitor is signed in.

import PageView from '@homeflow/v4-lib/components/external-scripts/page-view.component';

<PageView
  agency={JSON.parse(JSON.stringify(agency))}
  property={JSON.parse(JSON.stringify(property))}
  template="properties show"
/>
Copy

The agency, property, and branch props must be plain JSON — pass through JSON.parse(JSON.stringify(...)) if you have a model instance from Agency.current() etc.

The event payload is shaped for the structured GA4 schema used by Connells sites; any theme that wants the same payload conventions can mount it.

CMS-edited link analytics tags

The rich-text link dialog can show input fields for data-* analytics attributes on tel: / mailto: links. Add the attribute list to the theme's theme registry - the file at the theme's root that feeds admin's ThemeRegistryProvider:

Example:

// theme-registry.ts
import type { ThemeRegistry } from '@homeflow/v4-lib/providers/theme-registry-provider';

const THEME_REGISTRY: ThemeRegistry = {
  ...
  linkAnalyticsAttributes: [
    { name: 'data-department-name', label: 'Department name' },
    { name: 'data-branch-id', label: 'Branch ID' },
    { name: 'data-branch-type', label: 'Branch type (sales / lettings)' },
  ],
};

export default THEME_REGISTRY;
Copy

Themes that omit linkAnalyticsAttributes get no analytics fieldset in the link dialog, however the TipTap link extension recognises the registered keys at the schema level so they survive parse cycles when added via source view.

Lead form submissions

Form submission events (ga4_form_submit) are wired automatically when the form goes through submitLeadForm. See Lead Submissions for the recaptcha + dataLayer flow.

Custom event names per form type live on globalConfig.externalScripts.analytics.gtmCustomEventNames (configured per site in admin → scripts). Read the relevant key (viewingEnquiry, branchEnquiry, mortgageEnquiry, userRegistration, etc.) and set it on the form's data-form-name attribute.

Save property / save search / sign-up / login

Push these directly via sendGAEvent({...}) from @homeflow/v4-lib/utils/google-analytics. The helpers buildGAPropertyObject(property, branch) and buildGAUserObject(user) produce the rich payload shapes.

• ga4_sign_up — fire from useRegisterUser({ onSuccess })'s callback. The hook passes the new user data synchronously after registration.
• ga4_login — fire from the sign-in form after signIn() returns OK. Use a state flag and an eventFired guard so the auto-sign-in inside useRegisterUser doesn't double-fire it (that path produces ga4_sign_up instead).
• ga4_save_property — fire from the save button's onAdd callback with { event: 'ga4_save_property', ga4_property_object: buildGAPropertyObject(property) }.
• ga4_save_search — fire from the save-search button's onAdd callback.