API Version: 1.0

Overview

The Personalise-iT integration covers how to embed a Custom Gateway personalisation app into your platform.

Requirements

  • A unique company reference ID (provided by Custom Gateway)

Embedding Your App

All Custom Gateway personalisation apps are accessed via a URL which can be embedded into an iframe.

There are currently two types of URL and which one should be used depends on the app.

Distributed App URL

Starting from June 2016, many apps will run on Custom Gateway’s globally distributed apps platform, which allows both dynamic and static content to be served from a location that is closer to your users with no dependency on our main UK based servers.

The following is an example of a typical URL for a distributed app:

https://g3d-app.com/s/app/pluto/en_GB/default.html#p=1007644&r=2d-canvas

Note that Custom Gateway do offer select customers the ability to have their own self hosted distributed app and therefore the URL hostname may vary.

Legacy App URL

The following is an example of a typical URL for a legacy app:

https://app.gateway3d.com/acp/app/?l=pluto#p=1007644&r=2d-canvas

URL Parameters

The functionality of the personalisation apps can be configured via a variety of additional URL parameters.

Parameter Name Description
c Configuration Specifies an app configuration to use.
lo Locale Specifies which locale to use.
r Renderer Specifies which renderer to use.
p Product Specifies which product to load.
guid Company Ref ID Specifies an account code which is used to route the order.
ep3dUrl Add To Cart Callback Specifies a callback URL for adding to cart.
epa External Pricing API Specifies a URL to use for pulling pricing information into the app.

Configuration & Locale

The way in which configuration and locale are specified depends on the type of app.

For legacy apps with URLs of the form https://app.gateway3d.com/acp/app/?l=pluto#p=1007644&r=2d-canvas, both c and lo need to appear before the fragment part of the URL (which is delimited by #). For example:

https://app.gateway3d.com/acp/app/?l=pluto&lo=de_DE&c=abcdefghijkl#p=1007644&r=2d-canvas

For distributed apps, the value of c and lo are included as part of the path and must always be present. For example:

https://g3d-app.com/s/app/pluto/de_DE/abcdefghijkl.html#p=1007644&r=2d-canvas

Warning A future development for distributed apps may move the lo parameter to the fragment part of the URL:

https://g3d-app.com/s/app/pluto/abcdefghijkl.html#p=1007644&r=2d-canvas&lo=de_DE

Renderers

There are several types of renderer. Not all are supported by every app.

Code Name Product Type
2d-canvas 2D renderer using the HTML Canvas element 2D Only
webgl 3D render using WebGL 3D Only
svg 2D renderer using SVG 2D Only
html 2D renderer using standard HTML 2D Only
flash Legacy Flash renderer (obselete) 3D Only
multi Loads both the 2d-canvas and webgl renderers 2D and 3D

General Recommendations

  • Give your administrative users the ability to explicitly set an entire personalisation app URL against a product in their store. This saves on any headaches in the future if the structure of URLs change.

  • Hide the epa and ep3dUrl parameters from your administrative users, they should be added automatically by your software.

  • Allow for multiple personalisation app URLs to be set against a product and determine which one to use based on browser capability. For example it may be advisable to only show mobile uses a 2D version of a product with a 2D renderer.

Adding to Cart

All Personalise-iT personalisation apps will have some form of button that allows the user to confirm that they are happy with their design and then add their item your website’s shopping cart.

Once the user has clicked such a button, two things will happen in sequence:

  • A print job will be created using the unique company reference ID that was passed via the guid parameter. The print job is created on the Personalise-iT cloud infrastructure and contains all of the information needed to recreate the user’s design as a piece of high resolution artwork.

  • The app will make a POST request to a specified 3rd party callback URL.

Your Callback URL

The callback URL is be specified via the ep3dUrl URL parameter, for example:

https://g3d-app.com/s/app/pluto/en_GB/default.html#p=1007644&r=2d-canvas&ep3dUrl=http://my-site.com/personalise-it-callback.php

Warning If your callback URL contains any special characters (such as ? or &) please ensure that it is encoded according to RFC 3986. In PHP this can be accomplished using rawurlencode().

For legacy reasons there are two different POST mechanisms used (which one depends on which app, which software version and which renderer are being used):

  • A raw JSON POST that will have a content type of application/json.
  • A standard HTML form POST with a content type of application/x-www-form-urlencoded. A single field (data) will be passed which contains a JSON encoded object.

Using PHP, both types can be easily handled as follows:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
<?php

$type = $_SERVER['CONTENT_TYPE'];
 
switch($type)
{
	case 'application/json':
		$json = file_get_contents('php://input');
		break;
 
	case 'application/x-www-form-urlencoded':
		$json = $_POST['data'];
		break;
 
	default:
		throw new Exception('Invalid content-type');
}
 
$data = json_decode($json);

The JSON encoded object will contain the following key fields:

Name Type Description
printJobRef string The print job’s unique alphanumeric reference. This reference will be no more than 30 characters and needs to be stored by your platform and passed to the Order-iT API at a later stage.
thumburl string A URL to a thumbnail of the user’s design. The URL is not permanent, it is recommended that the image is downloaded and stored by your website for future use.
quantity int Only populated when the app has been loaded with an external pricing API URL set (see below).

Your callback URL will be opened within the same iframe that the personalisation app was running. After your callback has done any necessary processing (for example adding the product to your cart system), the iframe can be broken out using JavaScript, for example:

1
window.top.location = "http://example.com/yourcart";

External Pricing API

Some personalisation apps provide the ability to show product information (such as pricing) as well as allowing the user to input a purchase quantity. Such information is pulled from an external URL (i.e. your website) and is known as the External Pricing API.

EPA has two modes of operation.

Single Product Mode

In single product mode (when the app does not have a product menu enabled), the URL specified by the epa parameter is simply called by the personalisation app. Therefore it is possible to use a different URL for each product in your system (i.e. by changing a parameter). For example:

http://my-website.com/epa/product/83663

Where 83663 is a unique identifier for the product in your system, allowing you to determine which information to return.

Multi Product Mode

In multi product mode (when the app has a product menu enabled), the app will take the EPA URL and append an SKU parameter to the end of it before retrieving any information. For example:

http://my-website.com/epa/product/

Will become:

http://my-website.com/epa/product/?sku=MYSKU

The value of the sku parameter will be the SKU of the product that was selected by the user. The SKU comes from the Custom Gateway Custom Product Platform database and is typically the supplier’s SKU.

If both modes, the product information is retrieved via a JSONP API, the URL of which is passed to the app via the epa URL parameter.

The EPI API must return a JSONP encoded object with the following fields:

  • price
  • name
  • description

For example:

1
2
3
4
5
callback({
	'price': '£3.99',
	'name': 'iPhone 6 Case',
	'description': 'A stylish case for your iPhone'
});

This could be achieved in PHP as follows:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
<?php 
 
$callback = $_GET['callback']; 
$callback = preg_replace("/[^0-9a-zA-Z\$_]/", "", $callback); // XSS prevention
 
$price = "£3.99";
$name = "iPhone 6 Case"; 
$description = "A stylish case for your iPhone";
 
$json = json_encode(array('price' => $price, 'name' => $name, 'description' => $description)); 
$jsonp = "{$callback}({$json})"; 
 
header('Content-type', 'text/plain'); 
 
echo $jsonp; 
 
exit;

Deletion Policy

To conserve system resources and reduce costs, Custom Gateway reserve the right to delete any assets that have either been uploaded by the user or generated by the system after:

  • 30 days for print jobs that do not have a corresponding order in the system.
  • 182 days for print jobs that do have a corresponding order in the system.