📊 Analytics (Google Analytics 4)

The OV25 configurator can tell your own Google Analytics 4 (GA4) what shoppers do inside the 3D viewer: when it loads, when they change an option, spin the model, view dimensions, or launch AR. With that data you can measure how 3D engagement affects add‑to‑carts, conversion, and revenue.

This guide covers the standard iframe integration. It works no matter how you embed the configurator, and you can have it running in a few minutes.

How it works

The configurator runs inside an <iframe> on your product page. As the shopper interacts with it, the iframe sends a small message to your page for each interaction (using the browser's standard postMessage). You add a short script that listens for those messages and passes them on to Google Analytics.

Shopper interacts  →  iframe sends "ANALYTICS_EVENT" message  →  your script  →  Google Analytics 4

Two things are worth knowing up front:

• There is nothing to switch on inside the configurator. It always sends these messages. If your page isn't listening, they simply go nowhere — no data is recorded and there's no performance cost. You "turn it on" by adding the listener script below.
• The data goes into your GA4 property, on your page. You don't give OV25 your GA4 ID. Your existing Google Analytics / Tag Manager and cookie‑consent setup stay in full control.

Step 1 — Add the listener to your page

Paste this script onto the page that contains the configurator, after your Google Analytics or Google Tag Manager snippet. That's the whole integration on the OV25 side.

<!-- OV25 → Google Analytics bridge. Add this after your GA / GTM snippet. -->
<script>
(function () {
  if (window.__ov25BridgeInstalled) return;          // avoid adding it twice
  window.__ov25BridgeInstalled = true;
 
  var OV25_ORIGIN = 'https://configurator.orbital.vision';
  var seen = new Map();
 
  function send(name, params) {
    if (window.dataLayer) {                            // Google Tag Manager
      window.dataLayer.push(Object.assign({ event: 'ov25_event', event_name: name }, params));
    } else if (window.gtag) {                          // gtag.js directly
      window.gtag('event', name, params);
    }
  }
 
  window.addEventListener('message', function (event) {
    if (event.origin !== OV25_ORIGIN) return;          // only trust the OV25 configurator
    var data = event.data;
    if (!data || data.type !== 'ANALYTICS_EVENT') return;
 
    var payload;
    try { payload = typeof data.payload === 'string' ? JSON.parse(data.payload) : data.payload; }
    catch (e) { return; }
    if (!payload || !payload.event_name) return;
 
    // Ignore the occasional duplicate message.
    var now = Date.now();
    if (payload._id) {
      if (seen.has(payload._id) && now - seen.get(payload._id) < 10000) return;
      seen.set(payload._id, now);
    }
 
    var name = payload.event_name;
    delete payload.event_name; delete payload._id;
    send(name, payload);
  });
})();
</script>

What it does, in plain terms:

• Listens for messages on the page.
• Only trusts the OV25 configurator — it checks the message came from configurator.orbital.vision and ignores everything else, so nothing on your page can fake events.
• Drops duplicates — the same event can occasionally arrive twice; the script keeps just one.
• Forwards each event to Google Tag Manager (dataLayer) if you have it, otherwise straight to gtag.

Step 2 — Pick how events reach GA4

The script supports the two normal Google Analytics setups. You don't choose a setting — it automatically uses whichever you already have:

Step 3 — Google Tag Manager setup (GTM users only)

If you route analytics through GTM, do this once so the events reach GA4. It's a single trigger and a single tag for all OV25 events.

1. Data Layer Variables — create one for each value you want to see in reports: event_name, product_id, product_name, option_name, selection_name, selection_id, engagement_type, device.
2. Trigger — create a Custom Event trigger with the event name ov25_event.
3. Tag — create a GA4 Event tag:
   • Event Name: {{event_name}} (the Data Layer Variable from step 1)
   • Event Parameters: add each variable above as a parameter of the same name.
   • Trigger: the ov25_event trigger from step 2.
4. Submit / Publish your container.

Step 4 — Make the details show up in reports

GA4 won't display custom details like option_name or selection_name until you register them as custom dimensions — and it only starts collecting them from that point on (it can't backfill). So do this before you rely on the data.

In GA4: Admin → Custom definitions → Create custom dimension, with scope Event, for each detail you care about: option_name, selection_name, engagement_type, device, product_id.

Step 5 — Check it's working

1. Open your product page with the browser console open.
2. In GA4, open Admin → DebugView (use GTM Preview mode, or temporarily add gtag('config', 'G-XXXX', { debug_mode: true })).
3. Load the page — you should see ov25_configurator_loaded, then ov25_product_view.
4. Change an option, spin the model, open dimensions, launch AR — you should see ov25_option_changed, ov25_spin, ov25_dimensions_viewed, and ov25_ar_launched.

What events you'll see

Every event also carries device (desktop / mobile / tablet). ov25_option_changed carries auto_loaded: true when the configurator picked an option for the shopper (e.g. a default) rather than the shopper choosing it — filter on this if you only want deliberate choices.

Measuring sales impact

To connect 3D engagement to revenue, send GA4's standard add_to_cart and purchase events from your own cart and checkout (that's where the real transaction is), and add configurator_engaged: true to them. You can then compare conversion and revenue for shoppers who used the configurator against those who didn't.

Report ideas

Once events and dimensions are in place, build these in a GA4 Exploration or Looker Studio:

• Engagement rate — share of product‑page visits that interact with the configurator.
• Conversion, with vs. without 3D — purchase rate for sessions that used the configurator vs. those that didn't.
• Most‑popular options — ov25_option_changed grouped by option_name and selection_name.
• Drop‑off funnel — loaded → option changed → add to cart → purchase.
• AR usage — how many shoppers launch AR, and whether they convert better.

Privacy

The configurator only sends these messages; it never sets a Google Analytics cookie and never loads Google's scripts for you. All collection happens on your page, in your GA4 property, so your existing cookie‑consent banner / Google Consent Mode governs it exactly like the rest of your analytics.

Troubleshooting

No events at all. Check the script is on the page and loads after your GA/GTM snippet, and that OV25_ORIGIN is exactly https://configurator.orbital.vision. Add a console.log inside send() to confirm messages are arriving.

Events show in DebugView but reports are empty. You either haven't registered the custom dimensions (Step 4), or you're still inside the 24–48 hour processing window (Step 5).

Events appear twice. Make sure you kept the duplicate check (the _id part of the script) and that the script is only added once.

I want the events in my own code too. Add your own line inside send() (for example, push to your CDP or console.log) — it runs for every event alongside the GA4 forwarding.