Create Proxy Event Tracking Function to Add Site Kit as Source for All ICE Events

[10upsimon]

Feature Description

As part of the initial event conversion infrastructure work, the need to add an event parameter citing Site Kit as the source of events tracked as part of this epic has been identified.

Given the decoupled nature of the event tracking infrastructure - where supported plugins have their own JS files - it has been discussed that the simplest way to achieve this would be via a proxy style function that is defined in a script that in turn is a dependency to individual plugin script enqueues, much like Script_Data functions. Note, this is not an actual proxy function, merely a helper function abstracting our calls to gtag when we track events.

This body of work requires the need to define said function in a self contained script asset, set it as a dependency for all singular plugin JS scripts and update all individual plugin JS scripts to make use of this new helper function. This helper function should be define against a globally available Site Kit specific var, such as _googlesitekit, so that all plugins requiring it can access it easily from said global.

Said function should accept an event name and an event data object. Said event data object will then be merged so that it always contains the a _source property with a value of 'site-kit'.

A proof-of-concept function was shared as follows:

window._googlesitekit.trackEvent(name, data) {
  dataLayer = dataLayer || [];
  gtag = function () { dataLayer.push(arguments) }
  gtag('event', name, {...data, _source: 'site-kit' })
}

---

Do not alter or remove anything below. The following sections will be managed by moderators only.

Acceptance criteria

• A new helper function (acting as an abstraction/proxy to event tracking) should be created as a new asset for enqueue, and be set as a script dependency for all standalone plugin JS scripts supported in the Initial Conversion Events (ICE) epic
  • Said function should be loaded async using the relatively new async/defer support of WP_Scripts
  • Said function should track the intended event against gtag and ensure that site-kit is added as a _source event parameter value for all events tracked via this proxy/helper function
  • Said function should be attached to the global _googlesitekit var
  • All existing plugin scripts of the listed supported plugins should be updated to be loaded async and include this new script as a dependency
  • All future plugin scripts should utilise this new script as a dependency, and also be loaded in an async manner

Implementation Brief

• Add assets/js/track-conversion-event.js
  • Define new function, say trackConversionEvent and attach it to the _googlesitekit global, example global._googlesitekit.trackConversionEvent
  • It should accept name parameter - representing a conversion event name, and a data parameter which holds event data object with any additional details conversion provider might include.
  • Track the event against gtag function, using passed parameters, including _source: 'site-kit' to the event data (it should be merged with data parameter if present). You can check example POC in the issue description.
• Update includes/Core/Conversion_Tracking/Conversion_Tracking.php
  • Add register_event_tracking_script
    • Instantiate new Script including the above JS file and return the instance. It should include 'execution' => 'async' in the arguments.
  • In register method under existing wp_enqueue_scripts hook, before the scripts from active providers are enqueued:
    • If conversionInfra feature flag is enabled retrieve the tracking script instance with register_event_tracking_script method and invoke register_script() and enqueue() on it.
• Update existing conversion providers, individual provider JS file should adapt the usage of global._googlesitekit.trackConversionEvent and individual Google\Site_Kit\Core\Conversion_Tracking\Conversion_Events_Provider::register_script method should include 'execution' => 'async' in the arguments of Script, and have assets/js/track-conversion-event.js as dependency.
• Update webpack/basicModules.config.js webpack partial
  • Include assets/js/track-conversion-event.js to the entry

Test Coverage

• No updates needed

QA Brief

• Set up the site and event providers using QA briefs from Add Plugin integration for Contact Form 7 #8574, Add plugin integration for OptinMonster #8554, Add Plugin Integration for WPForms #8572, Add Plugin Integration for Mailchimp #8571, WIP: POC for PAX userActionService. #8750, and Add plugin integration for WooCommerce #8553
• Verify that events tracked for WPForms, Contact Forms 7, OptIn Monster, Popup Maker, Mailchimp, and WooCommerce providers now tracked with _source: "site-kit".

Changelog entry

• Update conversion tracking events to include source of event tracking as Site Kit.

[tofumatt]

From the context/ACs here, would there be a separate, inline script if the user was using two ICE scripts (eg. using two ICE-supported plugins)?

Why output the script inline instead of having a single, common script file we build and include whenever any ICE JS script is used?

[10upsimon]

@tofumatt as per out comms offline, I think it makes sense to:

• Have this function be contained within it's own script that we will enqueue
• Register it as a dep of all singular plugin scripts
• Load it async
• Load all singular plugin tracking scripts async too

