Go to Qubit

Opentag documentation

Parameters

Parameters in Opentag are a way of passing back values (both static and/or dynamic) to tags.

Overview

Many JavaScript tags require you to pass values to them from the page the user is interacting with. For example, affiliate marketing tags require you to pass the order number and total amount on the confirmation pages; some retargeting products ask websites to pass the product information the user is looking at.

There are a number of different ways of collecting data and passing to your scripts:

  • Using Universal Variable values from the page
  • Hard coding values
  • Custom JavaScript extractors (can use jQuery)
  • Extracting parameter values from the URL
  • Passing cookie values to your script
  • Reading DOM element values

Below you can find more about how to do each one of them below.

Defining where the value needs to be passed

When a script needs a value from the page, or you need to define a portion of a script that requires a variable value, you can do so by declaring a variable.
To declare a token simply use the following convention ${VAR_NAME}

For example, if you have a snippet on the page that expects a value, you can do so like this:

alert("Hello ${NAME}");

${NAME} creates the TOKEN in your script. Now, it is time to pass a value in there. To do so:

  1. Click the “Add Variable” button.
  2. Enter a description
  3. Enter your token name, in this case “NAME” (without the ${})
  4. Then pick where the value needs to come from: Universal Variable, or a new Custom Variable.

The following different methods tell you how you can pass a custom variable value to that token.

Note: If the value you are passing is a number, make sure in your custom HTML it is not wrapped with single or double quotes.
amount = ${var}

and NOT

amount = '${var}'

In the latter case the value you pass will be passed as a string.

Please see this section on tips about how to more effectively JavaScript to pass values to your scripts along with many examples.

opentag-parameter-dropdown

Hard coded value

You should be using Hard Coded values for static values, such as your Google Analytics profile id, or a Doubleclick cat param. Usually these are not directly related to the text rendered in the page.

To implement a hard coded value for a parameter, choose “Hard Coded Value” and enter the value.

Remember, this value will be passed as a string or number based on the encapsulating quotes around the custom value in the script.

For example, if you set ${var} as 5:

amount = ${var}
// amount = 5 (Number)
amount = "${var}"
// amount = "5" (String)

Custom JavaScript

Custom JavaScript extractors are JavaScript snippets (fuctions or variables) that will get evaluated and the value they return will be applied to the custom value expected in your script.

However, if the value it returns is null or undefined, it will keep re-evaluating until it gets a value and then it will continue with execution.

Custom JavaScript is great for your own custom functions you’d like to implement and keep reusing.

Your javascript code should be a format such that it can be the in the following statement, where the code is inserted directly before the semi-colon.

var x = ;

So the following is acceptable:

// The code in the custom JavaScript box
// Note: there's no semi-colon on the end
function () { 
  return 3 * 5;
}()

// Once inserted to the "var x = " statement
var x = function () { 
  return 3 * 5;
}();

But this is not:

// Code in the the custom JavaScript box
function () {
  return 3 * 5;
}

// Which will result in
var x = function () {
  return 3 * 5;
};

// ERROR: `var x` is a function, it needs to be a value!

Nor is:

// Code in custom JavaScript box
return window.some_variable

// Resulting code
var x = return window.some_variable;

// ERROR: should not have the `return` in there

Arrays

Using JavaScript variables you can also handle arrays of values.

For example if you have a custom JavaScript parameter that returns an array, it can be used as an array in the script. For example:

<script>
  for (var i = 0; i < ${arr}.length; i++) {
    console.log(${arr}[i]);
  }
</script>

There are two keywords that it specially replaces, length and [i]. For example if you had the array [1, 2, 3, 4] and the variable i = 2:

${token}.length will be replaced with [1, 2, 3, 4].length (that is 4)

${token}[x] will be replaced with [1, 2, 3, 4][i]. So, i being 2, this will return 3.

jQuery parameter

jQuery-based parameters are one of the most popular use-cases for JavaScript parameters. While these are not an explicit type of parameter in Opentag, they deserve a special mention because of how useful jQuery is.

Not heard of jQuery before? You find find out more at jqueryuk.com. If you have, you’ll know it makes selecting HTML elements a whole lot easier.

