Compilers Widget

Sphere Engine Compilers Widget allows you to run computer programs directly on the website. More precisely, it allows you to integrate the Compilers module of the Sphere Engine service via a component known as the widget, that's ready to be embedded on a website. Sphere Engine Compilers is a service that allows for remote execution of computer programs. It allows you to send a computer program written in one of many supported programming languages and execute it with the input data that you defined. Detailed information about the Sphere Engine Compilers module can be found in the introduction.

Embedding the widget is a quick and easy process allowing for the integration of any IT system with the Sphere Engine Compilers module and is recommended for both the expansion of existing projects and for projects built from scratch. An alternative method is integration using RESTful API.

The ability to embed a tool that allows you to run programs on a website can be used in many ways. For example:

  • extension of the system to conduct recruitment interviews with the ability to execute programs written by candidates,
  • supplementing e-learning programming courses with executable examples of programs,
  • enhancing the system for sharing code snippets with the ability to run the program.

Note: The above applications suggest the use of the widget to expand existing systems. Nothing prevents you from using this integration method to build systems from scratch.

See how it works

Widget embedded below allows you to familiarize yourself with its basic features.

Widget integration

Before the widget is integrated, it is necessary to create and configure it. In the widget's management panel (Menu > Compilers > Widgets), you can find the Create widget button which, when pressed, initiates the configuration process.


Using this method, you should attach to your code two snippets of HTML code responsible for the initialization and displaying the widget.

Widget initialization

The code responsible for widget initialization should remain embedded only once (regardless of the number of widgets displayed on the page), immediately after the <body> element.

A personalized and ready-to-use widget initialization code can be found in Menu > Compilers > Widgets > WIDGET NAME > Widget integration:

<script>SEC_HTTPS = false;
SEC_BASE = "<customized_link>"; 
(function(d, s, id){ SEC = window.SEC || (window.SEC = []);
  var js, fjs = d.getElementsByTagName(s)[0];
  if (d.getElementById(id)) return; js = d.createElement(s); = id; 
  js.src = (SEC_HTTPS ? "https" : "http") + "://" + SEC_BASE + "/static/sdk/sdk.js";
  fjs.parentNode.insertBefore(js, fjs);   
}(document, "script", "sphere-engine-compilers-jssdk"));
Displaying the widget

The following code should be embedded on the page in the spot envisioned for the widget:

<div class="sec-widget" data-widget="<hash>"></div>

The hash parameter which is the value of the data-widget attribute is the unique ID of the widget in the Sphere Engine system. It can be found in the Unique hash field in Menu > Compilers > Widgets > WIDGET NAME > Widget settings.

Displaying multiple widgets

Sphere Engine Compilers Widget allows you to embed multiple widgets on a single page. In the basic variant, no additional actions are required.

If you need to manipulate widget's behavior using JavaScript (see JavaScript SDK) it is necessary to identify them, which is done by means of a special identifier (marked as <id>) denoted by the data-id attribute of the div element used to embed the widget. For example:

<div id="idInHTML" data-id="<id>" class="sec-widget" data-widget="<hash>"></div>

Note: The widget is initialized automatically - directly after the page loads in the browser - even if the widget is not yet visible on the page. This makes it possible to perform operations on the widget (e.g. configuration) before displaying it.

