Step By Step

Modified on 2013/06/11 20:18 by jdibble — Categorized as: Uncategorized

Step by Step Integration Guide

Quick Links

Step by Step Integration Guide

This documentation seeks to provide step-by-step overviews of how to integrate with ezprints. This documentation is not meant to be used as finalized code that should not be edited. In fact, this is meant to be an overview of the integration paths. You should edit all of the code samples to suit your needs. The included code reflects the simplest way to integrate the builder. There are more advanced function calls described in the Builder Commerce Guide. The functions and parameters in the deployment guide which were excluded from this page are more rarely used, which is why they are not included here.

If you are unsure which integration path your company will use, please consult with your Cafepress Services sales representative or ask the business owner at your company.

ezp Builder + Fulfillment

The first step for adding personalized products to your site is to determine how they will be marketed. Although the ezp Builder will handle the product configuration, the manner in which your users learn that you offer personalized products is up to you.

Many partners set up a "product detail" page or pages, in which the products you plan to offer are described and displayed. This helps your users gain a better understanding of the types of products that are available and what they will look like. Ideally, users would reach the product detail pages from the main navigation on your site, or via a clearly identified link or ad tile.

The product detail page(s) will connect to the ezp builder. After you've determined the user flow, create a blank page on your site which will host the ezp builder.

The steps below can be done on a local computer that is set up as a web server, or on your web server.

STEP: Create an HTML page 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>

STEP: Copy the following code immediately above the closing </head> 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>

STEP: Copy the following code next. Note that in the code below, many lines or portions of lines are commented out with // or /* and */. A description of the purpose for each line is below the sample code and identified in the code with a (number). You can determine which of the parameters you want to use and uncomment those lines by removing the // or /* and */. You can also remove the description notations after deploying the code. Note that this is a full code example and you may choose not to use many of these functions.

<script type="text/javascript">
	/* NEEDED IN ITEM (18) BELOW
	var initialPhotoObject = ({
		id: "1234",
		screenResUri: "http://ezpservices.com/Assets/Artwork/Utility/SampleSource/Stock/preview/6863946_00000_preview.jpg",
		printResUri: "http://ezpservices.com/Assets/Artwork/Utility/SampleSource/Stock/full/6863946_00000_thumb.jpg",
		PrintResWidth: 1000,
		PrintResHeight: 1000
	 });
	*/
	var app = ezp.apps.createTemplateApp({
		elementId : 'appDiv',    // (1)
		width : 900,    // (2)
		height : 700,    // (3)
		sku : '10101',   // (4)
		// showMerchandising: false, // (5)
		// templateId: '70200-5X7FULLBLEED',  // (6)
		// initialPhoto: initialPhotoObject, // (18)
		mediaPickerSources :    // (7)
		["EZP Services", {
			id : "1",
			title : "Personal Albums"
			,iconUri: "http://apps.ezprints.com/mars/2.0/content/assets/icon-ezprints.png"
                        ,collectionsUri: "http://apps.ezprints.com/Assets/Artwork/Utility/SampleSource/Source.xml"
		}],
		comboTrayInitialAssetCollectionUri : "http://ezpservices.com/Assets/Artwork/Utility/SampleSource/Stock/StockAlbum.xml",    // (8)
		readyCallback : true,   // (9)
		// templatesUrl: "http://apps.ezprints.com/mars/2.0/content/fullbleedtemplates.xml", // (10)
		addToCartCallback : addToCartComplete // (11)
	});
	function addToCartComplete(projectId, productSku, thumbUrl) // (12)
	{
		//alert("The project was saved with project id " + projectId + " and the sku " + productSku);
		//alert("A thumbnail was saved for this project at this url: " + thumbUrl + ".");
	}
	/* // (13)
	 function setImage(photo)
	 {
	 app.setPhoto('http://ezpservices.com/Assets/Artwork/Utility/SampleSource/Stock/preview/6863947_00000_preview.jpg');
	 }
	 */
	/* // (14)
	 function changeTemplate(sku, templateId)
	 {
	 app.setSku('70210', 'Sailannounce_5x721');
	 }
	 */
	/* // (15)
	 function loadPID(projectId)
	 {
	 app.load("ac68af39-009a-4e77-b235-3275987494ff");
	 }
	 */
	/* // (16)
	 function changePhotoDetail(myMediaObject)
	 {
	 app.setPhoto(myMediaObject);
	 }
	 var myMediaObject = ({
	 id: "1234",
	 screenResUri: "http://ezpservices.com/Assets/Artwork/Utility/SampleSource/Stock/preview/6863946_00000_preview.jpg",
	 printResUri: "http://ezpservices.com/Assets/Artwork/Utility/SampleSource/Stock/full/6863946_00000_thumb.jpg",
	 PrintResWidth: 1000,
	PrintResHeight: 1000
	 });
	 */
	/* // (17)
	 function changeSku(sku)
	 {
	 app.setSku(sku);
	 }
	 function changePhoto(photo)
	 {
	 app.setPhoto(photo);
	 }
	 */
