The JDX Function is the heart of the pixel. It allows you to control when, what, and how things are sent to our system. There function is divided into four separate types of uses:
- Track: Sends a request to our system
- Config: Sets up the pixel configurations for every request that follows
- Options: Sets the options on the next request made and will be reset following its completion
- Metadata: Sets the metadata key and values for the next request
The jdxtag() function’s first argument is the action it will take and is followed by any required or optional parameters needed for that action:
jdxtag(<ACTION>, <PARAMETERS>)
The type of actions available for the JDX Function are:
track, options, metadata, and config. See the details for each action below for the specific parameters required.Ensure that when using the
jdxtag() function on an HTML page you have it wrapped in a <script> tag or no action will be made.Track
By making a request it allows you to report metrics into our system so we can keep track of how jobs are performing for you. These numbers can used for publisher payments as well as figuring out how to plan your campaigns.
The Track request accepts an object of options as a second parameter. The possible options are laid out in the table below:
Track Parameters
| Option | Description |
|---|---|
| jobId | This is the job's unique identifier. This identifier is the one we imported from your system so it should align with the one you are using on your website. This identifier is also available when we redirect a user. We include it under the query parameter jdx_jid. |
| clickId | For every user we redirect to your website we generate a click id for them. This value is sent to you on redirect under the query parameter jdx_click. If you can, save this value and send it when you make a conversion or track request. Sending this value is the best way to ensure accuracy of the data |
| conversion | A boolean variable to set the next track request to report a conversion (when set to true) or a regular track request (when set to false) |
| referrerUrl | The URL of the website that referred the user |
| currentUrl | The current URL the user is on |
| ignoreParams | List of browser parameters that you would not like to send to our system (see Options section for more details) |
The pixel can automatically figure out what the click identifier and job identifier for a job is in some cases but it is always better to set these values yourself manually so that any edge cases where the pixel cannot find the correct values are avoided and reporting data integrity is maintained.
Examples
// Set request options when sending request
jdxtag('track', { clickId: '{{CLICK_ID}}', jobId: '{{JOB_ID}}', conversion: {{CONVERSION_BOOLEAN}} })
// Set request options separately
jdxtag('option', 'clickId', '{{CLICK_ID}}')
jdxtag('option', 'jobId', '{{JOB_ID}}')
jdxtag('option', 'conversion', {{CONVERSION_BOOLEAN}})
jdxtag('track')
Config
Our pixel maintains a global config that persists for every request you make on a page. Typically you’ll set Config variables in the <head> tag (see the Head Snippet section for an example of config usage) so that any requests made from the tag on the page will include your config changes. However, you can update the config from anywhere, just note that jdxtag() function calls happen in order so any config changes applied only alter subsequent requests.
The Config action takes a variable name as the second parameter and a third parameter with the value you want to set that variable to. Depending on the variable, there may be additional parameters. Refer to the documentation on specific config variables for proper usage.
Config actions include:
- Set Pixel
- Pixel Time Zone
- Do Not Track
Set Pixel
This config action is mandatory and must be set before making any requests. This variable accepts a string value which is your pixel’s UUID. To find the UUID our system has assigned to your account please visit the platform, log into your dashboard, and visit the account’s pixel page.
jdxtag('config', '_setPixel', 'bdc609ea-9675-402f-ac5d-130ce1bfc4a5')
Pixel Time Zone
This config action is mandatory and must be set before making any requests. This variable accepts a string value which is the timezone you specified when you created your account. To see what this variable is for your account please visit the platform, log into your dashboard, and visit the account’s pixel page.
jdxtag('config', '_pixelTimeZone', 'EST')
Do Not Track
If you allow users to opt out of being tracked you can set their decision by passing a boolean value to the Do Not Track action. If set to true then requests will not be sent to our system. In order to stay flexible we’ve left how you keep track of a user’s Do Not Track status up to you. Just make sure whenever they go to a new page the status is re-affirmed.
jdxtag('config', '_doNotTrack', true)
If you want requests to be sent but you do not want to send user data, please use the Ignore Params action to turn off what is being tracked on your users.
Options
When making requests there are times where you want to make adjustments on how the data is being sent to our system. We provide various Option actions to give you flexibility. Note that unlike Config actions, these actions do not persist between requests. If you want to make multiple requests with the same options you’ll need to re-apply them before each request is made.
Option actions include:
- Current URL
- Referrer URL
- Ignore Params
- Job Identifier
- Click Identifier
- Conversion Boolean
Current URL
This action allows you to override the browsers current URL. Some practical uses of this option could be:
- That you have sensitive URL parameters that you don’t want sent to us
- Your website is a Single Page App (React, Angular, etc) and it doesn’t update the browser’s internal URL
- Your website uses AJAX and/or modals and you want distinct URLs and/or parameters sent to our system
- You want to set identifiers for the job/click separately from the tracking request
This option accepts a string which you can enter the URL of the current page the user is visiting.
jdxtag('option', 'currentUrl', 'http://www.your-website.com/route/page')
Referrer URL
If you need to override the referrer URL because the one stored in the browser is not accurate you can use the Referrer URL action. This is especially important for Single Page Apps (React, Angular, etc) that do not update the referrer URL at all. If you want to accurately track how users are navigating your website you will need to make sure the referrer URL being passed to our system is correct.
jdxtag('option', 'referrerUrl', 'http://www.your-website.com/route/referrer-page')
Ignore Params
Our pixel tracks various user attributes we get from the browser. This is useful for tracking user behaviour. However, there may be instances where you do not want certain data tracked on your user. To have the pixel ignore certain browser attributes use the Ignore Params action and pass an array of attributes (as strings) that you want ignored.
jdxtag('option', 'ignoreParams', ['userAgent', 'browser'])
Optimize Pixel Ignore Params
| Param | Description | Example |
|---|---|---|
| userAgent | The specific browser with version being used by a user | Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:88.0) Gecko/20100101 Firefox/88.0 |
| browser | The browser of the user | Chrome |
| mobile | A boolean value as to whether they are on mobile | TRUE |
| screenSize | A width by height string value of the browserâs screen size in pixels | 1600x900 |
| color | An integer with the color depth on the userâs browser | 24 |
| referrer | The URL that the user came from before the current page | http://www.website.com/route/page |
| encoding | The character set on the user's browser | UTF-8 |
| language | The native language set on the user's browser | en-US |
| location | The current URL that the user is on | http://www.website.com/route/page |
| timezone | The timezone that the user's browser is in | America/New York |
Note that if you want to add multiple ignore params you must add them all at once. Any additional calls of the Ignore Params action will overwrite the previous values:
Problematic:
jdxtag('option', 'ignoreParams', ['language', 'color'])
jdxtag('option', 'ignoreParams', ['timezone'])
// Now only timezone will be ignored, the language and color will still be present in the request!
jdxtag('track')
Good:
jdxtag('option', 'ignoreParams', ['language', 'color', 'timezone'])
// Now all three parameters will be ignored in the request!
jdxtag('track')
Job Identifier
This action allows you to set the job identifier for the subsequent track request. The job’s identifier should reference the one originating from your system. Sending this value helps us more accurately report tracking data to you. Our pixel has the ability to get the job identifier from the query parameters and/or the user’s session automatically but it is not perfect so providing it yourself is always preferable. This is especially true when you want to track organic traffic since the pixel is setup to only look for identifiers sent by our system. If you do not have access to the job identifier locally, you can always get it from the query parameter jdx_jid which we send on redirect. Note that this will only apply to users sent by us and users from any other source will need the job identifier set using a local value.
jdxtag('option', 'jobId', 'jid-13947-uf82jf')
Click Identifier
This action allows you to set the click identifier for the next track request. The click identifier is generated by our system and passed as a query parameter when we redirect the user to your website under the name jdx_click. Passing this value allows our system to more accurately report tracking data to you on your dashboard as we can make a direct connection between the user we sent and their actions on your site.
jdxtag('option', 'clickId', '3219f8c4-a543-4858-8e07-15d0a0e4fa98')
Conversion Boolean
Setting the conversion boolean to true tells our pixel to mark the next track request as a conversion. If a track request is made without setting this variable (or it’s not set to true) then it will treat the subsequent request as a regular track request and NOT as a conversion.
jdxtag('option', 'conversion', true)
Multiple Options Object
If you have multiple options you would like to set you can do so by pluralizing option to options and passing an object as the second parameter. Inside the object you can set each option outlined in this section:
jdxtag('options', { ignoreParams: ['language'], jobId: 'jid-123', referrerUrl: 'http://refurl.com' })
Metadata
If you need additional information attached to a request so you can better understand or organize your data, you can use the Metadata action. When using this action you also must include a key and a value which will be stored by Optimize. Note that the key and the value must both be of type String and the key must only include alphanumeric characters (_ and – also allowed as separators) in order to be valid:
jdxtag('metadata', 'a_key-example', 'A string value')
There is a maximum of 5 metadata parameters allowed per request, and you must make sure to run the metadata functions before you run the desired request:
// Set metadata
jdxtag('metadata', 'job-type', 'Sales')
jdxtag('metadata', 'company', 'Widget Corp')
// Then send request!
jdxtag('track')