Builder Commerce Guide

Modified on 2015/11/03 16:02 by jdibble — Categorized as: Uncategorized

ezp Builder Integration

Quick Links

EZP Applications Overview

This guide covers the process of installing ezp Builder into your website quickly and easily. It also goes into the details of the extensive API so that you can get the most out of your integration. Please note that this document is aimed at web developers with some HTML and JavaScript knowledge.

Basic Requirements

Installing and using ezp Builder is very simple, in many cases the modules can be installed by simply adding a few lines of JavaScript code to an HTML page. The application runs in the Adobe Flash runtime and thus will work in any web browser that supports Flash. ezp Builder currently requires Flash 10.3 and it will take care of detecting the flash version and suggesting an upgrade if necessary – you do not need to do any work to detect flash outside the builder. Running the builder in an iframe is not recommended.

How long does it take to integrate?

Our applications are designed to be embedded into a web page on your existing site. Integration time will vary depending on how much you want to customize. The most basic integration can be complete in minutes and a complete customization typically takes less than a day. In some cases you may wish to configure your website with new products or photo handlers that pass photos into the builder. In these cases integration may take longer. The ezprints team is always eager to help so if you run into problems please email your integration support contact.

Getting a Deployment Key

Our applications require a deployment key to run in a production environment. The deployment key allows you to have custom settings for each website where you deploy the builder. To obtain a key simply email your integration support contact.

What products are available in the builder?

Nearly every product that ezprints produces is available in the ezp Builder. As you will see below, to launch the builder with a particular product loaded, you pass a SKU to the builder. All the available SKUs are included in the Product Specifications Guide. However, there are a few exceptions and a few tweaks required to the SKUs in the Guide. Most notably, the correct SKUs for mugs are:

SKUDescription
10102T11oz Mug, White
1019011oz Mug, Black
10112T15oz Mug, White

When using our builder, full-bleed mugs and mugs with multiple images are handled through the use of templates, instead of separate SKUs.

There are also some Cafepress Services products that are not currently available in the builder:
For questions about available products, please contact your sales representative.

Best Practices

Before you get started review these best practices for deploying our applications.

Use medium resolution images

Why: Speed matters – customers buy more when the process is fast and easy. On ezprints.com our medium resolution files are about 100 Kb, these download 20 times faster than a full resolution 2 Mb photo.

How: Use images th#_600 pixels wide and use the printResWidth and printResHeight parameters to tell us the resolution of the full resolution image. More details about these parameters are listed below.

Use the media picker when multiple photos are available

Why: The media picker is very customizable and allows your customers to quickly find photos use drag and drop to place them onto the product.

How: The media picker is initialized in your create call and takes simple XML. See the complete documentation in the API Reference under the createTemplateApp function.

Use the built in upload functionality

Why: Customers often shop before they upload. Using the upload functionality in ezp Builder increases conversion by keeping customers in the ordering flow with a product they have already chosen.

How: Just tell the builder what URL on your site to post to and what parameters to pass with the upload. If you are using the media picker the builder will send the current collectionId as a field in the POST. See the complete documentation in the API Reference under the createTemplateApp function.

Make it bigger

Why: ezp Builder will scale the edit area to fill up all the room that you give it. Customers like to see the details of the product they are building and preparing to buy. A larger preview allows customers to see more detail which increases their confidence that they will get what they want.

How: The createTemplateApp call allows you to pass in the width and height you would like the builder to appear. Increase these until you get the look you want. More details about the createTemplateApp call are below.

Use the built in "Add to Cart" button

Why: The built in "Add to Cart" button is a highly visible call to action designed to help drive conversion. It also checks to make sure the project is complete and will provide instructions to the user if the need to do more to complete their project.

How: Simply add "addToCartCallback" as a parameter in you create call. We will return the projectid, sku, and thumburl to your callback function.

Call your external functions using the readyCallback parameter

Why: The readyCallback parameter is the truest measure of when the builder is loaded.

How: Simply add "readyCallback" as a parameter in your create call. Specify additional functions you'd like to run after the builder loads, such as setSku or setPhoto.

Display product thumbnails in your cart

Why: The addToCartCallback will return the Project ID, the SKU, and a thumbnail-resolution version of the product that was created. Displaying this to users in your shopping cart will help to increase conversion.

Let users upload their own photos

Why: Even if you have user albums on your site, users always have new photos that they might forget about until they're in the builder. Let them upload the photos while they're creating their products.

How: By using the new version of the media picker (above), you can automatically allow photo uploading by specifying your upload URL or adding “EZP Services” as an upload source.

Recommendations and Live Deployment Examples

