feat(page-meta): provide options to override automatically created pageId's

[codecapitano]

Why

With this PR we provide a convenient way to the user to change the page-meta.
This is mostly useful to give users and option to provide a custom template for pageID parsing.

If the page-meta contains an id attribute, the Faro receiver will use this ID instead.

API

Page tracking can be configured during initialisation via the Faro options

pageTracking?: {
    page?: MetaPage;
    generatePageId?: (location: Location) => string;
  };

• The page property can be used to set the initial page-meta.
• The generatePageId() function is used to define a template parsers which consistently updates the page id. It is to satisfy advanced use cases

** Explicitly set a the page via the setPage(page: string) function.

setPage is an overloaded function. If the page parameter is of type string, Faro updates the current active page meta with the given page id.

What

• Provide a setPage(meta) function to set/override the page-meta and getPage() function to receiver it.
• Provide an option to define a pageID template parser which is called on every URL change. It receiver the browser Location object as a parameter and is expected to return a string.
• The defaultMetas object is removed and such not exported anymore because pageMeta creation changed. This can break if users used that export for some reasons. It was never meant to be used outside Faro so we decided to remove it anyways.

Links

• Documentation PR

Screenshots

Manually testing the pageId parser using a custom parser which attaches a random id to the pageId URL string.
Jest doesn't play well with manually changing the URLs.
Location isn't updated on the code side

Screen.Recording.2025-01-29.at.13.39.37.mov

Checklist

• Tests added
• Changelog updated
• Documentation updated

[eskirk]

lgtm, one comment about a potential solution to your testing issue

[cedricziel]

The desired API usage would be:

Ad hoc usage:

faro.api.setPage('product-list');

Init usage:

initializeFaro({
  page: {
    id: 'product-list'
  }
});