I'll update the AC accordingly.

[tofumatt]

Just one question really, when you say a “proxy function”, do you mean an actual JS Proxy? Or do you just mean that our scripts should include/reference the new trackEvent function and use it to send events?

If it’s the latter, the AC should specify that it should be available (on a Site Kit JS global I’d think).

If the former: why? 😅 Proxies when it’s just for our code seems odd. Maybe it’s just a wording thing that’s tripping me up here 😆

[10upsimon]

Just one question really, when you say a “proxy function”, do you mean an actual JS Proxy?

@tofumatt no no, not an actual proxy :) I simply meant a helper function that abstracts our calls to gtag when we track events. Yes, this should be defined against the global _googlesitekit or similar var, but that seems more like IB territory. I'll update the AC to reflect the above.

[aaemnnosttv]

FWIW, I think we should avoid using trackEvent as the name to avoid confusion with our internal function by the same name.

[tofumatt]

Sounds good, moving to IB 👍🏻

[10upsimon]

@zutigrm

• Update includes/Modules/Ads.php
  • In setup_assets method:
    • If conversionInfra feature flag is enabled instantiate new Script registering the above JS file and pushing it to the $assets array.
    • It should include 'execution' => 'async' in the arguments.

I do not think this is correct, as Conversion Tracking is not specific to the Ads module, and can be turned on from GA4 without the ads module active, and vice-versa.

I think it may be better to register this script from within the Conversion_Tracking class. WDYT?

[zutigrm]

@10upsimon Yes that makes more sense. Thanks. IB updated

[10upsimon]

Thanks @zutigrm IB ✅

[benbowler]

Flagging here that @eugene-manuilov doesn't update the tracking for MailChimp or Popup Maker as these weren't merged at the time this ticket was started.

Should we hold back this ticket and address that here when these two are merged or update those separately?

[tofumatt]

@benbowler I think it makes sense to add those here. I'll do that in the PR, it's not a big deal to include 🙂

EDIT: Never mind, they were included later 🙂

[mohitwp]

QA Update ⚠️

• Tested on dev environment.
• Verified Optin Monster, WP Forms, MailChimp, Popup Maker and WooCommerce plugin events.
• Verified that events tracked for WPForms OptIn Monster, Popup Maker, Mailchimp, and WooCommerce providers now tracked with _source: "site-kit".
• Verified when conversionInfra feature flag is enabled.
• Verified when Analytics is connected.
• Verified when both Analytics and ads module are connected.
• Verified when only Ads module is connected.

Note : As mentioned on #8553 (comment) for WooCommerce only 'add to cart' event is getting tracked.

@wpdarren I'm not able to test Contact Form 7 event on InstaWP and TasteWP due to same error. Can you please retest this on your live site ?

Optin monster

Submit lead form event tracked when only analytics is connected

When only Ad module is connected

WP Forms

When only Ads module is connected

When only Analytics is connected

MailChimp

When only Analytics is connected

When only Ads module is connected

Popup Maker

When only ads module is connected

When only Analytics is connected

WooCommerce -

Add to cart event tracked

[wpdarren]

@mohitwp yes, I can confirm that the source appears for the contact conversion event.

[mohitwp]

QA Update ✅

Thanks @wpdarren !

• Tested on dev environment.
• Verified Optin Monster, WP Forms, MailChimp, Popup Maker, Contact Form 7 and WooCommerce plugin events.
• Verified that events tracked for WPForms OptIn Monster, Popup Maker, Mailchimp, and WooCommerce providers now tracked with _source: "site-kit".
• Verified when conversionInfra feature flag is enabled.
• Verified when Analytics is connected.
• Verified when both Analytics and ads module are connected.
• Verified when only Ads module is connected.

Note : As mentioned on #8553 (comment) for WooCommerce only 'add to cart' event is getting tracked.

Optin monster

Submit lead form event tracked when only analytics is connected

When only Ad module is connected

WP Forms

When only Ads module is connected

When only Analytics is connected

MailChimp

When only Analytics is connected

When only Ads module is connected

Popup Maker

When only ads module is connected

When only Analytics is connected

WooCommerce -

Add to cart event tracked

[aaemnnosttv]

Noting that the source parameter may change but it is currently implemented as defined.

One thing from the AC

All existing plugin scripts of the listed supported plugins should be updated to be loaded async and include this new script as a dependency

All the provider scripts should be loaded using defer – async scripts can't have dependencies since the load order isn't guaranteed. There are still a few scripts loading async so these will need to be updated in a follow up.