Strategy for adding custom site wide tracking functionality to n-tracking

[ifeanyiisitor]

One of the issues that were raised during discussions with various developers, is the need to be able to add / initialise new tracking functionality within n-tracking in a manner that does not result in spaghetti code. We see this as a valid concern because it not being formally addressed within the n-ui tracking implementation has resulted in its implementation becoming bloated and thus, harder to maintain.

While we plan to not initialise app specific tracking functionality within n-tracking, we have accepted that tracking functionality of a site wide nature, should probably be initialised within n-tracking so as to ensure that the responsibility of initialising them don’t fall to app developers (which is especially important when new apps are created). This means that over time, the n-tracking codebase will grow as developers contribute custom site wide specific tracking functionality to it, thus putting n-tracking in the same predicament where this issue is concerned.

Within the current n-ui tracking implementation, there seems to be two primary ways in which custom site wide tracking functionality is added. The first is by encapsulating the functionality within a module that resides in its own file, and then initialising that module within another module (also residing in its own file) whose responsibility it is to initialise custom site wide tracking functionality. The core tracking functionality then imports the initialisation functionality of the latter module and executes it. See the following links:

• https://github.com/Financial-Times/n-ui/blob/master/components/n-ui/tracking/ft/index.js#L185

• https://github.com/Financial-Times/n-ui/blob/18330fa2d95d041cf00b171cbcbdfed4023c05c4/components/n-ui/tracking/ft/next-events.js

Note that with the term ‘core tracking functionality’ I'm referring to the functionality whose only responsibility is to initialise o-tracking with the minimum non app specific tracking context.

Not only does this pattern do well to ensure that the code that defines the core tracking functionality does not get touched when adding custom functionality, it also adds a strong convention that allows for easily identifying what is being tracked on ft.com. For these reasons, this pattern is one that will probably be carried over to n-tracking

The second way of adding custom functionality, however, involves having to add code to the core tracking functionality, and this has indeed resulted in the somewhat spaghetti nature of the core tracking code within n-ui. It seems that the reason why those specific pieces of custom functionality needed to be added to the core tracking implementation, is because they reference context that has been specified in the core tracking implementation. Context that is not accessible outside of the module / function that implements the core tracking functionality.

Note that with the word ‘context’, I’m referring to the context object that is supplied to the o-tracking initialisation function.

So to ensure that this problem is not carried over to n-tracking, we can separate the concern of creating the context from that of initialising o-tracking with that context, so that custom tracking functionality that needs to reference the core context, will be able to do so from outside the scope of the core tracking functionality. This would leave the core tracking functionality to be nothing more than the absolute core tracking functionality.

But there is always a chance that a developer, in not understanding or being aware of the codebase specific intentions, may end up littering the core tracking code with code that implements custom tracking functionality. The following may help to mitigate this issue:

• Document within a 'Contribution Guidelines' document, the pattern for adding custom site wide tracking functionality

• Document within a 'Contribution Guidelines' document, the pattern for referencing the core tracking context within custom tracking functionality

• Document within a 'Contribution Guidelines' document, the general pattern around separating concerns with the aim of ensuring that responsibilities at a module / component / functional level remains single

• Add a clear 'Do Not Touch' comment at the top of the file that houses the core tracking functionality. This comment would be brief while pointing the developer to the contribution guideline.

• Institute a pull request template that features a contribution checklist covering the requirements around adding custom tracking functionality.

• Constantly be on the lookout for opportunities to establish coding conventions that are easily identified (without having to read docs) and that help developers to do the best / intended thing.

Any thoughts?