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" |
|
| 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).