Important

This article relates to both journy.io's SDKs and Twilio Segment SDKs.

Topics

1 Important
2 Intoduction
3 Data tracking philosophy
4 Identifying users and accounts, before tracking screens and events
5 Formalize and normalize your naming standards
- 5.1 Normalizing screen names
- 5.2 Normalizing track event names and metadata

Intoduction

Navigating the process of determining which events to track in journy.io may seem daunting at first. However, rest assured that journy.io has aided countless customers in this endeavour and has compiled a wealth of resources to guide you through the initial steps. Whether you are a fledgling startup or a sprawling enterprise with a multitude of stakeholders, this article will help you get an idea on how to best collect platform data.

Data tracking philosophy

At its essence, tracking centers on capturing user/account interactions with your platform—aiming for as many meaningful interactions as possible from a business perspective.

A notable best practice in screen tracking involves incorporating page calls (refer to the spec) on every app screen. Each screen should possess a distinct, normalized screen name derived from the URL. This normalization entails removing personal user IDs and domain names from the URL, ensuring consistency and clarity. For further details on this, please refer to the later sections of this document.

Likewise, when delving into event tracking, it's beneficial to examine the business logic layers within your code. These layers often serve as the central hub for dispatching various activities, such as POSTs and PUTs, or they may correspond to a GraphQL layer. Regardless of the specifics, the guiding principle remains the same: the names assigned to events, which represent your platform's features and actions, should be normalized. This normalization entails excluding user/account IDs and domain names from event names to ensure uniformity across different user accounts. For more in-depth guidance, consult the subsequent sections of this document.

The key advantage of adopting this approach is the seamless integration of new screens and features. There's no need for manual intervention when incorporating these elements. Any new screens and events are automatically transmitted to journy.io and seamlessly integrated into its data catalog.

Naturally, exceptions may arise in your data collection strategy. Some critical screens (e.g., login) and events (e.g., timeouts) may warrant inclusion despite not adhering to the standard API layer calling. For such cases, we recommend maintaining a concise data tracking sheet to document the calls and event metadata, ensuring comprehensive coverage and accuracy.

Identifying users and accounts, before tracking screens and events

Before tracking screens and events, you need to identify users and the accounts they belong to. Through these identify and group calls, you are actually associating reserved and custom properties to user- and account-IDs.

Here is a sample identify call (with analytics.js) for journy.io:

analytics.identify("abc123", // Elon Musk — unique Id from your database
{  firstname: "Elon", 
   lastname: "Musk",
   email: "elon.musk@tesla.com",
   place_of_birth: "South Africa", 
   friends: 42
});

journy.io recommends that you make an identify call:

After a user first registers
After a user logs in
When a user updates their info (for example, they change or add a new address)

Now the user is identified, add them to associated accounts:

analytics.group("xyz789", // Tesla — unique Id from your database
{  name: "Tesla Inc", 
   industry: "Automotive" 
}, 
{  relationship: 
   {  role: "admin" 
   } 
} 
);

analytics.group("uvw456", // SpaceX — unique Id from your database
{  name: "SpaceX Inc", 
   industry: "Aerospace" 
}, 
{  relationship: 
   {  role: "owner"
   } 
} 
);

journy.io recommends that you make a group call:

After a user first registers, entering its company details.
After a user logs in. Make a group call for each account the user is part of.
When a user updates their info, make a group call for each account the user is part of.

The utmost significance lies in journy.io's ability to comprehend the context of a user identified as 'abc123' ('Elon Musk') who is associated with two distinct accounts bearing the IDs 'xyz789' ('Tesla Inc') and 'uvw456' ('SpaceX Inc').

Without knowledge of the relationship between a user and account, journy.io will NOT track any event, nor screen on account level, even when including it in the call!

Given that a user looks at screens and trigger events when in function of a certain account —logged into a certain account— all further tracking will happen on both user and account level.

The page call for Elon Musk looking at the Dashboard screen when logged into the Tesla account will look like:

analytics.page("/dashboard/", {}, { groupId: "xyz789" });

while when logged into the SpaceX account, it will look like:

This is similarly true for events, when executing the track call. In Tesla:

while when logged into the SpaceX account, it will look like:

Formalize and normalize your naming standards

With your tracking strategy in place, it's time to establish a set of naming standards that your team will adhere to when deciding to track screens and events. While most organizations embrace the "track more, analyze later" stance, some are more leaning towards a "less is more" approach to data tracking. Both approaches come with their advantages and disadvantages, which you should consider in light of your company's specific needs.

Regardless of your chosen approach, keep the following tips in mind:

Adopt a consistent casing convention, such as Title Case for event names and snake_case for property names. Enforce this standard consistently across your events and properties.
Do not create screens or events with dynamic names that incorporate changing values (e.g., Screen: "/v55kaq4g/articles/articles/article-contents/8389378/edit").
Refrain from using events to track properties; instead, assign values to properties and forward those to journy.io through an identify or group call. (e.g. Do not send "Trial Expired" event, but provide us a consistently updates property 'status' = 'trial expired').
Steer clear of generating property keys dynamically, as names like "feature_1":"true" or "feature_2":"false" are ambiguous and challenging to analyze.

By adhering to these principles, you can streamline your data tracking efforts and facilitate more effective analysis in the long run.

Normalizing screen names

As mentioned in the journy.io specs, the difference between a screen and a page is the fact that you are providing a name to the page. As such, a screen is a named page.

journy.io recommends that you:

Make a page call on each screen of your app!
Derive screen name from the page URL.
Use RegExp functionality to change URL dynamic parts into fix parts.

Imagine you have a screen with URL:

where xyz789 is the account ID, and 8389378 is the current article ID current user is editing. If the screen name would be set to its URL, you would be tracking separate screens for separate users/accounts.

Instead, through RegExp, you would first change the name into:

...and pass it along the page call:

Normalizing track event names and metadata

As mentioned in the journy.io specs, events are actions that have been preformed by your users, specific to your software. If you're an accounting app, events would certainly include "Invoice Created", "Invoice Sent", "Credit Note Created" etc....

journy.io recommends that you:

Make a track call on each call in the business logic layer, where POSTs and PUTs are being dispatched. This could be in the GraphQL layer.
Derive event name from the POST/PUT/GraphQL names/URLs.
Use RegExp functionality to change URLs dynamic parts into fix parts.

Imagine you have a POST with URL:

where xyz789 is the account ID, and 8389378 is the invoice ID current user has created. If the event name would be set to its URL, you would be tracking separate screens for separate users/accounts.