Click tracking¶
The click-tracking endpoint can be used to track clicks on off-site content. This includes, but is not limited to:
- Ads
- 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)