Blink managed functions

While Blink tries to offer a lot of built-in functionality, different websites have different needs, and some may be too custom to make sense within Blink. This is why the Blink SDK offers an API to register and call your own Javascript functions. These functions can be used in a lot of places such as User Journey conditions, User Journey actions, in template expressions within panel custom content and more.

API

blinkSDK.addFunction(key, func)

Adds the function func to the map of managed functions, at the key key. Subsequently, calls to callFunction, hasFunction, getFunction for key key will return this function. key must be a string of dot-separated valid JavaScript identifiers.

Example:

function sum(a, b) { return a + b }

blinkSDK.addFunction("mySum", sum)
blinkSDK.addFunction("mySum.inline", function(a, b) { return a + b })
blinkSDK.addFunction("mySum.lambda", (a, b) => a + b)

blinkSDK.addFunctions(obj)

Receives an object containing key: func pairs, and adds all of them to the map of managed functions, same as by calling addFunction on each item of the object.

Example:

function sum(a, b) { return a + b }

blinkSDK.addFunctions({
    mySum: sum,
    "mySum.inline": function(a, b) { return a + b },
    "mySum.lambda": (a, b) => a + b,
})

blinkSDK.callFunction(key, ...args)

Invokes the function found at key key with the arguments ...args. This function looks up key in all functions registered by using addFunction or addFunctions, as well as all the SDK built-in functions and functions found in the global scope.

Returns an array with two elements:

  • first element will be true or false: whether the call succeeded
  • the second element will be null if the call failed, or the return value of the function if the call succeeded

The function call may fail if the function isn't found or if it threw an exception. In both cases, the exceptionHandler will be called (asynchronously) to inform you of the exception (see below).

Note: Calling a function through this API blocks exceptions. If you want to let exceptions flow, you can use something like blinkSDK.getFunction(key)(...args) instead.

Example:

function sum(a, b) { return a + b }
window.blinkAPI = {mySum: sum}
blinkSDK.addFunction("mySum", sum)
blinkSDK.callFunction("mySum", 3, 4)  // -> [true, 7] (found in registered functions)
blinkSDK.setVariable("myVar", "myValue")
blinkSDK.callFunction("getVariable", "myVar")  // -> [true, "myValue"] (built-in function)
blinkSDK.callFunction("blinkAPI.mySum", 3, 4)  // -> [true, 7] (found in global scope)
blinkSDK.callFunction("unknown", 3, 4)  // -> [false, null] (not found)

function thrower(a, b) { throw Error(String(a + b)) }
blinkSDK.addFunction("thrower", thrower)
blinkSDK.callFunction("thrower", 3, 4)  // -> [false, null] (throws an exception)

blinkSDK.hasFunction(key)

Returns true/false whether the key exists in the map of managed functions. This looks through the functions registered by using addFunction or addFunctions, then through the SDK built-in functions, but not through functions found in the global scope.

Example:

function sum(a, b) { return a + b }
blinkSDK.hasFunction("mySum")  // -> false
blinkSDK.addFunction("mySum", sum)
blinkSDK.hasFunction("mySum")  // -> true

blinkSDK.hasFunction("getVariable")  // -> true, builtin function

blinkSDK.getFunction(key)

Returns the function at key key, or undefined if it doesn't exist. This looks through the functions registered by using addFunction or addFunctions, then through the SDK built-in functions, but not through functions found in the global scope.

Example:

function sum(a, b) { return a + b }
blinkSDK.getFunction("mySum")  // -> undefined
blinkSDK.addFunction("mySum", sum)
blinkSDK.getFunction("mySum")  // -> sum

blinkSDK.getFunction("getVariable")  // -> a Blink builtin function

blinkSDK.allFunctions()

Returns an object with all functions registered by using addFunction or addFunctions, as well as all the SDK built-in functions, but (obviously) not all the functions found in the global scope.

Example:

function sum(a, b) { return a + b }
blinkSDK.addFunction("mySum", sum)
blinkSDK.allFunctions()  // -> an object that definitely contains "mySum" as a key

blinkSDK.setExceptionHandler(func)

Sets a new exception handler and returns the old one.

The exception handler is used when blinkSDK.callFunction doesn't find a function with the requested key, or when it causes an exception within your function. In that case, the exception handler is called asynchronously to not disrupt the current synchronous flow of the Blink SDK (that could have pretty weird consequences when evaluating User Journeys). The exception handler is called with 2 arguments: the first one is the exception itself (a ReferenceError in the case when the function isn't found), and the second one is the key of the function that caused the exception.

When calling this the first time, it will return the default exception handler, which simply throws the first argument it receives.

Example:

blinkSDK.setExceptionHandler(function (exc, key) {
    console.error("Exception thrown in Blink function at key", key)
    console.error(exc)
})
blinkSDK.callFunction("unknownKey")  // function not found
// ...after asynchronous tick...
// > Exception thrown in Blink function at key unknownKey
// > ReferenceError: Function not found for key 'unknownKey'

blinkSDK.getExceptionHandler()

Returns the current exception handler.

If you didn't set an exception handler before calling this, it will return the default exception handler, which simply throws the first argument it receives.

Example:

function blinkFunctionExcHandler(exc, key) {
    console.error("Exception thrown in Blink function at key", key)
    console.error(exc)
}
blinkSDK.setExceptionHandler(blinkFunctionExcHandler)
blinkSDK.getExceptionHandler()  // -> blinkFunctionExcHandler
← Load the SDKBlink managed variables →