Objectiv lets you model raw analytics data straight out of the box. This is partly enabled by early data validation against the open analytics taxonomy (also making instrumentation unambiguous and future-proof), and partly by helping developers set up tracking instrumentation with helpful tooling.
In this release we focused on the second part: we added links to relevant documentation pages in the Tracker SDK's Validation messages, to help you debug your tracking instrumentation.
How does it work?
We already support basic tracking validation in your IDE, the backend Collector, and the Tracker itself. Read more on that here.
Now, we've split that up into a separate package called Objectiv developer-tools. This
new package extends the Validation messages you see in the browser console, to provide links to contextually
relevant documentation pages.
For example, if a required Context is missing for an Event, the Validation message will now provide a link to that Context’s documentation, as well as any links to related pages. The pages describe the intended use, and provide troubleshooting.
And as an added benefit, you don’t have to include the new developer-tools package in
your production apps, reducing build size.
Examples
Missing RootLocationContext
The Tracker instance of the website has been configured to not track RootLocationContexts from URLs, but no alternative has been implemented to generate those. Since RootLocationContext is required by the open taxonomy, this will result in the validation reporting the issue:
Note how the validation rules detected the platform we are running in and attached links to the documentation for React aimed at solving this particular type of validation error.
Duplicated ApplicationContext
The second example simulates a low-level instrumentation gone wrong. The test button attempts to generate a custom ApplicationContext, but the Tracker has not been prevented from generating those automatically. Since ApplicationContext should only be present once in the list of Global Contexts, the validation reports the issue:
In this example we currently don't have any specific how-to links, but as we add more and more how-to's to our documentation we may introduce them later on.
These examples are non-exhaustive; several other validation rules have been added as well, such as Location Contexts that are in the wrong position in the stack.
The backend Collector also performs much of this validation as a failsafe, such as requiring a RootLocationContext and PathContext for InteractiveEvents.
How to get it
The new developer-tools package is available as a developer dependency for all SDKs. How
to import it depends on your application’s requirements (as an example,
see several options for React here), e.g. with conditional logic based on the
environment:
if (process.env.NODE_ENV.startsWith('dev')) {
require('@objectiv/developer-tools');
}
That’s it! The package will self-inject globally when loaded, and logging & validation will be enabled.
To just upgrade the tracker to the latest version, follow instructions for your platform.
We also introduced a few changes that may need some migration for some users; please double-check these PRs:
What’s next?
This is a new step in helping you set up instrumentation, and we’ll be making more miles:
- We’ll improve on the range of Validation messages. For example, you’ll see messages for redundant tracking of Contexts or duplicate Contexts on one or more screens.
- We’ll enable CI integration of end-to-end testing, such as checking for collisions on any
screen. As a first step towards this, we’ve exposed a Global variable
globalThis.objectiv. Stay tuned! - We’re looking into providing a Chrome plugin that can highlight any tracking issues where they originate in the UI.
Enjoy the new helpful messages, and please do give us your feedback, especially on what you think we should cover with Validation.
Join us on SlackRelease Office Hours
If you have any questions about this release or anything else, or if you just want to say 'Hi!' to team Objectiv, we have Release Office Hours every Thursday at 4pm CET, 10am EST that you can freely dial in to. If you're in a timezone that doesn’t fit well, just ping us on Slack and we'll send over an invite for a better moment.