Events and Contexts

Your code needs modifications to log events and contexts. These can be thought of as having a parent relationship.

• User = User-level data.
• (Page) View = Logged for a page view, screen view, or activity view. This includes session information.
• Request = A request for a list of content. Views can have multiple Requests on it. For example, related items, search suggested items, users who bought X also bought Y.
• Insertion = An item in a Request’s list response. These might not get viewed (Impression) by the user.
• Impression = When an item is viewed on a screen long enough to count as an impression. E.g., >50% visible for >1s.
• Action = Action taken by a user. For example, when an item is clicked on.

Logging Flow

Here is an example logging flow:

Some details:

• Depending on your use case, your logging flow might be different. You might log Users or Views from the client.
• For web client instrumentation, Promoted reuses the Snowplow JavaScript Tracker with custom schemas. The Snowplow Tracker has useful features like batching events and saving events to local storage. Promoted hosts a web endpoint that accepts the Snowplow HTTP format.
• For server-side events, we recommend calling our Promoted Metrics API directly since the spec is easier and Promoted provides an SDK.

Integration Advice

• Implement the code so you can incrementally push small commits. For example, in one commit, log a simple user object. In a different commit, add more user fields.
• Wrap the logging code in a boolean to keep logging off in production until you are ready.
• We currently require explicit ID contexts and events. For example, when an Insertion is logged, we need to log a Request ID with it. Most of these IDs are generated in your code base to simplify the data transfer.
• Our helper libraries (the Snowplow JavaScript tracker and our logging libraries) are designed to work in a single environment (either browser-side or server-side). If you have code that can conditionally run on both client-side and server-side, you will need different logging code for each case.