feat(reader-data): add engagement fields by chickenn00dle · Pull Request #4594 · Automattic/newspack-plugin

chickenn00dle · 2026-03-24T16:50:46Z

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:

Adds five new reader data fields to the Reader Data library for tracking reader engagement behavior:

first_visit_date — Timestamp of the reader's first visit (set once, never overwritten)
last_active — Timestamp of the reader's most recent page load (updated every page load)
articles_read — Count of unique articles viewed (derived from article_view activities)
favorite_categories — Top 5 category IDs by view frequency (derived from article_view activity data)
paywall_hits — Count of paywall encounters

All fields are client-authoritative and server-persisted — computed in JS, stored in localStorage, and synced to server via the existing store sync mechanism for logged-in users.

Closes https://linear.app/a8c/issue/NPPD-1387/create-new-fields-on-reader-data-library .

How to test the changes in this Pull Request:

Open DevTools and view Local Storage, filter by np_reader_1_
Clear localStorage, reload the page
Verify np_reader_1_first_visit_date and np_reader_1_last_active appear with timestamp values
Reload again — verify first_visit_date is unchanged but last_active has a newer timestamp
Navigate to an article — verify np_reader_1_articles_read appears with value 1
Navigate to a different article (ideally in a different category) — verify articles_read is now 2
Check np_reader_1_favorite_categories — should contain an array of category IDs
Paywall test: Enable a paywall, and as an anonymous visitor, verify np_reader_1_paywall_hits increments
Sync test: Log in as a reader, verify fields sync to server via Network tab (POST requests to /newspack/v1/reader-data)

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?

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

includes/content-gate/class-metering.php

src/content-gate/metering.js

Copilot

Pull request overview

Adds new engagement-related Reader Data fields and wires them into both the Reader Activation JS library and content-gate metering (JS + PHP) so engagement metrics can be persisted and synced for readers.

Changes:

Initialize/store first_visit_date and last_active on the client during Reader Activation init.
Derive and store articles_read and favorite_categories from article_view activity history.
Increment paywall_hits for anonymous readers in JS metering and for logged-in readers in PHP metering.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
src/reader-activation/index.js	Wires engagement setup into Reader Activation initialization.
src/reader-activation/engagement.js	Adds client-side initialization for `first_visit_date` and `last_active`.
src/reader-activation/article-view.js	Adds derived aggregates `articles_read` and `favorite_categories` from `article_view` activities.
src/content-gate/metering.js	Increments `paywall_hits` for anonymous metering blocks.
includes/content-gate/class-metering.php	Increments `paywall_hits` for logged-in metering blocks server-side.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

src/reader-activation/article-view.js

src/reader-activation/engagement.js

includes/content-gate/class-metering.php

Copilot

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated 4 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

src/content-gate/gate.js

src/reader-activation/mocks/ras.js

src/reader-activation/article-view.test.js

chickenn00dle · 2026-03-24T20:03:55Z

