Annotate Image

When putting together a support article that includes images, annotating those images with text, shapes, arrows etc. to call out specific parts of the image is a common use case that allows you can speak to specific parts of a bigger context.

Types of Image Annotation

We currently support the following types of annotation:

• Rectangle
• Arrow
• Enumeration
• Text
• Watermark
• modifyText
• blur

The bare minimum required to annotate screenshot

POST /screenshot

You can annotate a screenshot by specifying the selector(s) in the annotate property. For example:

{
  "url": "https://demo.baremetrics.com/stats/mrr",
  "elementSelector": [
    "section.main-graph.mrr"
  ],
  "deviceScaleFactor": 1,
  "margin": 10,
  "backgroundColor": "orange",
  "borderRadius": 25,
  "responseType": "image",
  "annotate": [
    {
      "type": "rectangle",
      "selectors": [
        "#s2id_autogen5"
      ]
    }
  ]
}

List of supported attributes

You can customize each annotation type by either specifying a list of attributes for all annotations as a global configuration or by applying a specific setting to each annotation.

Option	Default value	Annotation type	Description
offset	10	All	Add space around the element (think CSS padding) e.g 10
color	#dc2626	All	The border color of the rectangle e.g green, #800080
width	4	rectangle, arrow, enumeration	The border width of the rectangle e.g 4
position	bottom	text	Text placement. Possible values: bottom, top
size	20	text, enumeration,watermark	The size in px of the text
message	''	text	The message to be displayed.
opacity	0.3	watermark	The message to be displayed.

Usage

Below is a series of examples demonstrating various properties of the screenshot API endpoint focusing on the annotate property.

Example 1: Adding multiple rectangle annotations

{
  "url": "https://demo.baremetrics.com/stats/mrr",
  "elementSelector": [
    "section.main-graph.mrr"
  ],
  "deviceScaleFactor": 1,
  "margin": 10,
  "backgroundColor": "purple",
  "borderRadius": 25,
  "responseType": "image",
  "annotate": [
    {
      "type": "rectangle",
      "selectors": [
        "#s2id_autogen5"
      ]
    },
    {
      "type": "rectangle",
      "selectors": [
        "#s2id_autogen3"
      ]
    }
  ]
}

Example 2: Specifying multiple selectors type per annotation

{
  "url": "https://demo.baremetrics.com/stats/mrr",
  "elementSelector": [
    "section.main-graph.mrr"
  ],
  "deviceScaleFactor": 1,
  "margin": 10,
  "backgroundColor": "red",
  "borderRadius": 25,
  "responseType": "image",
  "annotate": [
    {
      "type": "rectangle",
      "selectors": [
        "#s2id_autogen5.fake",
        "xpath///*[@id='s2id_autogen5']"
      ]
    },
    {
      "type": "rectangle",
      "selectors": [
        "#s2id_autogen3.fake",
        "xpath///*[@id='s2id_autogen3']"
      ]
    },
    {
      "type": "rectangle",
      "selectors": [
        "body > div.container > div.container--inner > section > main > section > div.metric-stat > div.col.col-main > h1.fake",
        "xpath//html/body/div[1]/div[2]/section/main/section/div[2]/div[1]/h1"
      ]
    }
  ]
}

Example 3: Global annotation configuration

{
  "global": {
    "annotation": {
      "color": "purple",
      "width": 3,
      "offset": 3
    }
  },
  "url": "https://example.org/",
  "elementSelector": [
    "body > div"
  ],
  "deviceScaleFactor": 1,
  "margin": 10,
  "backgroundColor": "brown",
  "borderRadius": 25,
  "responseType": "image",
  "annotate": [
    {
      "type": "rectangle",
      "selectors": [
        "body > div > p:nth-child(2)"
      ]
    }
  ]
}

Example 4: Overriding the default offset, width and color properties.