</script>

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

<div id="appDiv">
	<a href="http://www.adobe.com/go/getflashplayer">
		<img src="http://www.adobe.com/images/shared/download_buttons/get_flash_player.gif" alt="Get Adobe Flash player" />
	</a>
</div>

OPTIONAL STEP: If you are passing images to the builder, either because users already have images on your site or because you are supplying the images for users to order, then you need to set up a cross-domain policy file to allow "apps.ezprints.com" to access your media. If you do not plan to pre-load images for the user (if users will upload their own images), you can skip this step.

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.

VERIFY: At this point, you should be able to see the application running on your site! Please view your page in a browser to confirm.

You now have a lot of code on your page that you may or may not want or need. Each photo site is different, so you will need to edit/remove code to fit your site. An explanation of each of the parameters and functions is listed below:

1 The elementId value in the createTemplateApp function should match the div id value for the div tag in your page. In the example code above, these values match, so you can leave this portion untouched.

2 The width of the builder is listed in pixels. This value is configurable and should be changed to fit the look and feel of your site. Note that increasing the width of the builder will make the design area larger, which will benefit your customers as they'll be able to more easily visualize the products they are configuring. Also note that the minimum width for photo books and calendars is 900px wide. All other products will work at 700px wide or greater.

3 Like the width of the builder, the height is also configurable. Depending on where the builder is placed on your site, make the builder as tall as possible to maximize the design area. Try to avoid positioning the builder or setting the height such that the template well (at the bottom) of the builder is below the fold, which will force your users to scroll.

4 The builder must launch with a particular product/sku identified. To change the product displayed in the builder, change the value in this parameter. If you want to dynamically change the product based on user selections outside the builder or on a previous page, the functions you write accomplish this can be called in this parameter. For example, sku: getSku would call a function called getSku to retrieve the sku the builder should load.

5 Currently, ezprints offers a merchandising module for photo books only. If you are not offering photo books on your site, you can remove this parameter. If you are offering photo books, including this parameter and setting the value to true instead of false will load the builder with the merchandising module, if a photo book sku is used in the sku parameter. The merchandising module allows users to select product options, such as color, text, designs, and sizes before they start configuring a product. ezprints is making the merchandising module more robust, such that it will be used for other products in the future. Setting the showMerchandising parameter to true will not cause problems for other products where merchandising is not available, so you can leave this parameter in your code for all products if you are using it for photo books.

6 If you want to launch the builder with a specific template selected, you can specify the templateId here, or you can use the setSku function described below. For more details about the templates ezprints offers, visit the ezpservices bundles page. The templateIds are listed in the templates XML files. The paths to the template XML files are listed in the builder documentation here.

7 The media picker, which is integrated into the builder, is used for a few different purposes. The media picker will allow users to upload photos from their computer or retrieve photos from your site. In the future, the media picker will also have the ability to retrieve photos from open third-party sources. The sample code above passes some sample photos to the builder and allows users to upload photos in the builder. To disable photo upload so only photos passed to the builder are available to the user, change the mediaPickerSources parameter to this:

