Configuration

Here, you will find all the parameters, events and methods on the PrintAppClient class. You can find a basic installation guide here. This is how to initialize a PrintAppClient:

const printAppInstance = new PrintAppClient({
    ...parameters
});

Parameters

Property	Type		Description
`domainKey`	String	-	Your store domainKey. You can fetch this from your Print.App Admin
`designId`	String	-	The id of the design you want your customer to edit. You can fetch this from the Designs page. Click the more icon and copy the design. That should also copy the designId into your clipboard. From your server, you can also list them with `GET /v2/designs`.
`designList`	Array of strings	-	A list of designId. This is only valid if you want your customers to pick from a list of designs you specify here. The first design is always loaded as default. If this is provided, you can omit the designId parameter
`designTemplate`	Object	-	An object describing a sample design source to display when the editor loads. This is optional and only required if you do not want to use a pre-generated designId. More details can be found at the end of this page
`projectId`	String	-	This is required if you want to load the editor to edit an existing project. Remember to also set the `mode` to `edit-project`
`mode`	String	-	The editor mode. Valid values are: `new-project`: The editor should create a new project using the designId as a template. `edit-project`: You want to edit an existing project. This requires a projectId to be provided
`custom`	Boolean	-	Set this to `true` to let the editor know it’s a custom installation
`autoShow`	Boolean	-	This is used to automatically launch the editor after it initializes, without the customer clicking a customize button.
`product`	Object	-	Your own details of the product the customer is designing, for example `{ id: 'sku-123', ref: 'cart-line-7f3a' }`. Saved with the project exactly as passed, and returned by the API, so your server can check that a project was made for the product being ordered. See Verify a project before fulfilling.
`userId`	String	-	Your id for the customer. Saved with the project and returned by the API as `userId`.
`userData`	Object	-	Customer details to save with the project: `id`, `name`, `email`, `phone`, `info`. Returned by the API as `userData`.
`customValues`	Object	-	Not saved with the project or returned anywhere. To attach your own data to a project, use `product`.
`langCode`	String	-	Default: `en` The language to load the editor in. This should be a two letter language code following the ISO 639-1 two-digit language codes. You will find a list of valid language codes supported by Print.App here

Methods

Name		Description
`showApp()`	-	Show the Print.App Editor
`closeApp()`	-	Close and hide the Print.App Editor
`addEventListener(eventType, function)`	-	Attaches an event listener to the Print.App Editor
`removeEventListener(eventType, function)`	-	Removes an eventListener from the Editor
`getBootStatus()`	-	How far the editor got in loading. See Checking how far the editor got.
`destroyApp()`	-	Remove the editor from the page: its frame, its message listener and its scroll lock.

Event types

Events are attached to the PrintAppClient after initialization using the addEventListener method.

const printAppInstance = new PrintAppClient({
    ...parameters
});

function readyFunction() {
    printAppInstance.showApp();
}
printAppInstance.addEventListener('app:ready', readyFunction);

EventType		Description
`app:validation:success`	-	Dispatched when the editor has completed its authentication process. This is the first action the editor makes before being ready to show any design or project. The store configuration is passed down to your event
`app:validation:failed`	-	Dispatched when the editor cannot validate the domainKey or the parameters passed are invalid
`app:ready`	-	Dispatched when the Editor has initialized and is ready to be shown
`app:saved`	-	Dispatched when the customer has clicked the submit button and a project is saved. Your function receives the project’s details, including its `projectId` and preview images: see The app:saved payload. `addToCart` is `true` when the design has Add to Cart on Save turned on. See Adding to the cart on save.
`app:closed`	-	The editor is closed
`app:display:changed`	-	Only in the Dialog Display Mode: dispatched when the customer expands the editor to full window or shrinks it back. A data object of `{ expanded: Boolean }` is passed to your function.
`app:boot:status`	-	Dispatched at each step of the editor loading, with the same object `getBootStatus()` returns. See Checking how far the editor got.

The app:saved payload

Your listener receives an event whose data describes the saved project:

printAppInstance.addEventListener('app:saved', ({ data }) => {
    console.log(data.projectId, data.previews[0].url);
});

Field	Type	Description
`projectId`	String	The saved project. Send it to your server with the order.
`mode`	String	`edit-project` once a project is saved.
`sourceDesignId`	String	The design the project was made from.
`previews`	Array	One `{ url }` per page: preview images of the design.
`saveForLater`	Boolean	`true` when the customer saved the design to finish later rather than submitting it.
`addToCart`	Boolean	`true` when the design has Add to Cart on Save turned on.
`orderData`	Array	`{ name, value }` pairs from objects marked Include in order details, for your cart line.
`userId`, `userData`		As passed when the editor was opened.
`launchData`	Object	As passed when the editor was opened.
`scene`	Object	Only when the design has a 3D Scene: the design rendered on it.
`records`	Number	Only for mail-merge designs: how many rows (copies) the order carries.
`canvas`, `items`	Object, Array	Only for gang sheets: the sheet size and its items.
`base64Previews`, `resources`, `design`		Only when you opened the editor with `exportBase64Previews`, `exportResources` or `exportDesign` set to `true`.

