The command queue

Almost everything you can do with the Web SDK from the browser/webpage can be done with the orb() command queue. This guide explains what this is, how it works, and how to use it.

The orb command queue

The JavaScript tracking snippet defines a global orb() function known as the "command queue". It is named this because rather than executing commands immediately (like calling a function), it adds them to a queue and will execute them once the tms.js bootloader is fully loaded.

The tracking snippet defines within the orb() function (which is also an object in JavaScript) a property q as an empty array. Prior to the bootloader loading, calling the orb() function appends the q array with the command.

For example, if you were to run the tracking snippet, run a single command, and then print out the contents of the orb.q variable immediately, you'd see an array, containing the command you just passed to the orb() function:

// We assume the installation snippet has already ran
orb('config', 'SCRIPT_TOKEN_1', { namespace: 'namespace1' });
console.log(orb.q);

// Outputs the following:
// [
//  ['config', 'SCRIPT_TOKEN_1', { namespace: 'namespace1' }]
// ]

Once the bootloader is loaded, it inspects the contents of orb.q and executes each command in order. After that, the orb() function is redefined, so all subsequent calls execute immediately. This pattern abstracts away most of the complexities of asynchronous code!

Adding commands to the queue

All calls to the orb() command queue share a common signature. The first parameter, the "command", is a string that identifies a particular bootloader method. The next parameter identifies the target or object of worth for that command. The last parameter is an object, which contains any other required parameters that the command might need.

All commands are global and are run by the bootloader. For a comprehensive list of all commands that can be executed via the command queue, see the bootloader section of the Web SDK Reference.

Info

Once the bootloader has loaded, all commands are also available as functions under the loaded orb.bootloader object. orb('config', ...) can also be called with orb.bootloader.config(...).