Getting proof images

• 3 minutes to read

When users approve results of their work, you need to show them proof images displaying customized products. You can find rendering configuration parameters in the Proof images topic. Here you will also learn the parameters of the API methods to render proofs.

To generate proof images, you can just call the getProofImages method with the default options. However, Customer's Canvas allows you to render three types of proof images: a page thumbnail, a real-size page preview, and product thumbnails as a multi-page PDF. All of these proof images are 72 DPI. To configure proof images, you can pass the following options to getProofImages:

• A page thumbnail:
  • maxHeight is the maximum height of thumbnails (500 by default).
  • maxWidth is the maximum width of thumbnails (500 by default).
• A real-size page preview:
  • generateLargePreviews enables real-size proof images.
  • largePreviewMaxHeight is the maximum height (by default, the surface height is applied).
  • largePreviewMaxWidth is the maximum width (by default, the surface width is applied).
• A product preview:
  • generateProductProof enables a preview of all product pages in a multipage PDF file.
  • productProofPageIndexes specifies page indexes to be included in the output PDF file.

All these properties are optional. By default, this method renders a page thumbnail. To pass the properties, combine them in an object as follows:

//Getting links to proof images.
editor.getProofImages({maxHeight: 720, maxWidth: 720, pregeneratePreviewImages: true})
    //Handling the results.
    .then(function (result) { ... })
    .catch(function (error) { ... });

To specify the required size, you can pass the maximum width and height. If you omit these parameters, the default value of 500 will be applied. This method proportionally resizes proof images according to maxHeight and maxWidth. For example, if they are both set to 640 pixels, then a 1280 x 960 px image will be resized to 640 x 480 px. In the previous example, the width and height of a proof image are limited to 720 pixels.

You can also pass the pregeneratePreviewImages option to start generating proof images in the background when running this method. By default, getProofImages only returns links to proof images and starts generating these images when a request to download them is received.

To render real-size proof images, set generateLargePreviews to true. This option allows you to specify the largePreviewMaxWidth and largePreviewMaxHeight parameters to render images at a different size from the actual size.

The generateProductProof property allows you to output previews of all product pages to a multipage PDF file. In this case, proofImageRendering.fileFormat is ignored. If only a few of the pages are required, you can specify their indexes in the productProofPageIndexes array. Only these pages will be included in the output PDF file. You can specify comma-separated numbers as well as page ranges (two numbers separated by a dash "-"), in any order.

This method returns a promise, of which the onFulfilled callback function accepts an object implementing the IProofResult interface. This interface has only one property:

• proofImageUrls: the array of temporary links to proof images. The getProofImages method creates state files in the cache, so these links become invalid after a cache cleanup. You can get permanent links to proof images using the finishProductDesign method.

//Getting links to proof images.
editor.getProofImages()
    //If the links to proof images were generated successfully.
    .then(function (result) {
        proofImageUrls = result.proofImageUrls;
        ...
    })
    //If there was an error thrown while getting links to proof images.
    .catch(function (error) {
        console.error("Getting proof images failed with exception: ", error);
    });

When you generate product previews in PDF files and allow your users to directly download these files using the links returned by this method, you can pass the filename query parameter that enables the download and customizes the resulting file name. For example, to download a booklet.pdf file:

https://example.com/api/rendering/GetProofImage/JohnWood/06047be9-78fb-4b89-98c5-8b1712ba1b51/-1\_-1.pdf?filename=booklet

Generated proof images as well as hi-res outputs are cached by default. To disable caching, include the query parameter disableCache=true in the resulting link, for example:

https://example.com/api/rendering/GetProofImage/JohnWood/06047be9-78fb-4b89-98c5-8b1712ba1b51/-1\_-1.pdf?disableCache=true