Skip to main content
Skip table of contents

Smartlinks

Kornit X's smartlink apps are provided in the form of a URL which can be embedded via an iframe into your website.

Different apps layouts exist and you may require different URL parameters depending on your use case.

The below URL is a bare bones example of our standard offering:

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

It is highly recommended that HTTPS is used. However, the personalisation apps can be loaded via HTTP as well if needed.

Please take note of the use of the hash (#) rather than the traditional question mark (?).

You may encounter our legacy app URL format (i.e. https://legacy.custom-gateway.net/acp/app/?l=acp2). Whilst the legacy format will continue to work for the foreseeable future its usage is strongly discouraged.

The URL can be broken down into a few key parts:

Part

Description

acp3_2

The app that you would like to use

en_GB

The app locale

default

The app configuration

p=1007644

The ID of the product to load

r=2d-canvas

The renderer to use. Typically this would either be 2d-canvas for 2D products or webgl for 3D products. multi can be used to load both renderers however doing so may slightly reduce loading speeds

d=COMPANYREFID

Your unique company reference ID

It is recommended that you store the entire app URL as its own text field rather than providing a separate text field for each parameter and then dynamically building the final URL. Storing the URL in its full form allows you to more easily deal with URL format changes or additional parameters in the future.

Don't forget to replace COMPANYREFID with your unique company reference ID

When a user clicks on an "Add to Cart" button within a personalisation app, the app will create a "print job" which represents the user's design.

Subsequently, the app will then use the postMessage API to send an ADD_TO_CART_CALLBACK event to the parent window.

You will need to add a JavaScript message handler to the parent window that listens for the ADD_TO_CART_CALLBACK event. The handler should add the item to the user's shopping cart and store the value of the printJobRef field.

To allow the postMessage API to function, 3 Smartlink iframe URL parameters are required.

Name

Description

meo

The origin of the parent window (i.e https://myshop.com)

mei

A random string.

a2c

Should always be set to postMessage

The meo and mei URL parameters are used to ensure that the parent window only acts on messages from the correct iframe instance. The app will not send messages if either meo and mei are not specified. For security reasons it is also important to ensure that the message is from the g3d-app.com origin.

An example of the event handler is provided in the HTML below.

HTML
<!DOCTYPE html>
<html>
    <body>
        <iframe style="border: 1px solid red; width: 100%; height: 50px;" src="" id="app"></iframe>

        <script>
        let iframeOrigin = "https://g3d-app.com";
        let iframeUrl = iframeOrigin + "/s/app/acp3_2/en_GB/default.html#p=1007644&r=2d-canvas&d=COMPANYREFID&a2c=postMessage";

        let meo = location.origin;
        let mei = Math.random().toString(16).substr(2);

        window.addEventListener("message", e => {
            if(e.origin == iframeOrigin && e.data.id == mei) {
                switch(e.data.name) {
                    case 'ADD_TO_CART_CALLBACK':
                        var printJobRef = e.data.body.items[0].ref;
                        console.log(printJobRef);
                        break;
                }
            }
        });

        let iframe = document.getElementById('app');
        iframe.src = iframeUrl + "&meo=" + meo + "&mei=" + mei;
        </script>
    </body>
</html>

On line 8 of the above example, replace COMPANYREFID with your sales channel company ref ID.

The event's data contains a separate item for each print job that was created. Usually, each item would be added to the cart separately however you may wish to consolidate them depending on your exact use case.

Each item element of the data property contains the below fields.

Name

Type

Description

ref

string

The unique reference code for the created print job.

sku

string

The product's SKU. This should only be needed if the smartlink contains a product selector. In single product mode, your event handler should already know which product to add to cart.

thumbnails

array

A collection of thumbnails for different views of the product (including the user's design)

Ensure that you store printJobRef as it will be needed when submitting an order later on.

If you wish to allow the user to edit their design later on, it can be loaded again by passing the value of printJobRef back to the personalisation app via the pj (print job) URL parameter.

For example:

https://g3d-app.com/s/app/acp3_2/en_GB/default.html#p=1007644&r=2d-canvas&d=COMPANYREFID&a2c=postMessage&meo=...&mei=...&pj=CF921CF10F59B3A258

When the user clicks "Add to Cart" again in the app, the ADD_TO_CART_CALLBACK event will be called as normal but with a new value for printJobRef.

This section is optional

A user can save their design, allowing them to reload it at a later date. You need to provide a callback URL which the user is redirected to after saving. The callback URL allows you to record the information needed to reload the user's design.

The way in which a user can save is app dependent. The following instructions assume you are using the standard acp3_2 app.

The following URL enables the save button:

https://g3d-app.com/s/app/acp3_2/en_GB/mt217h0kr51b1wh.html#p=1007644&r=2d-canvas&d=COMPANYREFID&save=https://example.com/save-callback

Don't forget to replace COMPANYREFID and the callback URL with your own values!

The URL scheme for your callback URL should match the URL scheme that the app was loaded using. For example, loading the app via HTTPS means your callback URL must also be HTTPS.

Once the user has clicked save, the app will make a application/x-www-form-urlencoded form POST to your callback URL.

The POST will include a data field, the value of which is a JSON encoded object (example below).

CODE
{
  ...,

  "created_from": "https://g3d-app.com/s/app/acp3_2/en_GB/mt217h0kr51b1wh.html#p=1007644&r=2d-canvas&d=COMPANYREFID&save=https://example.com/save-callback",
  "ref": "44EEEA752F59C3A3B1",
  "thumbnails": [
    {
      "name": "thumbnail",
      "url": "https://g3d-app.com/u/product-state/44/EE/EA/75/2F/59/C3/A3/B1/thumbnails/thumbnail.png",
      "description": ""
    },
    {
      "name": "thumbnail_60",
      "url": "https://g3d-app.com/u/product-state/44/EE/EA/75/2F/59/C3/A3/B1/thumbnails/thumbnail_60.png",
      "description": ""
    }
  ],
}

The object will contain many fields, the most important of which are:

Name

Type

Description

created_from

string

The original app URL

ref

string

A unique reference code needed to reload the user's design

thumbnails

array

A collection of thumbnails for the user's design which you might like to display somewhere

The default thumbnail is named thumbnail. Other thumbnails for different views may be included depending on the product.

The user's design can subsequently be loaded by taking the value of the created_from field and appending &ps= and the value of the ref field. For example:

https://g3d-app.com/s/app/acp3_2/en_GB/mt217h0kr51b1wh.html#p=1007644&r=2d-canvas&d=COMPANYREFID&save=https://example.com/save-callback&ps=44EEEA752F59C3A3B1

Our Personalisation apps provide the ability to show pricing as well as allowing the user to input a purchase quantity. This information is than pulled from an external URL and is then know as the External Pricing API (Or EPA for short). There are 2 types of EPA which work with new pricing and that is either "Single Product Mode" or "Multi Product mode". This works in conjunction with "Pricing" set up against products. 

In single product mode, the URL specified by the EPA Parameter is called by the personalisation app. Meaning it is possible to use a different URL for each individual product you want to use from platform by changing the parameter.

The Multi Product mode (which is when a product menu is visible) is when the app will take the EPA URL and append a SKU parameter to the end of it before retrieving information. The value of the SKU parameters likely to be the SKU of the product that is selected by the user. This SKU comes from the KornitX Platform and is typically in this case the fulfiller SKU.

This works with both single and multi options, the product information is retrieved via a JSONP API, the URL of this is passed to the app via the EPA URL parameter. The EPA API must return a JSONP encoded object with the following fields:

  1. Price

  2. Name

  3. Description

Well, to begin with you need to ensure the product you are updating has pricing set up within the "Pricing" menu as shown below. In this example we can see the cost, trade and RRP pricing has been set against the product which means we can use the EPA based on the products pricing setup. If your products are missing pricing, the actual EPA setup will fail so this needs to be set up. 

Once we have set the pricing we can head to either "App Defaults" to make a legacy link or to "Smartlink Builder" to select our chosen app, and adding the needed EPA to the product which is set like this -  https://app.custom-gateway.net/api/p/3/epa-v2/:productRef/s/159121/b/any/c/GBP/pt/1

Below is a breakdown of this app link, please take this into account with the above link

  1. The `s` parameter is for the seller company ID (this is set at the example 6 digit ID)

  2. The `b` parameter is for the buyer company ID (set as "any" for our example)

  3. The `c` parameter is for the currency code (Set as "GBP" for our example)

  4. The `pt` parameter is for the price type (In our example this is 2 which is RRP.)

Regarding the pricing type, each type of pricing has a numerical value as detailed below.

Cost - 0

Trade - 1

RRP - 2

Retail - 3

Carriage - 4

Pricing EPA has been updated to ensure that for any Virtual products that do not have any pricing information set, the use of the Pricing EPA in a smartlink will ensure a price is gathered from the Blank product of which the virtual is made from.  This has reduced the need to set virtual pricing on products as with the use of the Pricing EPA, a price will always be set as long as a blank contains this data. 

To set this, simply set add the following "i" paremeter, standing for "Inherit pricing from base product". This will appear at the end of the smartlink like the following example - "i/1"

This a huge change to Pricing EPA tand they key change is the fact products can pull pricing from their blank which from a workflow production vastly speeds up the process. 

In addition to the ADD_TO_CART_CALLBACK event, Smartlinks also emit other events.

Currently the full list of available events is undocumented and we do not provide any guarantees to their future behaviour unless the event in question is described in this document.

CODE
window.addEventListener("message", e => {
    if(e.origin == iframeOrigin && e.data.id == mei) {
        switch(e.data.name) {
            case 'IFRAME_RESIZE':
                iframe.style.height = e.data.body.height + "px";
                break;
        }
    }
});

The IFRAME_RESIZE event can be used to automatically resize the iframe on your site so that all content fits within it without the need for scroll bars within the iframe.

Whilst the IFRAME_RESIZE event exposes both a width and a height, you should only automatically resize in one dimension, keeping the other dimension static.

The code example sets a very small height to aid in demonstrating how the auto resize works. Its best to start with a much larger height to begin with.

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.