How to use Segment Tracking

What is Segment?

Great question, reader! Segment is our event management/tracking platform. It is not the 'Destination' of where we store our events but it is our event tracking pipeline. The 'Source' of events are coming from our applications. You can get more about what Segment is here.

How do I add a Segment tracking to my application?

This doc will go over some implementation details to help with adding Segment tracking to new apps and/or existing apps. The code examples will be for Javascript only (more specifically in Vue) but you can see other language implementations here. Here are some code examples:

Tracking an event in Vue component

Add the import statement at top - I'll show the contents of "services/segment.js" momentarily

import Segment from "services/segment";

Set a category for this component - current convention is to have one category per component for now

const TRACK_BUYOUT_OFFER = "Buyout Offer";

Define a method for each specific event - More on Segment.track in a little bit, I promise ☺️

methods: {
    trackShowBuyoutOffer() {
      Segment.track("pageView", { category: TRACK_BUYOUT_OFFER, label: "Offer Displayed" });
    },
    trackOpenOfferModalFromEmail() {
      Segment.track("pageView", { category: TRACK_BUYOUT_OFFER, label: "Offer Displayed From Email" });
    },
    trackShowOfferUnavailableBanner() {
      Segment.track("pageView", { category: TRACK_BUYOUT_OFFER, label: "Offer Unavailable" });
    },
    trackOnReviewClick() {
      Segment.track("click", { category: TRACK_BUYOUT_OFFER, label: "Review Offer Clicked" });
    },
  },

Key things to note here: Segment.track takes two arguments, the first is the event name and the second is the event properties. There can be different implementations of this function but it's based on the current implementation in the Retail Platform right now. The event properties contain the same category for all, since these are all happening in the same component, and the label represents the desired event behavior we want to track.

And this is an example of when we would call on one of those methods

mounted() {
# do code stuff here

    if (this.showBuyoutOffer) {
        this.trackShowBuyoutOffer();
    }
    
# do more code stuff here
},

Setting up segment.js file

The Retail Platform has the Segment class defined in app/javascript/services/segment.js. It looks sorta kinda like this:

import "segment";

const EVENTS = {
  areYouALender: "Are you a lender",
  pageView: "Page View",
  click: "Click",
};

class Segment {
  static load() {
    if (!window.analytics) { return; }

    window.analytics.load(PSData.global.segmentApiKey);

    if (PSData.user.signedIn === "yes") {
      window.analytics.identify(PSData.user.id, PSData.user.properties, {
        Intercom: {
          user_hash: PSData.user.intercomUserHash,
        },
      });
    }

    window.analytics.page(PSData.page.title);
  }

  static track(event, properties) {
    if (!EVENTS[event]) {
      throw {
        name: "Segement Analytics Error",
        message: "event is not defined",
      };
    }

    window.analytics.track(EVENTS[event], Object.assign({
      user: PSData.user ? PSData.user.id : null,
      event: EVENTS[event],
    }, properties));
  }
}

window.PS.Services.SegmentService = Segment;
export default Segment;

Ok, it actually looks almost exactly like this but I did clean up the EVENTS constant as they don't all need to be in this example. The main events for us to track in the secondary marketplace are pageView and click - although the retail platform has others for more specific use cases.

Breaking down the track function

As you can see from the code snippet above, the track function will first check our list of predefined event names and if it doesn't already exist, we will throw an error because you were being very naughty about trying to track a new type of event without updating the EVENTS constant... After that, we use the window.analytics.track function to send the event name and an Object (which also includes the event name 🤔 ) that has all of the event properties we talked about earlier in this doc. One design implementation to note here:

user: PSData.user ? PSData.user.id : null,

We are currently only tracking events when a user is signed in, but this line of code here gives us flexibility down the road in case we want to track events outside of a user being logged in. This also allows us to not have to mock out a logged in user for all of our test suites - more on that in a bit 😊

Breaking down the load function

TODO

How do I test my Segment tracking implementation?

Whoa, great question again! There are a few things that need to be added to your project before adding the actual spec files.

TODO - enter exact file and code to turn off Segment event tracking in test env

Testing the Segment service

You can see how we implemented the segment service here. Obviously it all depends on how the implementation is set up in your application, but the important thing to note here is that window.analytics.track function is being mocked out. You just need to test for properties/event names based on different scenarios.

How do I get access to Segment?

No formal request process or anything, but access will be granted as a necessary based on Boris Lansky's discretion. So reach out to him if you think you need access.