Personalized Rendering

Customer's Canvas provides a Web API to personalize products and render both proof images and hi-res outputs without loading the editor. This API works based on HTTPS requests and is handled by the Preview and HiRes controllers. It has the following functionality:

Function Request type URL Description
Generate proof images POST ~/api/Preview/GeneratePreview Populates a product with personal data, applies color themes, and generates proof images of the product.
Generate hi-res outputs POST ~/api/HiRes/GenerateHiRes Populates a product with personal data, applies color themes, and generates high-resolution outputs.

As a result, the Preview controller generates URLs that link to proof images. The HiRes controller generates state files and URLs that link to high-resolution outputs. Optionally, this controller generates URLs that link to proof images. The response contains an array of the links grouped by products, their surfaces, and mockups: Array[products][surfaces][mockups].

The Preview and HiRes controllers operate in the same way as Editor.getProofImages and Editor.finishProductDesign.

Request Payload

These controllers take the same product definitions as in the IFrame API, substitute personalized data, and return URLs that link to rendered products. You can render a single product or a product group all at once. You can pass the following common data params in the POST request:

  • itemsData sets the content and properties of design elements.
  • productTheme binds color themes using IProductThemeConfig.
  • productThemeName binds color themes using a theme name.
  • productDefinitions defines an array of products based on IProductDefinition or state files.
  • userId sets the user ID.

Also, the Preview controller accepts previewOptions specifying the preview size, whereas the HiRes controller accepts hiResOptions specifying the rendering configuration.

PreviewOptions

The previewOptions object defines the size of proof images and their resizing mode through the following properties.

Property Possible values Default values
width number 500
height number 500
resizeMode "Fit", "Fill" "Fit"

You can define these parameters as follows:

JavaScript
inputData = {
    previewOptions: {
        width: 504,
        height: 360,
        resizeMode: "Fill" 
    },
    ...
};

HiResOptions

The hiResOptions object allows you to configure the rendering of hi-res outputs and define whether the controller generates URLs that link to proof images through the following properties.

Property Possible values Default values
renderProofImages boolean false
renderingConfig IHiResOutput null

You can define these parameters as follows:

JavaScript
inputData = {
    hiResOptions: {
        RenderProofImages: true,
        renderingConfig:{
            defaultHiResOuputRendering: {
                fileFormat: "pdf",
                dpi: 400
            }
        }
    },
    ...
};

ItemsData

The itemsData object allows you to apply properties to all product pages at once and separately on a per-page basis. Also, the itemsData object personalizes in-string placeholders through the placeholders property. This object complies with the following specification.

TypeScript
itemsData: {
    surfaces: {
        [surfaceName: string]: {
            [itemName: string]: itemData
        }
    },
    [itemName: string]: itemData,
    placeholders: {
        [placeholderName: string]: string;
    }
}

Here, itemsData may contain the following properties.

TypeScript
itemData: {
  image?: string;        // The path to images.
  opacity?: number;      // The opacity of design elements.
  text?: string;         // The content of text elements.
  leading?: number;      // The text leading.
  tracking?: number;     // The text tracking.
  font?: FontSettings;
  textAlignment?: TextAlignment;
  textVerticalAlignment?: TextVerticalAlignment;
  isVertical?: boolean;  // Whether the text is vertical.
  underline?: boolean;   // Whether the text is underlined.
  location?: PointF;
  size?: ItemSize;       // The width and height.
  color?: string;        // The color in a CSS-compatible format.
  borderColor?: string;  // The border color of design elements.
  borderWidth?: number;  // The border width of design elements.
  fillColor?: string;    // The fill color for shapes.
  altColor?: string;     // The alternate color for dashed lines.
  dashWidth?: number;    // The dash width.
  altDashWidth?: number; // The width of alternate dash lines.
  width?: number;        // The width of lines.
  sourcePoint0?: PointF; // The start point of lines.
  sourcePoint1?: PointF; // The end point of lines.
}

TextAlignment and TextVerticalAlignment allow you to align text elements. Using PointF, you can define item coordinates. To define font properties, you can use FontSettings.

TypeScript
FontSettings: {
  postScriptName?: string;
  size: number;
  fauxBold: boolean;
  fauxItalic: boolean;
}

