Decide how to proceed with the Page view event/instrumentation

[martinkuba]

The purpose of this issue is to come to a decision on what a page view event should represent, and how it should be implemented.

Work in progress:

• PR to add page view semantic conventions
• PR to add page view instrumentation

Definitions

Navigation:
Action that changes the current history entry. This includes loading a new document, changing URL fragment, going back/forward, reloading, changing the URL programmatically

Hard navigation / page load:
HTML document is loaded in the browser

Soft navigation:
An event that appears to the user as a page load, but does not involve loading a new HTML document - URL is changed without loading a new HTML document, DOM is updated programmatically. The main use case is route changes in SPA applications.

Page view:
TBD

Use cases

There are a few use cases that we are trying to address:

1. Provide an event that can be used to reliably capture count of page loads (hard navigations).
   Hard navigations result in many events (e.g. window load, navigation-timing, FCP, LCP) that could also be used for this but are less reliable. Sending an event as soon as the SDK is initialized would guarantee that the page load is counted. In this case, page view is simply synonymous with page load.

2. Automatically capture events that represent route changes in SPA applications.
   These are also referred to as soft navigations, and to users they appear the same as page loads - URL changes and content of the page changes.

3. Capture all URL changes including ones in the same document
   This essentially means capturing all navigation events. Not all URL changes represent a logical page view, but this would give us comprehensive data about navigation/history.

4. Capture events that represent views of a section of the application.
   Examples include displaying a dialog, displaying specific content in a sub-section of a page, or perhaps changing the whole page content without changing the URL. This definition of a view does not couple the page content with the URL, and it would likely need to be captured using an API (since it is not possible to automatically determine what change in DOM represents a page view).

5. Capture events that represent multiple related pages.
   This is related to the previous use case with the distinction that multiple pages can be combined into a single view. For example, a user view could include user list page and user profile page.

Questions

What should the page view event represent? Should it represent hard navigation only? Should it also represent SPA route changes (soft navigation)? Should it represent a logical page view that may or may not involve URL change? Should we even use this term if it is not clear/self-explanatory?

Do we need instrumentation solely for the purpose of counting page loads?

Should we capture SPA soft navigations as page view events or soft navigation events?

Comments

The original intent of the event as proposed in open-telemetry/semantic-conventions#1910 was to cover use cases 1 and 2.

However, we do not have consensus on how to capture soft navigations. Should we follow the ongoing experimental work to standardize soft navigations? Or, should we simply capture all same-document navigation events as "virtual" page views? In other words, we do not have consensus on what a virtual page view is.

In addition, use cases 4 and 5 provide yet another definition of a page view. Here it represents more of a logical page view that may or may not be tied to a specific URL or URL change.

[martinkuba]

Here is one possible solution:

• define/capture a navigation event

Instead of calling the event page view, we could capture all navigation events. This would satisfy use cases 1 and 3. If an analytics tool considered any programmatic URL change a SPA soft navigation, then it would satisfy use case 2 as well.

Instrumentation: the Navigation API "navigate" event provides this information. However, it is not available in Safari and Firefox, so additional instrumentation of the history/navigation APIs would be needed.

• define/capture a soft-navigation event

This is specifically intended to capture SPA soft navigations that involve user action, URL change, and DOM change. Semantic conventions and instrumentation would be experimental (and purposefully separate) since the concept is still being defined in the industry. This would satisfy use case 2.

• define page view or view semantic conventions

These would be intended to capture logical views of the application. There would likely be no auto-instrumentation, but we could provide APIs for users to call.

[joaquin-diaz]

What should the page view event represent? Should it represent hard navigation only? Should it also represent SPA route changes (soft navigation)? Should it represent a logical page view that may or may not involve URL change? Should we even use this term if it is not clear/self-explanatory?

I think it should represent the fact that the user is viewing a new page in their browser. As we discussed a "new page" might mean a lot of things depending on each use case; i.e. all the content in the browser changed, a new modal opened, the next step of a wizard, etc. An attribute can define whether is a hard or soft navigation.

In my opinion we should only focus on defining this event and later create multiple optional instrumentation that users can use depending on their understanding of a new page. For example:

• Instrumentation that creates a page_view when the page loads from zero.
• Instrumentation that creates a page_view on URL change
• Instrumentation that hooks into react router library XYZ and creates a page_view on navigation

