Skip to content

Viewthrough tracking

The viewthrough-tracking endpoint can be used to track views on content. This includes, but is not limited to:

  • Ads
  • Emails
  • External Webpages

The viewthrough-tracker provides a configuration to track a variety of views on all sorts of content in a flexible manner.

Paths

The viewthrough-tracking endpoint provides a two paths to use for tracking, as follows:

Path Variables Variable Info Description
/ N/A N/A The default endpoint, simple pixel-drop on client
/nr N/A N/A The default endpoint, but returns HTTP 204 (Empty Response)

Usage

The viewthrough-tracking endpoint supports a variety of variables that can be used to add depth and clarity to the events at hand.

URL Parameters

The table below shows all parameters that can be set through the endpoint's query-string:

Variable Value Required? Description Example
oa_aid number yes Your Orbee Account ID 1
oa_vpid number yes Your Orbee Identifier Pool ID 1
oa_vtid string yes Your Viewthrough Tracking ID (yours if oa_vpid != 1, Orbee's if oa_vpid = 1) 1
oa_campaign string no Provides a readable name you want for the campaign My+Test+Campaign
oa_vt string no The view-type of the view, defaults to "email" email
oa_uid string no unique user ID for the viewer; usually unique per viewer abc123
oa_subid string no Unique ID to categorize the view into a group 213
oa_emid string no [EMAIL ONLY] Unique ID for the email the recipient received when applicable email123
oa_track boolean no whether or not to track the event (default: true) false
oa_nr boolean no if true, a 204 (no response) is returned. True by default false

Server-side settings

Coming Soon

Set your server-side settings soon on the Orbee Marketing Platform!

On the server, the endpoint provides settings that can be written at the account and viewthrough-tracker levels. The table below details these parameters:

Variable Value Required? Description Example
Parameters list of Parameters no If provided, you can list a set of query-string k/v pairs to add to the pixel's tracking event. Each k/v pair also has an override flag, for whether or not you want to override any given value with the server value. {key: oa_campaign, value: my_amazing_email, override: true}

Best Practices

Implications of using the viewthrough-tracker come with some rules to abide by. The list below covers most pain-points there are when using the viewthrough-tracker.

Encode all parameters

When using the viewthrough-tracker, all parameters must be encoded. The viewthrough-tracker will recover from many cases, but cannot handle all of them. The safest way to use the viewthrough-tracker is to make sure all URL parameters are encoded. A popular and easy-to-use encoder that can show you what this means is available here.

Check ID's against the Platform

It can be easy to get your IDs wrong in the URL. Be sure to check the IDs against Orbee's to make sure they match. The oa_vtid parameter can be whatever you want if you've got a viewthrough-tracker pool ID (the oa_vpid param) from Orbee's Marketing Platform.

Use oa-track=false to exclude clicks from reporting

oa_track can be set to false for views you want to keep away from your general reporting in the Platform. The event is still captured and can be debugged. Use this for audit emails and ads and other test scenarios.

Provide oa_subid whenever possible

oa_subid can be used to tie data to an action from your product or vendor. Utilizing this ID will make integrations far easier to implement.


How it works

The viewthrough-tracking endpoint is actually very simple -- it takes events from a variety of sources and queues the event into our back end.

1. View ID

The first thing the endpoint does is generate a view ID. This ID is stored with the tracking event.

2. Input + Rules = Tracking Event

Given the input, plus the server-side information for the viewthrough-tracker, the endpoint will generate the tracking event. This will take into account server-side configuration like additional/override parameters and more.

3. Tracking

Before the endpoint returns the pixel, it tracks the view event by queueing up the event into our back end. This is done asynchronously while generating and returning the response.

4. Browser-side

Since we return an invisible pixel, the pixel is rendered (unless oa_nr=true is set).


Last update: 2023-04-13