To set up the size of items, use ItemSize. For text elements, this object defines the bounding rectangle.

JavaScript
ItemSize: {
  width: number;
  height: number;
}

All properties of itemsData are optional. Through different variations, you can define any design element supported in Customer's Canvas. The following table details the design elements and their properties that you can pass to the Preview and HiRes controllers.

Images, image placeholders, barcodes location, size, image, opacity, borderWidth, borderColor
Shapes, ellipses, rectangles location, size, fillColor, opacity, borderWidth, borderColor
Lines color, width, opacity, sourcePoint0, sourcePoint1
Dashed lines color, altColor, width, opacity, dashWidth, altDashWidth, sourcePoint0, sourcePoint1
Plain text location, text, font, underline, color, isVertical, textAlignment, leading, tracking
Curved text location, size, text, font, underline, color, textAlignment, leading, tracking
Bounded text location, size, text, font, underline, color, isVertical, textAlignment, textVerticalAlignment, leading, tracking
Path bounded text, auto-scaled text location, size, text, font, underline, color, isVertical, textAlignment, leading, tracking

All the numeric values are measured in points. If you do not pass any property that is appropriate to a design element, say text for bounded text, then the corresponding value from the design template remains unchanged.

Important

The sample below defines the API security key in JavaScript code. It could be highly insecure if it runs on a public site. However, you can use it this way in your admin panel, or just for demonstration purposes.

The Personalization Sample

The following sample illustrates how you can generate personalized proof images without loading the editor. Replace example.com in baseURL with the domain name of your site.

HTML
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
    <title>Proof Images API Test</title>
    <script type="text/javascript" src="https://code.jquery.com/jquery-2.2.0.js">
    </script>
    <script language="javascript">
    // Set a link to the Preview controller.
    var baseURL = "https://example.com/api/Preview/GeneratePreview";
    // Set a unique key for using the Web API.
    var apiKey = "ApiSecurityKey";

    // Define a function for obtaining links to proof images.
    var getProofImages = function() {
        // Set up the inputData to personalize the Name layer of the template.
        var inputData = {
            itemsData: {
                "Name": {
                    text: "John Wood",
                    location: { x: 30, y: 30 },
                    font: {
                        postScriptName: "ArialMT",
                        size: 40.5,
                        fauxItalic: true
                    },
                    color: "rgb(255, 0, 100)",
                    textAlignment: "center"
                }
            },
            productDefinitions: [{
                surfaces: ["businesscard_front", "businesscard_back"]
            }],
            userId: "default"
        };

        // Make the request.
        $.ajax({
            url: baseURL,
            type: "POST",
            headers: { "X-CustomersCanvasAPIKey": apiKey },
            dataType: "json",
            contentType: "application/json; charset=utf-8",
            data: JSON.stringify(inputData)
        }).
        fail(function (d) { console.log(d.statusText); }).
        done(function (d) {
            // List the URLs of the proof images.
            d.forEach(function (products) {
                products.forEach(function (surfaces) {
                    surfaces.forEach(function (links) {
                        console.log(links);
                    })
                })
            });
        });
    }
    </script>
</head>

<body>
    <h3>Get Proof Images</h3>
    <input type="button" value="Get" onclick="getProofImages()" />
</body>
</html>

Examples of Input Data

productDefinitions allows you to specify one or more products through IProductDefinition, which, in turn, allows for setting up the design location, mockups, spines, folding lines, crop marks, and safety lines. Here are several snippets illustrating possible use-cases and input data for this request. You can copy and paste them into the previous personalization example.

A proof image of an 8.5x11 inches flyer

JavaScript
inputData = {
    previewOptions: {
        width: 504,
        height: 360
    },
    productDefinitions: [{
        surfaces: [{
            designFile: "flyer",
            safetyLines: [{
                margin: 10,
                color: "green",
                altColor: "rgba(255,255,255,0)",
                stepPx: 5,
                widthPx: 1
            }],
            cropMarks: [{
                margin: 10,
                color: "red"
            }]
        }]
    }],
    userId: "default"
};

Personalization of in-string placeholders