Note: The process of loading (and, as a result, displaying) the widget begins only when the widget becomes visible on the screen (i.e. when the user scrolls the page to the widget's position). Thanks to this, the loading of other elements of the page is not blocked. This allows for the page to load faster, which is especially useful when embedding multiple widgets.

Standalone page

An alternative way to embed the widget directly on your site is to use the feature of presenting it as a "standalone page", i.e. on a separate website in the domain.

A link to a standalone page is generated when creating the widget. You will find a ready-to-use link in Menu > Compilers > Widgets > WIDGET NAME > Widget integration. It has the following structure:<hash>

Note: The Standalone page section of the Menu > Compilers > Widgets > WIDGET NAME > Widget integration page provides a configuration field that allows you to define (in the form of HTML code) the header of the page with the widget. You can, for example, embed your own logo in the header.

JavaScript SDK

If you need more control over the behavior of the widget or you would like to process execution results in your system, look for further information in JavaScript SDK document.


Sphere Engine Compilers Widget provides mechanisms for secure integration. A fully secured widget can be embedded only on selected websites (i.e. on websites in the appropriate domain) and the communication between the client's system and the Sphere Engine system is fully reliable (i.e. unauthorized people are unable to falsify or fabricate communication).


In a production environment, we recommend using the signature security measure that fully protects the widget from unauthorized use. The signature verification feature must be enabled in advance by selecting the Secure the widget option in Menu > Compilers > Widgets > WIDGET NAME > Widget settings.

The use of a signature for communication between the client's system and the Sphere Engine system increases the security level, i.e .:

  • eliminates the possibility of unauthorized access to the widget (preventing even complex and difficult attempts at acquiring access by preparing fake HTTP requests)
  • guarantees the reliability of transmitted data.
Signature parameters

Signature generation is based on selected widget parameters and additional signature parameters:

  • hash - unique widget ID in the Sphere Engine system. It can be found in the Unique hash field in Menu > Compilers > Widgets > WIDGET NAME > Widget settings.
  • se_secret - secret key which is the basis for the security of the signature. It can be found in the Shared secret field in Menu > Compilers > Widgets > WIDGET NAME > Widget settings.
  • (optional) se_nonce - unique (for a given widget) session ID.

Important: The se_secret parameter is the basis for the security of the signature and should remain a secret. Do not send it in messages between systems.

Important: The procedure of signature generation in the client's system should not be performed on the front-end side of the application (e.g. using a JavaScript function) due to the se_secret parameter being disclosed.

Note: The use of an optional se_nonce parameter ensures that each session of the end-user (i.e., every situation in which the widget has been initialized) is a one-off. It is impossible to re-initialize the widget using the se_nonce parameter with the same value. Using this parameter provides full protection against unauthorized use of the widget.

Signature generation algorithm

The signature generation procedure can be divided into the following steps:

  • Normalization by sorting parameter names in alphabetical order. For example:
    [hash, se_secret, se_nonce] ➡ [hash, se_nonce, se_secret].
  • Conjunction by saving the parameters and their values ​​in the form of a string with the following format:
    for example:
  • Encoding to the application/x-www-form-urlencoded format using UTF-8 encoding.
  • Hashing using the SHA-256 algorithm which is available for the majority of popular programming languages ​​(in the standard library or as part of an additional library).

Pseudocode of the algorithm that generates the signature

generate_signature(params) {
    // Normalization
    params = sort(params);

    // Conjunction with Encoding
    seq = [];
    foreach p in params {
        seq += key(p) + "=" + urlencode(value(p), "utf-8"); 

    // Hashing
    return sha256(join("&", seq));

Implementation of the algorithm that generates the signature in PHP

function generate_signature($params) {

    $seq = [];
    foreach ($params as $k => $v) {
        $seq[] = $k . "=" . urlencode($v);

    return hash("sha256", implode("&", $seq));

Implementation of the algorithm that generates the signature in Python

def generate_signature(params):
    keys = sorted(params.keys())

    seq = []
    for k in keys :
        seq.append(k + "=" + urllib.parse.quote_plus(params[k]))

    return hashlib.sha256("&".join(seq).encode('utf-8')).hexdigest()
Attaching a signature

The signature and the values ​​of all parameters used to generate it (except the se_secret parameter which should remain secret) should be attached to the embedded widget in the form of the appropriate HTML attributes with the data- prefix:

  • data-widget for the hash parameter,
  • data-nonce for the se_nonce parameter,
  • date-signature for the signature.

An example of HTML code used to embed a widget prepared to support the signature

<div class="sec-widget" 

For those interested: The general scheme for securing communication with the signature assumes that both communicating parties share a secret key (so-called shared secret).
The sender uses the selected parameters of the message (or even the entire message) along with the key to create the so-called signature. The generated signature is attached to the message and sent to recipient.
The recipient, who also has access to the key, repeats the procedure of creating the signature. The received message is authorized, if the signature sent by the sender is identical to the signature generated by the recipient.

What's next?

If you need more control over the behavior of the widget or you would like to process execution results in your system, look for further information in JavaScript SDK document.

Alternative integration method via the RESTful API has been described in: