Track custom events on Grav 1.7 Twig themes

Start with the Grav 1.7 Twig themes installation

These instructions target Grav's documented 1.7 Twig theme structure. Find the active theme's templates/partials/base.html.twig and add the deferred tracker inside head. Preserve existing blocks, asset output and page content. Maintain the change in a custom or inherited theme rather than an unmanaged installed-theme edit, then clear relevant caches and inspect public output.

Grav page templates commonly extend the shared base, but modular pages and custom templates can use another structure. Check the active theme and inheritance before assuming the base file covers every route. Do not treat a browser tracker as a Grav backend plugin.

Use the public project key from the DataSag project you are inspecting. A test on a preview domain does not confirm that the production domain has the same code or settings.

Track custom events in Grav 1.7 Twig themes

1. Add a goal attribute to an owned theme link or button, using the actual Twig template selected for that page. Inspect rendered markup because a plugin or content filter can transform or sanitize source HTML.
2. For a completed form action, invoke the existing browser API from a confirmed success hook supported by your form implementation. Do not call it from Twig rendering or assume that clicking a submit button proves delivery.
3. Test on the public page after clearing relevant caches. Include a failed validation attempt and a successful action where applicable. If modular content reuses the same control, verify that one interaction does not trigger duplicate custom listeners.

Public theme controls record their defined browser action once, with completed-form claims tied to observable success.

Complete the collection checks

1. Write the event definition first. For example, signup_click means a visitor pressed a signup link, while signup_completed means your application confirmed account creation.
2. For click intent, add data-datasag-goal to the element. The tracker delegates clicks, so you do not also need a JavaScript handler for the same goal.
3. For a completed action, call the JavaScript API in the success handler. Wait for the tracker to be available. An optional guard avoids a crash but intentionally drops the event if the tracker has not loaded.
4. Send only the context needed for the report, such as a form or plan name. Do not include email addresses, passwords, payment details or freeform form contents.
5. Complete one successful and one failed attempt. Inspect /api/track for the exact eventName and properties. Only the successful attempt should emit a completed-action event.
6. Check the event report available to your plan. Collection and access to reports are separate; review current plan details before depending on a particular report.

<!-- Click intent: use this OR your own click handler -->
<a href="/signup" data-datasag-goal="signup_click">Create account</a>

// JavaScript: inside the confirmed-success handler
window.datasag?.track('signup_completed', { form: 'main_signup' });

For a click goal, add data-datasag-goal to theme markup that survives Twig rendering. A confirmed form event requires a browser success hook from your actual form implementation. Twig server rendering cannot establish that a visitor later completed an action.

What a successful check looks like

A controlled successful action produces one event with the agreed name. A validation failure does not emit a success event. Network evidence matches the report definition.

Record the public path you tested, the browser state, the approximate time and the observed request. Check one direct page load and one later navigation so the result covers more than the homepage.

Common mistake

A goal attribute on a submit button measures clicks, including attempts that fail. Do not report those clicks as completed signups or purchases.

Installation snippet for Grav 1.7 Twig themes

The shared installation belongs in the head in the active theme templates/partials/base.html.twig. Use this as the installation reference while checking the procedure above.

<script defer src="https://www.datasag.com/tracker.js" data-datasag-key="YOUR_PUBLIC_KEY"></script>

Related Grav 1.7 Twig themes guides

• Verify DataSag analytics
• Fix DataSag analytics not working
• Fix duplicate analytics pageviews
• Track UTM campaigns
• Measure AI referral traffic
• Configure CSP for DataSag analytics
• Exclude your own analytics visits
• Load analytics without blocking rendering

Full Grav 1.7 Twig themes setup guide · Search and AI visibility

References

Official Grav 1.7 Twig themes documentation covers the integration point. For DataSag data handling, read the privacy policy. Use support if a request fails after these checks.