{
  "url": "https://example.org/",
  "elementSelector": [
    "body > div"
  ],
  "deviceScaleFactor": 1,
  "margin": 10,
  "backgroundColor": "brown",
  "borderRadius": 25,
  "responseType": "image",
  "annotate": [
    {
      "offset": 10,
      "width": 5,
      "color": "orange",
      "type": "rectangle",
      "selectors": [
        "body > div > p:nth-child(2)"
      ]
    }
  ]
}

Example 5: Adding various annotation types to the same screenshot

{
  "url": "https://example.org/",
  "elementSelector": [
    "body > div"
  ],
  "deviceScaleFactor": 1,
  "margin": 10,
  "backgroundColor": "brown",
  "borderRadius": 25,
  "responseType": "image",
  "annotate": [
    {
      "offset": 10,
      "width": 5,
      "color": "orange",
      "type": "rectangle",
      "selectors": [
        "body > div > p:nth-child(2)"
      ]
    },
    {
      "offset": 10,
      "width": 5,
      "color": "purple",
      "type": "arrow",
      "selectors": [
        "body > div > p:nth-child(2)"
      ]
    },
    {
      "offset": 20,
      "width": 1,
      "color": "pink",
      "type": "enumeration",
      "selectors": [
        "body > div > p:nth-child(2)"
      ]
    }
  ]
}

Example 6: Adding a text annotation

{
  "url": "https://example.org/",
  "elementSelector": [
    "body > div"
  ],
  "deviceScaleFactor": 1,
  "margin": 10,
  "backgroundColor": "brown",
  "borderRadius": 25,
  "responseType": "image",
  "annotate": [
    {
      "type": "text",
      "message": "Hello World",
      "position": "bottom",
      "size": 12,
      "offset": 12,
      "color": "white",
      "selectors": [
        "body > div > p:nth-child(2)"
      ]
    }
  ]
}

Example 7: Adding a watermark of type image

{
  "responseType": "image",
  "deviceScaleFactor": 1,
  "elementSelector": [
    "body > div"
  ],
  "steps": [
    {
      "type": "navigate",
      "url": "https://example.org"
    },
    {
      "value": 3000,
      "type": "waitFor"
    }
  ],
  "annotate": [
    {
      "type": "watermark",
      "image": "https://app.launchbrightly.com/launchbrightly-mark-social-rounded-512px.png",
      "position": "bottom-right",
      "size": 25,
      "offset": 10,
      "opacity": 1
    }
  ]
}

Example 8: Adding a watermark of type text

{
  "responseType": "image",
  "deviceScaleFactor": 1,
  "elementSelector": [
    "body > div"
  ],
  "steps": [
    {
      "type": "navigate",
      "url": "https://example.org"
    },
    {
      "value": 3000,
      "type": "waitFor"
    }
  ],
  "annotate": [
    {
      "type": "watermark",
      "text": "Captured by Launchbrightly  ",
      "position": "bottom-right",
      "size": 13,
      "offset": 0,
      "color": "red"
    }
  ]
}

Example 8: Modify an existing text using modifyText

{
  "responseType": "image",
  "deviceScaleFactor": 1,
  "elementSelector": [
    "body"
  ],
  "steps": [
    {
      "type": "navigate",
      "url": "https://example.org"
    },
    {
      "value": 3000,
      "type": "waitFor"
    }
  ],
  "annotate": [
    {
      "type": "modifyText",
      "selectors": [
        "h1",
        "xpath/html/body/div/h3"
      ],
      "value": "Hello World!"
    }
  ]
}

Example 9: Adding a blur annotation

  {
  "url": "http://example.org",
  "fullPage": true,
  "annotate": [
    {
      "type": "blur",
      "selectors": [
        "body > div > p:nth-child(2)"
      ],
      "intensity": 100,
      "color": "red"
    }
  ],
  "deviceScaleFactor": 1
}

💡 Scrolling behavior for full page screenshots:

1. When capturing a full screenshot (fullPage: true), the API will automatically scroll to the annotated element if it falls outside the viewport.

2. If multiple elements are annotated, the API will scroll to the last one.