The following example personalizes the [#Name] and [#Phone] in-string placeholders, the specially formatted strings.

JavaScript
inputData = {
    itemsData: {
        placeholders: {
            "Name": "John Wood",
            "Phone": "555-123-1234"
        }
    },
    productDefinitions: [{
        surfaces: ["businesscard_front", "businesscard_back"]
    }],
    userId: "default"
};

Personalization of color themes and images

For images, you can specify URLs starting from http:// or https:// and links to your public and user images through the public: and user: prefixes, correspondingly. For example, public:company_logos/aurigma.png applies the aurigma.png logo from the \company_logos\ subfolder of the public gallery folder.

In the following example, state files specify the product.

JavaScript
inputData = {
    itemsData: {
        "photo": {
            image: "https://example.com/centralview.jpg",
            opacity: 0.8,
            borderWidth: 1
        },
        "cornerImage": {
            image: "user:tower.jpg",
            size: {
                width: 100,
                height: 100
            }
        }
    },
    productTheme: {
        "mainColor": "rgb(32, 83, 69)",
        "altColor": "rgb(26, 47, 41)",
        "texts": "rgb(176, 143, 37)"
    },
    productDefinitions: [
        "044abd5e-da18-46ff-9053-b019b62baa77",
        "d6c67467-6a3a-466a-9945-288c94b698a3"
    ],
    userId: "default"
};

Proof images of an envelope with preview mockups

In this example, we personalize only the Front page of the two-page product.

JavaScript
inputData = {
    itemsData: {
        surfaces: {
            "Front": {
                "name": { text: "John Wood" },
                "address": { text: "4414 Hill Road, Perth, IL" },
                "zip": { text: "61701" }
            }
        }
    },
    productDefinitions: [{
        surfaces: [{
            name: "Front",
            previewMockups: [{ up: "envelope" }],
            printAreas: [{
                designFile: "envelopeDesign",
                designLocation: { X: 4.1, Y: 4.1 } 
            }]
        },
        {
            name: "Back",
            printAreas: [{
                designFile: "envelopeBack"
            }]
        }]
    }],
    userId: "default"
};

Responses

The Success Response

The following list shows examples of URLs generated by the Preview and HiRes controllers. As a successful result, this API can return the following URLs:

  • The preview URL of a one-page product.
    Status Code: 200 OK
    Content: [[["https://example.com/api/rendering/GetProofImage/default/preview_5603922333D0F6CB246F6AC20DC45552/0_0%5b504x360%5d.png"]]]	
    
  • The hi-res URLs of two products.
    Status Code: 200 OK
    Content: [{"HiResUrls":["https://example.com/api/rendering/GetHiResOutput/default/408693E1872EC277EA28E90E481B2F72/-1_-1.pdf"]},
              {"HiResUrls":["https://example.com/api/rendering/GetHiResOutput/default/4C042925C4A39E45F886D67B0DE5B4E5/-1_-1.pdf"]}]
    
  • The URLs of proof images and hi-res outputs for the previous two products.
    Status Code: 200 OK
    Content: [{"ProofImageUrls":[["https://example.com/api/rendering/GetProofImage/default/408693E1872EC277EA28E90E481B2F72/0_0.png"],
                                 ["https://example.com/api/rendering/GetProofImage/default/408693E1872EC277EA28E90E481B2F72/1_0.png"]],
               "HiResUrls":["https://example.com/api/rendering/GetHiResOutput/default/408693E1872EC277EA28E90E481B2F72/-1_-1.pdf"]},
              {"ProofImageUrls":[["https://example.com/api/rendering/GetProofImage/default/4C042925C4A39E45F886D67B0DE5B4E5/0_0.png"],
                                 ["https://example.com/api/rendering/GetProofImage/default/4C042925C4A39E45F886D67B0DE5B4E5/1_0.png"],
                                 ["https://example.com/api/rendering/GetProofImage/default/4C042925C4A39E45F886D67B0DE5B4E5/2_0.png"]],
               "HiResUrls":["https://example.com/api/rendering/GetHiResOutput/default/4C042925C4A39E45F886D67B0DE5B4E5/-1_-1.pdf"]}]
    

The Error Response

You can obtain the following error responses:

  • Status Code: 400 Bad Request
    Content: ProductDefinitions is required.
    
  • Status Code: 400 Bad Request
    Content: Image not found: https://example.com/centralview.jpg
    
  • Status Code: 403 Forbidden
    Content: Invalid Security Key
    

See Also

Manual