Skip to content

Click tracking

The click-tracking endpoint can be used to track clicks on off-site content. This includes, but is not limited to:

  • Ads
  • Email
  • Video
  • External Links

The click tracker provides a few endpoints and configuration variables to offer you a flexible interface for tracking clicks.

Paths

The click-tracking endpoint provides a few different paths depending on the implementation you want to use. They are as follows:

Path Variables Variable Info Description
/ N/A N/A The default endpoint, server-side redirect implementation
/tp/{p} p provider The third-party click-tracking integration. The provider is the third-party being used -- e.g. goog for Google Ads
/js N/A N/A The document.location.href redirect implementation
/psv N/A N/A The passive-tracking implementation (no redirect, fired in parallel)

Usage

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

Do note that the "required" variables below are required for tracking; however for the click-tracking to work functionally, a destination url (oa_dest) is all that's required.

Hash-Query Order

hash (#) / query (?) order in the URL works in either order, so we provide the option to specify it yourself. By default, we will always adhere to the W3C specification.

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_cpid number yes Your Orbee Identifier Pool ID 1
oa_ctid string yes Your Click Tracking ID (yours if oa_cpid != 1, Orbee's if oa_cpid = 1) 1
oa_campaign string no Provides a readable name you want for the campaign My+Test+Campaign
oa_lid string no Your Orbee Link ID (autogenerated links) 123
oa_dest string yes The destination URL, encoded https%3A%2F%2Forbeeauto.com
oa_referrer string no If multiple click-trackers, you can provide the original referrer https%3A%2F%2Forbeeauto.com
oa_uid string no unique user ID for the recipient; usually unique per email address abc123
oa_hqo boolean no specify the hash/query order for the destination URL (default: W3C standard) false
oa_subid string no Unique ID to categorize the click into a group 213
oa_emid string no Unique ID for the email the recipient recieved email123
oa_clid string no The click ID to use for this click, in the format k=v where k is the query-string key in the destination URL or matching event, and v is the value that query-string key will be set to.

WARNING: DO NOT use this unless you know what you're doing.
gclid=askfhl328y
oa_track boolean no whether or not to track the event (default: true) false
oa_debug boolean no whether or not to display the debug page (default: false) true

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, click-tracker, and link levels. The table below details these parameters:

Variable Value Required? Description Example
Query Param Whitelist list of strings no A list of querystring keys that are whitelisted for the destination URL. If provided, only these querystring parameters will be passed to the destination URL. utm_source
hqo boolean no The hash/query order for the destination URL (default: W3C standard) false
Parameters list of Parameters no If provided, you can list a set of query-string k/v pairs to add to the destination URL. 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: utm_source, value: click-tracker, override: true}
Default URL string no The default URL (useful for clicks that don't set oa_dest) https://orbeeauto.com
Override URL string no When provided, this URL overrides any input for the destination URL, and forces it to its value https://orbeeauto.com

Best Practices

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

Encode all parameters

When using the click tracker, all parameters must be encoded. The click tracker will recover from many cases, but cannot handle all of them. The safest way to use the click 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_ctid parameter can be whatever you want if you've got a click-tracker pool ID (the oa_cpid param) from Orbee's Marketing Platform.

Use oa_debug to debug implementation

oa_debug can be used to enable our debug HTML page when clicking links, which provides very deep insight into the process the click tracker goes through.

Use oa-track=false to exclude clicks from reporting

oa_track can be set to false for clicks 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 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 click-tracking endpoint is a robust rules engine that works on tracking clicks in real-time, while removing performance issues for the process.

1. Click ID

The first thing the endpoint does is generate a click ID. This ID is returned to the destination URL, to connect the landing page with the click that happened.

2. Input + Rules = Response

Given the input, plus the server-side information for the click-tracker, the endpoint will generate the final destination that should be reached. This will take into account server-side configuration like override URLs, default URLs, and more.

If oa_debug is true, it will also generate a debug page response. This page displays the inputs, outputs and logs, as well as a button to reach the destination page.

3. Tracking

Before the endpoint returns a response, it tracks the click event by queueing up the event in our backend. This is done asynchronously while generating and returning the response.

4. Browser-side

After the endpoint returns a response, the browser will handle the click in one of the following ways:

  • The browser will follow the returned server-generated redirect (/, /tp/{p})
  • The browser will display the page, which does a JavaScript rewrite of the URL (/js)
  • The browser does nothing, an empty response was returned (/psv)

Last update: 2023-04-13