NAV
javascript

Summary

Markup Hero Annotation API is a browser javascript library that allows any web application to take advantage of markuphero.com annotation functionality.

Setup

Script Tag

Add the following script tag to your website's head:

<html>
  <head>
    <script async src="https://static.markuphero.com/v0.2.0/annotation-api.js" />
  </head>
</html>

Add our javascript payload to your website by placing our script tag in the html head.

API Token

window.MARKUP_HERO_PUBLIC_API_TOKEN = '*YOUR API TOKEN*';

Define your Markup Hero Public API token.

Styling

MarkupHeroApi.configureStyle({
  activeButtonColor: '#0071df',
  darkButtonColor: '#161618',
  backgroundColor: '#dddddd'
});

There are three colors available for optional customization:

Colors can be partially customized.

Usage

Create Markup

createMarkup function

MarkupHeroApi.createMarkup({
  imageUrl: 'https://images.pexels.com/photos/802112/pexels-photo-802112.jpeg',
  exportFormat: 'IMAGE_DATA_URL',
  onCompleted: onCompletedCallbackFunction
}).then((result) => {
  let markupId = result.markupId;
  let secret = result.secret;
});

Promise result:

{
  "markupId": "TxDCRyPSC7HiD5Scb3rG",
  "secret": "844616fe-6216-4fe4-867c-9cbbdc03c7ca"
}

Creates a markup and displays the annotation editor to the user.

createMarkup request object parameters:

Parameter Required Description
imageUrl No URL of image to be annotated.
imageDataUrl No Image in base64 format.
imageFile No HTML File object.
exportFormat Yes Image format in which the annotated markup will be returned. Possible values: 'IMAGE_DATA_URL', 'IMAGE_BLOB'.
secret No If the user has previously created a markup, you can passback their generated secret string here.
onCompleted Yes Callback function to be invoked when the user clicks "Done" button after annotating image.

When exportFormat value of 'IMAGE_BLOB' is provided, the returned image format will be of HTML File object. (https://developer.mozilla.org/en-US/docs/Web/API/File)

The function call returns a promise with a result object that contains:

Parameter Description
markupId Markup identifier. To be stored for later use to retrieve the markup image & user annotations.
secret Secret string. To be stored for later use to be able to re-edit the markup.

The above values are also returned in the onCompleted callback and do not need to be consumed at this stage.

Callback function to be defined for use in createMarkup & openMarkup call

const onCompletedCallbackFunction = (result) => {
  const {markupId, 
         secret, 
         imageBlob, 
         imageDataUrl} = result;
};

onCompleted callback

The onCompleted callback function is invoked when the user is done annotation the image and clicks the "Done" button in the top right of the screen.

The function is invoked with the following return parameters:

Parameter Description
markupId Markup identifier. To be stored for later use to retrieve the markup image & user annotations.
secret Secret string. To be stored for later use to be able to re-edit the markup.
imageBlob If exportFormat = 'IMAGE_BLOB', the HTML File object of the annotated markup.
imageDataUrl If exportFormat = 'IMAGE_DATA_URL', the base64 string of the annotated markup.

Open Markup

Re-opens a markup that has been previously created.

openMarkup function

MarkupHeroApi.openMarkup({
  markupId: 'TxDCRyPSC7HiD5Scb3rG',
  secret: '844616fe-6216-4fe4-867c-9cbbdc03c7ca',
  exportFormat: 'IMAGE_DATA_URL',
  onCompleted: onCompletedCallbackFunction
});

openMarkup request object parameters:

Parameter Required Description
markupId Yes Markup identifier returned after the createMarkup function call.
secret Yes Secret string returned after the createMarkup function call
exportFormat Yes Image format in which the annotated markup will be returned. Possible values: 'IMAGE_DATA_URL', 'IMAGE_BLOB'.
onCompleted Yes Callback function when the user clicks "Done" button after annotating image.