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.1/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 Type Required Description
imageUrl string No URL of image to be annotated.
imageDataUrl string No Image in base64 format.
imageFile File No HTML File object.
exportFormat string Yes Image format in which the annotated markup will be returned. Possible values: 'IMAGE_DATA_URL', 'IMAGE_BLOB'.
secret string No If the user has previously created a markup, you can passback their generated secret string here.
onCompleted Function Yes Callback function to be invoked when the user clicks "Done" button after annotating image.
showCancel boolean No Should the "Cancel" button be displayed allowing the user to exit annotation view resetting any changes.
onCancelled Function No If showCancel is true, this callback function will be invoked when the user clicks "Cancel".

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 annotating the image and clicks the "Done" button in the top right of the annotation view.

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-annotate 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.

onCancelled callback

The onCancelled callback function is invoked when the user clicks the "Cancel" button in the top right of the annotation view.

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.
secret Secret string. To be stored for later use to be able to re-annotate the 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 Type Required Description
markupId string Yes Markup identifier returned after the createMarkup function call.
secret string Yes Secret string returned after the createMarkup function call
exportFormat string Yes Image format in which the annotated markup will be returned. Possible values: 'IMAGE_DATA_URL', 'IMAGE_BLOB'.
onCompleted Function Yes Callback function when the user clicks "Done" button after annotating image.
showCancel boolean No Should the "Cancel" button be displayed allowing the user to exit annotation view resetting any changes.
onCancelled Function No If showCancel is true, this callback function will be invoked when the user clicks "Cancel".
javascript