feat: add ga4 user registered handler

[leogermani]

All Submissions:

• Have you followed the Newspack Contributing guideline?
• Does your code follow the WordPress' coding standards and VIP Go coding standards?
• Have you checked to ensure there aren't other open Pull Requests for the same update/change?

Changes proposed in this Pull Request:

Closes # .

How to test the changes in this Pull Request:

Get the GA4 credentials. You will need your measurement ID and an API secret.

• api_secret - Required. An API SECRET generated in the Google Analytics UI. To create a new secret, navigate to:
  Admin > Data Streams > choose your stream > Measurement Protocol > Create
• measurement_id - Required. The measurement ID associated with a stream. Found in the Google Analytics UI under:
  Admin > Data Streams > choose your stream > Measurement ID

Store this info in the database:

wp option set ga4_measurement_id "G-XXXXXXXXXX"
wp option set ga4_api_secret YYYYYYYYYYYYYYYYYYY

Now, let's test:

1. Make sure RAS is active and that you have a registered reader
2. Make sure to add this constant to wp-config

define( 'NEWSPACK_LOG_LEVEL', 2 );
define( 'NEWSPACK_EXPERIMENTAL_GA4_EVENTS', true );

4. Register the site (either via a registration prompt or from the my account page)
5. Watch the reader_registered event being fired in the logs

[NEWSPACK-DATA-EVENTS][Newspack\Data_Events::dispatch]: Dispatching action "reader_registered" via Action Scheduler.

6. Watch the handler being triggered and sending the reader_registered GA event:

[NEWSPACK-DATA-EVENTS][Newspack\Data_Events::handle]: Executing action handlers for "reader_registered".
[NEWSPACK-DATA-EVENTS-GA4][Newspack\Data_Events\Connectors\GA4::log]: Event sent - reader_registered

7. Visit the Google Analytics Realtime dashboard
8. See the reader_registered events coming in
9. Inspect them and see the registration_method attribute set as registration-block for the times you registered via the registration block.
10. See that the referer attribute is correct
11. Register from inside a popup and see that, in those cases, you'll also get some campaign specific data:

(
    [logged_in] => yes
    [ga_session_id] => 1677185108
    [is_reader] => yes
    [registration_method] => registration-block-popup
    [campaign_id] => 139
    [campaign_title] => Registration Overlay
    [campaign_frequency] => always
    [campaign_placement] => center
    [campaign_has_registration_block] => 1
    [campaign_has_donation_block] => 
    [campaign_has_newsletter_block] => 
    [referer] => /2023/02/07/accumsan-nam-mauris-erat-ultrices-nascetur-porta-ornare-est-class-cursus-massa-lectus/
)

(you can also add a debug to the handle_reader_registered method to see these params being set).

Note that this PR also fixes kind of a bug. Something that was working by accident.

In the line:

$metadata['current_page_url']    = home_url( add_query_arg( array(), \wp_get_referer() ) );