Using selectors

“Selectors” are at the backbone of how jQuery works. If you haven’t used selectors before, check out jQuery’s selecting elements tutorial. Below are a few examples:

// Get an element by id
$("#myid")

// Get an element by class
$(".myclass")

// Get the first h1 tag
$("h1:first")

// Get all link elements that contain "hello"
$("a:contains('hello')")

Passing values to tags

jQuery can be used along with selectors to pass values back to tags as JavaScript parameters.

// pass the text within the first heading tag
function () { 
  return $("h1:first").text();
}()

// pass the text within the div with id "myid"
function () { 
  return $("#myid").text();
}()

HTML can be often be very unstructured, so while the codes above are likely to work, there are extra steps that can be taken to maximise reliability. We’ve put together a few standard functions that you may find useful. They ensure that:

  • The returned value is the correct type (String/Number/Date)
  • Any whitespace before/after the content is trimmed
  • JavaScript errors are suppressed.

You can view the gist here.

Never fear! While these functions may look big and scary, all you should have to do is copy-paste them above your code.

For example:

function () { 

  /** Useful Qubit snippet **/

    // A function to to get the number out of a jquery selector or $el
    var getNumber = function(selectorOrEl, $) {

      // Check jquery
      if (!$ || !$.fn || !$.fn.jquery) {
        return null;
      }

      // Get the $el out of selector, or just reference the $el
      var $el;
      if (selectorOrEl instanceof $) {
        $el = selectorOrEl;
      } else {
        $el = $(selectorOrEl);
      }

      // Make sure it exists
      if ($el.length === 0) {
        return null;
      }

      // Get number out
      var text = $el.text();
      text = $.trim(text);
      var number;
      if (!text) {
        return null;
      } else if (text.match(/free/ig)) {
        number = 0;
      } else {
        var match = text.replace(",", "").match(/([0-9|\.]+)/);
        number = (match) ? match[0] : null;
        number = (!isNaN(number) && number !== null) ? Number(number) : null;
      }
      return number;

    };


  /** Your code **/

    return getNumber($("#myNumberId"));

}()

Helpful pointers

  • jQuery needs to exist on the page and before the Opentag container
  • To maximise reliability, use parameters Universal Variable parameters rather than scraping the page with jQuery.
  • Use our pre-defined functions in the gist.
  • Use a custom starter with $(document).ready(cb) inside so the tag doesn’t look for an element that doesn’t exist on the page yet.
  • By default our gist snippets look for window.$, if jQuery on the page is under a different name, you can pass the window.myCustomJquery as the second argument of the getNumber function.

Query parameter from the URL

Opentag can be used to extract the value from a query parameter in the URL. For example, if you wanted the value of the parameter myid from the URL http://yourdomain.com?myid=123456, Opentag could be used as below, passing 123456 to the tag.

opentag-query-parameter

Cookie value

Rather than writing a JavaScript function to extract the value of a cookie (e.g. Quirksmode), Opentag allows you to easily pass it’s value to a tag:

opentag-cookie-parameter

If the cookie does not exist for the domain, the script will not execute. If you’d like to send empty value when it does not exist please implement this it a custom JavaScript.

Using third party cookies? Unfortunately, JavaScript cannot be used to read third party cookies. We recommend using a trick like HTML5 postMessage in conjunction with a tag to translate the third party cookie to a first party one.

DOM element value

You can also pass the text within a <div> element (or any other HTML element) to a tag. Just input the name of the element, and its value will be passed to your script. The value will be interpreted as String if it is encapsulated with quotes in the script, otherwise as a number.

For example if you have the following HTML:

<div id="username">John Smith</div>

Setting the element id to ‘username’ (without quotes) will insert the value ‘John Smith’ into your script. Note that if you need to pass text from element that doesn’t have an id attribute, you’ll need to use custom JavaScript (we’d recommend using jQuery parameters).

opentag-dom-parameter

Universal Variable

For full information on Universal Variable, please visit our UV documentation.

opentag-uv-parameter

When you select a variable in this drop down menu, it corresponds to the JavaScript variable listed here.

Was this helpful?