The event comes from the customer’s browser, so its contents are the customer’s to change. Before you fulfil an order, verify the projectId from your server: see Verify a project before fulfilling.

Adding to the cart on save

With Add to Cart on Save turned on in a design’s settings, the client presses the store’s Add to Cart button for the customer after the project is saved. It waits for every app:saved listener to finish first, so the project can be attached to the cart line before the add. A listener that does asynchronous work (posting the project to your server, say) must return its promise, or the add can happen before that work is done:

printAppInstance.addEventListener('app:saved', async event => {
    // returned, so the add waits for it
    await saveProjectToMyCart(event.data.projectId);
});

If your cart needs something other than a button press, take the add over. Just before it presses the button, the client dispatches a cancelable printapp:addtocart event on document. Call preventDefault() and do the add yourself:

document.addEventListener('printapp:addtocart', event => {
    event.preventDefault();
    const { projectId, data } = event.detail;   // data is the app:saved payload
    myCartPlugin.add({ projectId });
});

You can add this script to your store from the Custom JavaScript input in your store settings. If the client cannot find your Add to Cart button, set the Cart button selector in your store settings.

Checking how far the editor got

The editor loads in steps: the client fetches your store settings, adds the editor’s frame to the page, the frame loads, the editor sends its first message to your page, the client sends it your parameters, the editor validates with our servers, and then it is ready. When app:ready doesn’t arrive, getBootStatus() tells you which step it stopped at:

printAppInstance.addEventListener('app:boot:status', ({ data }) => {
    console.log(data.stage, data.stalled);
});

// or at any moment
console.log(printAppInstance.getBootStatus());

The status holds counts and timings only, never your keys, settings or message contents, so you can log it or send it to us as it is.

`stage`	Meaning
`settings`	The client is fetching your store settings from `run.print.app`.
`loading`	The frame is in the page; its editor page is loading.
`loaded`	The frame has loaded; the editor has not sent its first message yet.
`announced`	The editor reached your page and was sent your parameters; it is validating.
`validated`	Validation succeeded.
`ready`	The editor is ready to show.
`failed`	Validation failed. `validationReason` says why, for example `domain mismatch`.

When a step takes longer than 10 seconds, stalled says which one, and the client logs a warning in the console:

`stalled`	What to check
`load`	The editor page never loaded. Check that `editor.print.app` resolves and is reachable from this network (DNS, a proxy or a content filter).
`unreachable`	The frame shows the browser’s own error page: `editor.print.app` did not answer this page. Check DNS, proxies, content filters and your page’s Content-Security-Policy.
`announce`	The editor page loaded but never reached your page. A browser setting or privacy extension that strips referrers stops it, as does anything blocking the editor’s scripts.
`validation`	The editor started but could not validate. It connects over a WebSocket to `*.execute-api.eu-west-1.amazonaws.com`: check for a blocked WebSocket in the editor frame’s network requests.

The other fields:

Field	Description
`startedAt`	When the client was created (UTC). Send it to us with your IP address if you need us to look an attempt up.
`settings`	`loaded`, `passed` (you gave `settings` yourself) or `unavailable` (the client carried on with defaults).
`frame`	`inserted`, `src` and `referrerPolicy` of the editor’s frame.
`loads`, `announces`, `configsSent`, `validations`, `readies`	How many times each step happened. Each editor page counts once, and opening a design made in PrintFx switches the frame to a second page, so these can reach 2. `validations` counts successful validations.
`validation`, `validationReason`	The last validation result (`success` or `failed`) and, for a failure, the editor’s reason.
`elapsed`	Milliseconds after `startedAt` at which each step last happened.

Loading the editor without a designId

This feature allows you to initilize the editor without having an prior design, by describing a design template. The parameter to pass unto the editor is an object titled designTemplate A sample value is shown in the code below with detailed comments.

designTemplate: {
	// design unit. possible values are: cm, mm, in, pt, px, ft
	"unit": "cm",

	// an array of pages in the design
	"pages": [
		{
			// page dimensions, bleed and other info
			"width": 20,
			"height": 22,
			"bleed": 0.5,

			// background color
			"background": "transparent",

			// underlay image url
			"underlay": "",

			// overlay image url
			"overlay": "",

			// page margins (if you provide an underlay)
			"offsets": {
				"top": 4,
				"left": 5.6,
				"right": 5.6,
				"bottom": 1.5
			},
		}
	]
}

REST API (v2)

Guides

Endpoints

Editor

Parameters

Methods

Event types

The app:saved payload

Adding to the cart on save

Checking how far the editor got

Loading the editor without a designId