wp_get_referer() always returns false because the referer is the same page as the current page. (It's a post to itself). The accident is that if the second parameter to add_query_arg is false, it will use the current URL instead. And since this is a post to itself, the result is the same...

But my code fixes it and we now actually read the value from the _wp_http_referer in the form.

Other information:

• Have you added an explanation of what your changes do and why you'd like us to include them?
• Have you written new tests for your changes, as applicable?
• Have you successfully ran tests with your changes locally?

[miguelpeixe]

Why not make it a global handler that watches every event? A global handler exists mostly for analytics integrations like this one.

[leogermani]

I'll explore it

I want to have each event handler in its own callback for the sake of organization, I didn't want to have one big callback with a switch case or anything like it. But let me give it a go

[miguelpeixe]

This feels like a very fragile implementation. If the watched_events are modified it will call for an undefined method.

[miguelpeixe]

In the context of a global handler for analytics, it can look like this:

Being a global hanler, this suggestion assumes the first argument of the method is the $action_name.

Suggested change

	$params['registration_method'] = $data['metadata']['registration_method'] ?? '';
	$event = new Event( 'reader_registered', $params );
	self::send_event( $event, $client_id, $timestamp, $user_id );
	$event = new Event( $action_name, $data );
	self::send_event( $event, $client_id, $timestamp, $user_id );

[leogermani]

I cant' simply pass whatever is in $data to GA4. Each event will have its own handler to add the appropriate parameters

[miguelpeixe]

I wish we could. The listeners' documentation would be the source of truth on what and how we collect and we avoid having another layer of support for each new trackable thing. The more we track the better, there's no downside to that IMO.

[leogermani]

There's a limit of 25 parameters an event can have in GA, so I think we want to carefully choose what we will track.

Also, some events have arrays as parameters, that need to be treated...

[leogermani]

@miguelpeixe This is ready for another review.

I slightly changed the implementation, using a global handler, but I kept one method for each event. Each event will have a very unique way of setting up its parameters. (In fact, if this gets too big, I might refactor it into having each event handling in one simple child class with only one method)

Please note that the handle_reader_logged_in doing nothing is also intentional. I want to be as explicit as possibe, and avoid situations where event tracking would silently fail without anyone noticing.

Note that I've updated the test instructions.

[miguelpeixe]

The registration metadata is being logged as described, except for the campaign popup metadata, which I was not able to test:

[miguelpeixe]

This is no longer a specific handler method

[leogermani]

fixed

[miguelpeixe]

Don't know the reason, but the newspack_popup_id is not being populated to my registration through a campaigns popup. This is the resulting params from a center overlay campaign:

(
    [logged_in] => yes
    [is_reader] => yes
    [registration_method] => registration-block
    [referer] => /
)

[leogermani]

Check if you have blocks and popups plugins in the latest master and that they are built

[miguelpeixe]

It was the popups plugin that was outdated!

[miguelpeixe]

After getting all params working from a campaigns' prompt the GA4\Event::validate_params() is not happy with it:

[28-Feb-2023 13:24:09 UTC] [57031][NEWSPACK-DATA-EVENTS][Newspack\Data_Events::handle]: Executing global action handlers for "reader_registered".
[28-Feb-2023 13:24:09 UTC] Array
(
    [logged_in] => yes
    [is_reader] => yes
    [registration_method] => registration-block-popup
    [campaign_id] => 394
    [campaign_title] => Reader Registration
    [campaign_frequency] => daily
    [campaign_placement] => center
    [campaign_has_registration_block] => 1
    [campaign_has_donation_block] =>
    [campaign_has_newsletter_block] =>
    [referer] => /
)

[28-Feb-2023 13:24:09 UTC] [57031][NEWSPACK-DATA-EVENTS][Newspack\Data_Events::handle][ERROR]: Invalid event parameters. Limit is 25 parameters, included the default parameters. Values must have a max of 100 characters.

This error message is not too helpful because it can be any of:

• Max params count exceeded
• Invalid param name on any of the params
• Invalid param value on any of the params

Perhaps the validate_params() method could be the thrower and more verbose?

In this case, this is the culprit: [campaign_has_registration_block] => 1. The validation is not happy with its value because the method doesn't handle a boolean.

[miguelpeixe]

I also suggest making the GA4\Event parse the parameters to become valid while still logging the issue so it can be fixed. We don't want to lose the entire event due to bad parameter(s).

I suggest the parsing to:

• transform invalid names to become valid by replacing/removing characters when possible (slugify?)
• add an extra parameter containing a list of the names of parameters that were removed in case of an invalid value or exceeded the limit of 25

[leogermani]

This error message is not too helpful

Yes, I know. I struggled a bit when I was doing this and decided to keep it simple for starters because I didn't want to over complicate.

But I agree with you, let's make it correct and sanitize the parameters and just throw a warning log in case something is invalid.

[leogermani]

@miguelpeixe done!

I want to keep the Event class simple, as the source of truth of the limitations that GA4 has to events. And I didn't want to transform validation methods into validate & sanitize...

So I made the event values a little more flexible, accepting data types we can easily convert to strings, but still throwing error otherwise.

And then added the validating and error handling to our class. I think it looks ok now.

In the future we might want to surface these errors, and the events api errors in general, somehow....

[miguelpeixe]

Thank you for the tweaks and improved debugging! It's working great now 🎉:

Non-blocking NIT, by instantiating a new Event() with name and params, isn't non-static methods a better practice for this case?

$event = new Event( $name, $params );
if ( ! $event->has_valid_name() ) {
	throw new \Exception( 'Invalid event name' );
}

[leogermani]

by instantiating a new Event() with name and params, isn't non-static methods a better practice for this case?

Not necessarily. If the method does not interact or depend on anything from the instanced object, it could be static.

It could be non-static if it was, for example, writing the errors to a errors attribute in the object, or manipulating the object attributes... but then this would grow in complexity.

By keeping it static we are saying "If you provide me invalid params, I will throw exceptions, use my static methods to validate them before instantiating an object. It's also super easy to test those methods as well.

[matticbot]

🎉 This PR is included in version 1.106.0-alpha.1 🎉

The release is available on GitHub release

Your semantic-release bot 📦🚀

[matticbot]

🎉 This PR is included in version 1.106.0 🎉

The release is available on GitHub release

Your semantic-release bot 📦🚀