mediaPickerSources: 
	[{id: "1", 
	title: "Personal Albums"
	,iconUri: "http://apps.ezprints.com/mars/2.0/content/assets/icon-ezprints.png"
        ,collectionsUri: "http://apps.ezprints.com/Assets/Artwork/Utility/SampleSource/Source.xml"
}],

If you want to allow users to upload photos in the builder, but you do not plan to pass any pre-existing photos to the builder, change the mediaPickerSources parameter to this:

    
mediaPickerSources: [
	"EZP Services"
],

If you plan to pass photos into the builder using the setPhoto function below, and you do not want users to upload their own images, remove the mediaPickerSources parameter (including everything in the square brackets) and the comboTrayInitialAssetCollectionUri parameter.

Note that the examples above use "EZP Services" as the upload source. This functionality is integrated into the builder, which will make your development efforts much easier. However, photos uploaded by the user are not added back to any albums that are stored on your site. Uploaded photos are stored on Cafepress Services servers and are available to users for their current ordering session only. If users leave the site and come back the following day, their uploaded photos will no longer be there. You should consider these uploads as transactional, in the sense that they are only available for the current ordering session.

8 The comboTrayInitialAssetCollectionUri parameter should always be present if you plan to have a media picker of any type. The configurable portion of this parameter is what appears between the quotes. Use "EMPTY" if you do not want to load the builder with any photos set initially. If you want to pass an initial set of photos to appear in the photo well, use a collections XML file. More information about using collections XML is loaded in the Builder Commerce Guide, in the mediaPickerSources parameter section.

9 The readyCallback event fires when the builder loads the first time and is ready for use. If you want to specify a function to run after the builder loads (like setSku or setPhoto), use this parameter. For a basic installation example, leave the sample code as is.

10 ezprints offers a variety of templates that are integrated into the builder. For more details about using templates, see the the builder documentation here. Leave this parameter commented out to take advantage of every template that ezprints offers.

11 Including the addToCartCallback parameter enables the "Add to Cart" button inside the builder. This parameter specifies the function to be called when the user clicks the button.

The functions labeled (13) through (17) are optional and you can remove them from your code if do not plan to use the functionality described.

12 To set a particular image in the builder after it loads, call the setPhoto function.

13 To change the sku and/or the template selected after the builder loads, use the setSku function.

14 The builder can load a ProjectId that was previously generated. To load a ProjectId, use the load function.

15 The setPhoto function can be more robust that what was described above. To include more details about the photo, including the screenResUri, the printResUri, the PrintResWidth, and the PrintResHeight, use the setPhoto example as shown in the example.

16 You can now set the photo the builder initially loads with. The passed in object is the same as what can be passed to the setPhoto call.

VERIFY: At this point, you should be see a fully functioning product builder with sample images. You should be able to run this page in a browser, choose a photo, add your product to your cart, and complete the checkout process and post the order to our systems. Your account is initially in test mode, so orders are not produced and shipped.

ezp Fulfillment Only

If you are not using the ezp Builder or ezp Commerce, you are responsible for the end-to-end user experience on your site. You probably already have a user flow established, or at least mapped out. In case you are just starting, the first step for adding personalized products to your site is to determine how they will be marketed and displayed to the user.

Many partners set up a "product detail" page or pages, in which the products you plan to offer are described and displayed. This helps your users gain a better understanding of the types of products that are available and what they will look like. Ideally, users would reach the product detail pages from the main navigation on your site, or via a clearly identified link or ad tile.

The product detail page(s) could connect users to a page where they will either choose or configure their products. After choosing or configuring products, users will need to go through your shopping cart to complete their transaction. After completing a transaction through the cart, you are ready to construct the ezprints order XML and post to the ezprints order API.

Details about the ezprints order XML schema are in the XML Specifications section under the Integration Guide. Full details for how to post order XML are in the Integration Guide.

We do offer some sample code for assisting with the process, in our code samples section.

Your account is initially in test mode, so you should post as many orders as you want until you are consistently receiving a reference number in response to your post. Additional details about where to post your XML are in the Integration Guide. After you've successfully posted orders to the ezprints order API, you're ready for some of your orders to be printed and shipped so you can verify the product quality and packaging. Email your Integration Manager for more details.