Embed Annotation

Embed the annotation interface right into your product. Manage and control the process from the Heartex dashboard. Customize the look and feel of the editor to follow your brand’s and product design.

Creating virtual Collaborator

The first step is to create a virtual collaborator (you can also use a real one). Collaborator account will be used to complete tasks, and usually, you create a separate collaborator account for every user of your own product or a cohort of users. This can be automated using an API. API request returns a collaborator token that is further used to authenticate when loading and completing the task.

Requests and Response looks like this:

~/ » http -f POST https://go.heartex.net/api/projects/1/experts/ Authorization:"Token 6c684e40104fd1c8b6b45ef0a663b5fa857689ba" email="test@heartex.net"
HTTP/1.1 200 OK                                                                                                                                                                                     
Allow: POST, OPTIONS
Content-Length: 73
Content-Type: application/json
Date: Thu, 18 Nov 2019 20:29:50 GMT
Vary: Accept, Origin, Cookie
X-Frame-Options: SAMEORIGIN

{
    "expert_id": 1,
    "expert_token": "3d88cd31f15de845161659faaa6412c85feead24"
}

Embed the Editor using SDK

Heartex provides you the SDK located at: https://go.heartex.net/static/js/htx-v1.0.0.js. After loading the javascript you get the HeartexSDK object you can initialize. It expects an authentication token, for example the one you get above after creating a collaborator, and a set of parameters, for example a task id.

When the initialization is done, it automatically renders the interface into the element with the provided html id. Here are three steps you need to take to embed it on your page:

Step 1: Create element

Copy or create a div element that will be used as a parent element for the Editor

<div id="label-studio"></div>

Step 2: Loader script

Following script executes the code when the DOM is ready, if you use jQuery it’s an equivalent of $(function () {})

<script type="text/javascript">
  !function(d,o){d.domReady=function(n,a){o.addEventListener&&o.addEventListener("DOMContentLoaded",function e(t){o.removeEventListener("DOMContentLoaded",e),n.call(a||d,t)})||o.attachEvent&&o.attachEvent("onreadystatechange",function e(t){"complete"===o.readyState&&(o.detachEvent("onreadystatechange",e),n.call(a||d,t))})}}(window,document);
</script>

Step 3: SDK config

Initialization code. You need to edit $ variables to make it usable

<script type="text/javascript">
  domReady(function () {
      var Htx = new HeartexSDK({
          token: $TOKEN,
          elid: $ELID,
          // config: $CONFIG,
          
          task       : $TASKID,
          expert     : $EXPERT,
          project    : $PROJECTID,
          interfaces : ["controls", "side-column", "panel", "submit", "update", "check-empty"],
          
          messages: {
            DONE: "Great! Thanks!"
          },
          
          onSubmitCompletion: function(result) {
            console.log(result)
          }
      });
  });
</script>

SDK Config

SDK can be configured in a number of ways, including what UI elements are shown to the user, messages for specific actions, validation of the input and others. There are a number of required params: token, elid, task, expert, project

token

Expert authentication token, you can use API to fetch one or create a new collaborator

elid

DOM Element ID used for rendering the editor

task

Heartex Task ID to work on

expert

Expert ID

project

Project ID associated with the task

config

Project label config, if you don’t provide that there is an extra request to fetch that from the server

supports

Default: null

Type data: array

[
  "completions:load",
  "predictions:load",
  "check-empty",
  "next:load"
]

interfaces

Default: null

Type data: array

Collection of modules to include and respective options:

[
  "controls",
  "side-column",
  "panel",
  "submit",
  "skip",
  "update",
  "predictions:menu",
  "completions:add-new"
  "completions:delete"
  "completions:set-groundtruth"
  "completions:menu",
]

SDK Callbacks

Callbacks can be useful when you need to capture the actions being performed inside the editor, for example when the task gets submitted.

onSubmitCompletion

Type data: function

Called when a button submit is pressed. result is the value of current completion.

Example

onSubmitCompletion: function(result) {
  console.log(result)
}

onUpdateCompletion

Type data: function

Called when a button update is pressed. result is value of current completion.

Example

updateCompletion: function(result) {
  console.log(result)
}

onDeleteCompletion

Type data: function

Called when a button delete is pressed. result is value of current completion.

Example

deleteCompletion: function(result) {
  console.log(result)
}

onEntityCreate

Type data: function

Called when a new region gets labeled, for example a new bbox is created. region is the object that got created

Example

onEntityCreate: function(region) {
  console.log(region)
}

onEntityDelete

Type data: function

Called when an existing region got deleted. region is the object itself.

Example

onEntityDelete: function(region) {
  console.log(region)
}

onSkipTask

Type data: function

Called when a button skip is pressed.

onTaskLoad

Type data: function

Called when the task is done loading through the API.

onLabelStudioLoad

Type data: function

Called when editor is done loading is pressed.