Check out some existing websites that have the ezp Builder. ezprints, and ezpservices

Here are some recommendations on ways to incorporate personalized products onto your website.

Deployment Example

Deployment Example

Basic Installation Example

Copy this simple 4 step example to setup ezp Builder an environment that you can play around with. This can be done on your local computer or on a web server.

  1. Create an HTML document where you can install the builder. Here is a sample:

    <html xmlns="http://www.w3.org/1999/xhtml"> <head> <title>Your Page Title Here</title> </head> <body> <h2>Simple Installation Example</h2> <p> Please use your browsers <b>View-Source</b> feature to see the code. </p> </body> </html>

  2. Copy the following code immediately above the tag. Note that you need to replace "demo-builder-key" with the deployment key you received from your integration contact.

    <script type="text/javascript" src="http://apps.ezprints.com/home/demo-builder-key.ezp"></script>


    <script type="text/javascript">// fires when the application is ready for usevar readyHandler = function() {}var app = ezp.apps.createTemplateApp({elementId : 'appDiv',width : 750,height : 600,readyCallback : readyHandler});

    </script>

  3. Copy the following code onto your web page where you would like the app to appear.

    <div id="appDiv"></div>

  4. Setup your cross-domain policy file to allow "apps.ezprints.com" to access your media.

By default, Flash applications cannot access images and other media that is hosted on other web sites without receiving explicit permission to those resources. This permission is given using a cross domain policy file. To give apps.ezprints.com permission to access your media, save the following into a file called crossdomain.xml.

<cross-domain-policy>
	<allow-access-from domain="apps.ezprints.com"/>
</cross-domain-policy>

Make sure that the resulting crossdomain.xml file is available at the root of your website. For example, if your site is site.com, the cross domain policy file should be available at site.com/crossdomain.xml.

There are more advanced aspects to the cross domain policy file. To learn more on cross domain policy files please visit the following link: http://livedocs.adobe.com/flex/3/html/help.html?content=security2_04.html.

At this point, you should be able to see the application running on your site! Next we will discuss how to interact with the application using the JavaScript API.

API Reference and Examples

Our API gives you the power to interact with and customize the applications to your specifications. In this section, we will go over the details of the API with examples. Required fields are denoted with a red asterisk (*).

Including ezp Builder

You need to include a reference to our JavaScript on every page where you want an ezp application to run. This script contains the JavaScript API and flash detection code. You will need to use the deployment key issued to you by Cafepress Services. If you need a key simply email your Cafepress Services integration contact.

<script type="text/javascript" src="http://apps.ezprints.com/home/Your Deployment Key.ezp"></script>

Customizing ezp Builder

In step 2 of the Basic Installation Example above, you added the createTemplateApp function to your page. The createTemplateApp function takes many parameters that allow you to customize ezp Builder to fit your site.

ezp Builder Functions

createTemplateApp

Function: ezp.apps.createTemplateApp(config: Object) – Creates an instance of the application.

Returns: An instance of the application.

Parameters


setPhoto

If you are using the photo well inside the builder you will not need the setPhoto function. This is provided when the builder is used for products that only take a single photo and the photo is chosen outside the builder.

Function: setPhoto(photo: Object) – sets the current photo region's photo.

Parameters


getCurrentProduct

Function: getCurrentProduct() – returns a simple object containing the current product.

Returns: A JavaScript object containing the product id, name and sku, all with type String.

Parameters: None

Example: Gets the current product in a JavaScript object and displays a message with the details.

var myProduct = myApp.getCurrentProduct();
alert("ID: " + myProduct.id + ", Name: " + myProduct.name + " Sku: " + myProduct.sku);
Remarks: None

save

Function: save(size) – asynchronously saves the project.

Returns: By way of an asynchronous callback, returns to the saveCallback function defined for the current application instance, a projectId String and a thumbnailUrl String.

Parameters:


getProjectInfo

Function: getProjectInfo()

Returns: projectInfo Object with three properties: requiredPhotoRegionsCompleted, requiredTextRegionsCompleted, and pageCount. The requiredPhotoRegionsCompleted and requiredTextRegionsCompleted properties will be "true" if all required regions in the product or template have been filled in. By default all photo regions are required and all text regions are optional. The pageCount property returns the total number of pages in a project. This is useful for photobooks when you need to know the number of extra pages to charge for. To get the number of extra pages subtract this number by 20.

Parameters: None

Example:

function getProjectInfo()
{
var projInfo = widget.getProjectInfo();
alert("required photos completed? " + projInfo.requiredPhotoRegionsCompleted);
alert("required text completed? " + projInfo.requiredTextRegionsCompleted);

// for photobooks use this to get the number of extra pages
var numExtraPages = (projInfo.pageCount - 20) > 0 ? (projInfo.pageCount - 20) : 0;
alert("number of extra pages? " + numExtraPages);
}
Remarks: getProjectInfo can be used to get a javascript object with valuable statistics about the project. More stats will be added over time, but for now, the two pieces of information available are requiredPhotoRegionsCompleted and requiredTextRegionsCompleted which are Boolean values indicating completion of photo and text regions respectively.

load

Function: load(projectId: String) – asynchronously loads the specified project.

Returns: None, but does call the loadCallback function defined for the current application instance so that further action can be taken upon a successful load.

Parameters: None

Example:

myApp.load('123456-7890-abcd-ef12-34567890abc');
Remarks: None

setSku

Function: setSku(sku: String) – sets the current sku visible in the application.

Returns: Not Applicable

Parameters:


previewMode

Function: previewMode(Bool) – toggles the view of the builder from preview mode to edit mode.

Returns: Not Applicable

Parameters:


createPrintsBuilder

Function: ezp.apps.createPrintsBuilder(config: Object) – Creates an instance of the prints builder version of the application. This version allows for customers to order multiple full prints in different sizes as a single project. The config object is the same as that for createTemplateApp.



Adding Photo Books

The minimum width and height for the builder when offering Photo Books is 900px wide and 600px high.

Additional Web Services

In addition to the javascript API, we offer web services for advanced integration with builder data.

Session Service

The session service provides access to manually and automatically saved projects.

Fulfilling Orders: Posting Order XML to EZ Prints

If you are an existing partner who is currently posting order XML to ezprints or if you are a new partner who is using the ezp Builder, you will need to make a few changes to the standard ezprints order XML schema. This section describes those changes.

Updating Your Order XML: In the standard ezprints order XML schema, you specify a productid (SKU#) and crop settings for each orderline. You also specify an imageid, which references a specific image in the images node of your order XML. The ProjectId attribute generated by the ezp Builder takes care of all those details for you. The ProjectId is the return value of the save() API call you will need to store in your systems, and pass back to us when posting your order XML. The ProjectId is stored at ezprints and tells us everything we need to know about the product being produced. As a result, if you are using the ezp Builder, you can omit the following elements and attributes from your orderline node in your order XML: imageid, crop, productid, and productid2. Note that you still need to include a quantity, along with the rest of the order XML.

An example of order XML from a partner using the ezp Builder:

<orders partnerid="x" version="1">
	<ordersession>
		...
		<order>
			...
			<orderline ProjectId="aaaa-1245-cccc-a0aa-b6gsj-11111">
				<quantity>1</quantity>
			</orderline>
			...
		</order>
		...
	</ordersession>
</orders>

Automatic Content Replacement: For security and performance reasons, it often makes sense to withold your print-quality resolution image client side instead of passing it to the application. In such cases you will need a method to swap out the screen resolution image with a larger, print ready version at order time. All you have to do is add the ReplacementContent element on the orderline node as shown below.

...
<orderline ProjectId="aaaa-1245-cccc-a0aa-b6gsj-11111">
	<ReplacementContent>
		<!- - Method 1: Replace using a URI -->
		<Replacement Uri="http://www.my-domain.com/12345_for_screen.jpg" 
			ReplacementUri="http://www.my-domain.com/12345_for_print.jpg" />
		<!- - Method 2: Replace using an ID (passed using the "setPhoto" call -->
		<Replacement Id="23456"	ReplacementUri="http://www.mydomain.com/12345_for_print.jpg "/>
	</ReplacementContent>
	<quantity>1</quantity>
</orderline>
...
To determine what images are in use in a project, a web service is available that can be called with the ProjectId that will return all of the user's media content. The web service is available at http://apps.ezprints.com/service/2.0/Project.asmx. The data can alternately be retrieved at http://apps.ezprints.com/service/2.0/Project.asmx/GetContentForProject?ProjectId=ABCD where "ABCD" is the project id of the project for which data is being requested.

Back Printing: Our regular prints allow an image title to be printed on the back. Our systems support a maximum of 40 characters. We support all alpha-numeric characters, parenthesis, dashes, and underscores. All other characters will be changed to underscores. If a back-print is desired, when using ezp Builder (or any project or template-based product that does not include an imageid attribute on the orderline element), the back-print information, if desired, should be provided in an attribute called "backprint" on the orderline element, as is shown below. 

...
<orderline ProjectId="aaa-145-ccc-a0a" backprint="appears on the back of the print">
	<quantity>1</quantity>
</orderline>
...