Boxalino Convert Endpoint

Owned by Dana Negrescu
Last updated: Feb 02, 2022
2 min read

As part of a new newsletter integration strategy, the recommended products/content details (pictures) will be generated live, upon endpoint use.

A sample of the use of the convert (live) endpoint is used on our Shopware6 QA server: http://auto-qa.bx-cloud.com/Newsletter/


This is how the final link (shared with Boxalino) is:

https://convert.bx-cloud.com/img/stream?cropWidth=400&cropHeight=655&source=http://auto-qa.bx-cloud.com/boxalino/newsletter/product/en/<product-id>

Set the properties viewportWidth/viewportHeight, cropWidth/cropHeight ,source  and converter (optional) values.

https://convert.bx-cloud.com/img/stream?viewportWidth=400&viewportHeight=655&converter=puppeteer&source=http://auto-qa.bx-cloud.com/boxalino/newsletter/product/en/<product-id>

Use your account`s API key / API secret (role: ADMIN API Credentials ) in order to access the bx-convert endpoint.

 

About the CONVERT endpoint


The public service (convert.bx-cloud.com) is a play framework application that performs conversions. Currently, it implements wkhtmltoimage to convert html pages to images (opensource)

html to image conversion

Api paths (GET):

Path

Functionality

Path

Functionality

/img/stream?[...]

generates and streams the image

/img/redirect?[...]

generates and redirects to the /img/get endpoint

/img/get?[...]

public endpoint, only supports retrieval

Note that the /img/get api should never be directly used, because the result image will eventually be deleted (typically after 24 hours).

Use the /img/redirect api instead to always ensure a fresh image.

Parameters supported for stream and redirect endpoints:

Name

Description

Name

Description

bypassCache

if set to true, always generates a new image

viewportWidth

Set viewport width

viewportHeight

Set viewport height

cropWidth / clipWidth

Set width for cropping / clipping

cropHeight / clipHeight

Set height for cropping / clipping

cropX / clipX

Set x coordinate for cropping / clipping

cropY / clipY

Set y coordinate for cropping / clipping

javascriptDelay

Wait some milliseconds for javascript finish (default 200)

quality

Output image quality (between 0 and 100) - defaults to 85

encoding

Set the default text encoding, for input

converter

Which converter to use, supports: "puppeteer", "wkhtml"

selector

css selector of element to screenshot (screenshot the entire page if absent)
(must include . or # )

- when selector is used, the viewportWidth must be set (viewportHeight can be ignored)

timeoutSeconds

timeout per try* to convert the image in seconds, default 60

*Whenever trying to convert an image, will try up to 3 times, the timeout applies to each individual try independently, i.e. 180 seconds in total.

Examples

caveats using custom fonts

There are some issues using custom fonts, see also: https://stackoverflow.com/questions/10611828/use-custom-fonts-with-wkhtmltopdf