In addition, users can emit page_view event whenever their needs don't fit into any of the auto-instrumentation we provide. We could wrap this in a public API to make it easier and consistent.

I don't think is a bad idea to also create more events tied to discrete browser events, like URL changes or the navigation API. The user can later analyze these however they need.

[david-luna]

It seems we are reaching a consensus :)
IIUC

• loading a document is navigation and page_view
• modifying the URL is navigation but not necessarily a page_view
• so in the scenario of showing showing modals (commented on the SIG):
  • with no URL change may be a page_view but not a navigation
  • with URL change may be a page_view and its a navigation

I don't fully get the soft-navigation event. Could navigation type property be enough to model that?

Regarding implementations I share @joaquin-diaz idea of different instrumentations creating the same event. This way I think we can implement instrumentations in a way they are not overlapping when patching browser APIs

[martinkuba]

@david-luna

loading a document is navigation and page_view

Yes, but it is not clear if they would represent the same thing. If we define page_view as the moment the user actually sees meaningful content rather than just when the document starts loading, then page_view would naturally occur after navigation. The exact point could be FCP, LCP, or the window load event.

I don't fully get the soft-navigation event. Could navigation type property be enough to model that?

This needs to be defined. I proposed soft-navigation since that's the name the experimental feature in Chrome is using as the performance entry type. But I think it could also make sense to capture it as a page_view event, or annotate the navigation event with additional attribute(s).

[vigneshshanmugam]

Navigation is a loaded term. In the browser world it refers to a document load and URL change, which makes sense at the rendering layer. A page view, on the other hand, is a user-centric activity which represents the moment the user perceives a new page or screen, which may or may not be triggered by a browser navigation.

Every browser navigation should map to a page view, but not all page views require a full navigation (for example, SPA route changes). If we tie page view strictly to performance milestones like FCP or LCP, we run the risk of losing data if the SDK fails to collect those metrics or user exiting the page before these events are triggered.

Page view should basically follow navigation: whenever a navigation or route change occurs, a page view should be recorded. Performance metrics like FCP, LCP, or load timing can then be attached as supplemental data, rather than gating whether the page view fires.

[martinkuba]

@vigneshshanmugam

Navigation is a loaded term. In the browser world it refers to a document load and URL change...

I think the definition of navigation has broadened. The W3C Navigation API emits "navigate" entries for any URL change, not just document loads.

If we tie page view strictly to performance milestones like FCP or LCP, we run the risk of losing data...

I agree that page_view should not be tied to FCP or LCP if the goal is to reliably record page loads.

Page view is a user-centric activity which represents the moment the user perceives a new page or screen. ... Page view should basically follow navigation: whenever a navigation or route change occurs, a page view should be recorded.

Your description of page_view seems to align with the traditional interpretation: it fires for either a page load or a SPA route change.

That said, we've discussed a few nuances:

• Some see value in firing a page view even without a URL change if the user perceives a new screen.
• If the user abandons the page before anything is displayed (long load, hidden tab), would this count as a page view if the definition is “the moment the user perceives a new page”?
• Not every route change represents a meaningful page view, so it might be useful to distinguish same-document navigations from actual page views.

If we introduce a navigation event, we:

• Cover page loads consistently — this event happens before any timing events like FCP/LCP.
• Leverage a browser-generated, unambiguous event instead of inventing heuristics.
• Capture generic route changes without instrumenting every framework router.

My thinking is:

• Start with a navigation event since it’s straightforward and aligns with the spec.
• Add a page_view event later if we want a user-centric signal with more complex semantics (e.g., “perceived screen change”).

[vigneshshanmugam]

I think the definition of navigation has broadened. The W3C Navigation API emits "navigate" entries for any URL change, not just document loads.

Thanks for the context, I haven't been following actively lately. Makes sense.

I agree with most of your take and we should follow the browser navigation event pretty closely as it aligns with the spec and its easier to reason about 💯

However, page_view is something that comes after that and user perceived - Seems like we both are in agreement here. I was trying to convey that the spec should either be opinionated and consider both Navigation and Non navigation event as you mentioned as page views as helps capture user activity in some way or we are flexible and provide multiple choke points that can dictate the page views (visibility change != hidden, FCP, LCP, or custom Event timing events).