src/content-gate/gate.js

 		const detectSeen = () => {
 			const delta = ( gate?.getBoundingClientRect().top || 0 ) - window.innerHeight / 2;
 			if ( delta < 0 ) {
+				handleSeen( gate, ! seen );


Just noting I initially removed the typeof window.gtag check below to ensure this only triggers once, but it seems this check is to avoid a race condition and ensure the listener isn't removed when gtag hasn't been added to window before this runs. So instead, I am adding a seen flag to determine when to update paywall hits.

chickenn00dle · 2026-03-24T20:06:35Z

src/reader-activation/article-view.js

+		const topCategories = Object.entries( catCounts )
+			.sort( ( a, b ) => b[ 1 ] - a[ 1 ] )
+			.slice( 0, 5 )
+			.map( ( [ id ] ) => Number( id ) );


The spec calls for a list of category strings, but since we only have ids here, I am storing ids which can be converted to string representation in the backend. But let me know if we prefer to store as strings here instead.

miguelpeixe · 2026-03-31T20:47:58Z

src/reader-activation/engagement.js

+	// first_visit_date — Date of the reader's very first visit to the site, regardless of whether or not they registered.
+	if ( ! ras.store.get( 'first_visit_date' ) ) {
+		ras.store.set( 'first_visit_date', Date.now() );
+	}


The store sync strategy will overwrite this on every new authenticated session. The fresh session will generate a new first_visit_date and upon authentication, the new value will replace the one in the db:

newspack-plugin/src/reader-activation/store.js

Lines 263 to 266 in bb4813c

// Do not overwrite items that were pending sync.

if ( unsynced.includes( key ) ) {

continue;

}

I don't think we ever got a consensus on whether the stored value takes precedence over the new value from the reader session. There's a case for both...

Good catch @miguelpeixe!

I added a commit to ensure we always defer to the oldest date for first_visit_date here: 4a7f352

I suspect first_visit_date might be the only key which requires the stored value take precedence as the other fields should be updated with the latest activity right? I'm happy to revisit this if this isn't the case though.

I think this works well for this case. I'm working on a session hydration feature in #4618 that will require some tweaks to support this new requirement. I can adapt once this is merged.

miguelpeixe · 2026-03-31T20:52:43Z

src/reader-activation/article-view.js

+			.sort( ( a, b ) => b[ 1 ] - a[ 1 ] )
+			.slice( 0, 5 )
+			.map( ( [ id ] ) => Number( id ) );
+		ras.store.set( 'favorite_categories', topCategories );


Can we replace the existing favorite_categories matching function on newspack-popups to use this, so we have a single source of truth?

Sure thing! I'll work on this in this PR: Automattic/newspack-popups#1542

Looks like we're losing part of the matching logic, to have at least 2 categories or 2 posts within the same category.

Do you think we can move that from the matching function to the list generation itself? In reality, the reader shouldn't really have a favorite category if they just read a single article that happens to match a category.

Good call. Added a filter for this in 68296d0

miguelpeixe

Thank you for the revisions!

github-actions · 2026-04-02T19:44:21Z

Hey @chickenn00dle, good job getting this PR merged! 🎉

Now, the needs-changelog label has been added to it.

Please check if this PR needs to be included in the "Upcoming Changes" and "Release Notes" doc. If it doesn't, simply remove the label.

If it does, please add an entry to our shared document, with screenshots and testing instructions if applicable, then remove the label.

Thank you! ❤️

feat(reader-data): add engagement fields

b3297a6

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

chickenn00dle commented Mar 24, 2026

View reviewed changes

includes/content-gate/class-metering.php Outdated Show resolved Hide resolved

chickenn00dle commented Mar 24, 2026

View reviewed changes

src/content-gate/metering.js Outdated Show resolved Hide resolved

chickenn00dle marked this pull request as ready for review March 24, 2026 17:00

chickenn00dle requested a review from a team as a code owner March 24, 2026 17:00

Copilot AI review requested due to automatic review settings March 24, 2026 17:00

Copilot started reviewing on behalf of chickenn00dle March 24, 2026 17:01 View session

Copilot AI reviewed Mar 24, 2026

View reviewed changes

src/reader-activation/article-view.js Outdated Show resolved Hide resolved

src/reader-activation/engagement.js Show resolved Hide resolved

includes/content-gate/class-metering.php Outdated Show resolved Hide resolved

chickenn00dle added 2 commits March 24, 2026 13:08

fix: check metered state after filter

c3db9f4

fix: add unit tests

ab17b6a

chickenn00dle added [Status] Needs Review The issue or pull request needs to be reviewed and removed [Status] Needs Review The issue or pull request needs to be reviewed labels Mar 24, 2026

chickenn00dle force-pushed the feat/reader-data/add-engagement-fields branch 3 times, most recently from dbe011d to e51b001 Compare March 24, 2026 19:20

fix: update paywall_hits on every gate

847b434

chickenn00dle force-pushed the feat/reader-data/add-engagement-fields branch from e51b001 to 847b434 Compare March 24, 2026 19:23

chickenn00dle requested a review from Copilot March 24, 2026 19:29

Copilot started reviewing on behalf of chickenn00dle March 24, 2026 19:29 View session

Copilot AI reviewed Mar 24, 2026

View reviewed changes

src/content-gate/gate.js Outdated Show resolved Hide resolved

src/reader-activation/mocks/ras.js Show resolved Hide resolved

src/reader-activation/mocks/ras.js Show resolved Hide resolved

src/reader-activation/article-view.test.js Show resolved Hide resolved

fix: reinstate gtag check

21c456e

chickenn00dle commented Mar 24, 2026

View reviewed changes

chickenn00dle added the [Status] Needs Review The issue or pull request needs to be reviewed label Mar 24, 2026

chickenn00dle commented Mar 24, 2026

View reviewed changes

leogermani requested a review from miguelpeixe March 31, 2026 19:47

miguelpeixe requested changes Mar 31, 2026

View reviewed changes

github-actions bot added the [Status] Needs Changes or Feedback The issue or pull request needs action from the original creator label Mar 31, 2026

fix: always use oldest first visit date

4a7f352

chickenn00dle mentioned this pull request Apr 2, 2026

fix: update favorite categories matching Automattic/newspack-popups#1542

Merged

6 tasks

chickenn00dle requested a review from miguelpeixe April 2, 2026 15:20

chickenn00dle removed the [Status] Needs Changes or Feedback The issue or pull request needs action from the original creator label Apr 2, 2026

fix: only count categories with 2 or more views

68296d0

miguelpeixe approved these changes Apr 2, 2026

View reviewed changes

github-actions bot added [Status] Approved The pull request has been reviewed and is ready to merge and removed [Status] Needs Review The issue or pull request needs to be reviewed labels Apr 2, 2026

chickenn00dle merged commit 1cba4ef into trunk Apr 2, 2026
11 checks passed

chickenn00dle deleted the feat/reader-data/add-engagement-fields branch April 2, 2026 19:44

github-actions bot added the needs-changelog label Apr 2, 2026

chickenn00dle removed the needs-changelog label Apr 2, 2026

	// Do not overwrite items that were pending sync.
	if ( unsynced.includes( key ) ) {
	continue;
	}

Conversation

chickenn00dle commented Mar 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

All Submissions:

Changes proposed in this Pull Request:

How to test the changes in this Pull Request:

Other information:

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

miguelpeixe left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

github-actions bot commented Apr 2, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

chickenn00dle commented Mar 24, 2026 •

edited

Loading