Purpose

Store shared (mustache) templates to be used by the implementation of JavaScriptBuilderElement and other components across the languages.

Background

The language-independent specification describes how JavaScriptBuilderElement is used here. The mechanics is: javascript file is requested from the server (on-premise web integration) and is created from this mustache template by the JavaScriptBuilderElement. It then collects more evidence, sends it to the server and upon response calls a callback function providing the client with more precise device data.

Cookies -> Session storage Transformation

The processJsProperties function in javascript template has a section that uses regex to search the injected JavaScript for any commands that set cookie values to the browser's document object. It then transforms this command so that it sets session storage values instead. This format should be accounted for when writing JavaScript properties.

---

Cookie Transformation regular expression rules

Valid Format for Cookie Statements:

• Cookie Assignment: The expression should start with document.cookie =
• Spaces: Spaces around the first = sign are optional
• Cookie Name: The name of the cookie should only contain alphanumeric characters, underscores, and must not have spaces
• Assignment with Double Quotes: The cookie value assignment can use double quotes, and the value should be set programmatically by concatenating a string with a variable or expression
• Assignment with Backticks: The cookie value assignment can use backticks for template literals, and the value can be set programmatically using expressions inside ${}
• No Direct Value Assignment: Directly setting a value within the string is not allowed; values must be set programmatically

Regular Expression:

/document\.cookie\s*=\s*(("([A-Za-z0-9_"\s\+]+)\s*=\s*"\s*\+\s*([^\s};]+))|(`([A-Za-z0-9_]+)\s*=\s*\$\{([^}]+)\}`))/g

Valid Examples:

document.cookie="51D_PropertyName="+"True"; // No spaces around the equals and/or plus sign
document.cookie = "51D_PropertyName=" + "True"; // Spaces around the equals sign
document.cookie = "51D_PropertyName=" + screen.height; // Assigning a value using a variable
document.cookie="51D_PropertyName="+screen.height; // No spaces, variable assignment
document.cookie=`51D_PropertyName=${btoa(JSON.stringify(value))}` // Using a template literal with an expression
document.cookie="51D_PropertyName="+profileIds.join("|") // Assigning a value using a joined string of variables
document.cookie = `51D_PropertyName=${"True"}`; // Using backticks for programmatic value assignment

Invalid Examples:

document.cookie = "51D_PropertyName=True"; // Direct assignment within the string is not allowed
document.cookie = "51D_PropertyName=" + profileIds.join(" ") // Spaces within the expression are not allowed
document.cookie = "  51D_PropertyName  = " + "True"; // Spaces inside the cookie name are not allowed
document.cookie = `  51D_PropertyName  =${"True"}`; // Spaces inside the template literal are not allowed
document.cookie = `51D_PropertyName=START${window.middle}END`; // Concatenating strings directly within template literals is not allowed

---

CSP Considerations

Content Security Policy is an added layer of security to mitigate cross-site and other types of attacks. CSP limits which 3rd party resources are loaded and what these resources are allowed to do. 51Degrees JavaScript produced from the template is usually such a 3rd party resource when hosted on 51Degrees cloud. If CSP header specifies script-src it has to list 51Degrees cloud origin as a source and also add 'unsafe-eval' as a source.

'unsafe-eval' source is needed because the template loads and executes dynamic javascript code snippets relying on JavaScript Function API which is in the eval() family. The snippets are part of the data file and are frequently updated to support latest changes in the browsers. Snippet execution may cause multiple server calls to load more dynamic code (in theory, in practice it usually comes down to a single server call) - thus this code can not be statically included in the template and has to be loaded dynamically as part of the JSON response of the server.

Shipping / Deployment

This repo is not a stand-alone package, but is shipped as part of and used by each of the following repositories / packages:

• pipeline-dotnet as a submodule
• pipeline-java as a submodule
• pipeline-node as a submodule
• pipeline-python as a submodule
• pipeline-php-core as a static dependency

Wherever it is a submodule it will be updated by Nightly Submodule Update action, wherever it is a static dependency it will be updated by the Nightly Package Update action within a target repository.

No special action is needed from the user to deploy the template, just be aware that any changes introduced in this repo will automatically propagate and affect the above packages.