Smartlink VPC (Virtual Product Creator)

Before embedding the VPC tool into your website, you need the following pieces of information:

A unique company reference ID.
An alphanumeric API key.

Additionally, it is also necessary to specify two product category IDs:

The ID of a category which is used to determine the available blank products.
The ID of a category into which all end user created content is saved.

Please visit the support portal if you need any help or advice on this.

Embedding the VPC

The VPC tool can be embedded into your site using an iframe set to the following URL:

https://whitelabel.custom-gateway.net/artists/vpc

Several query parameters are also required:

Name	Description	Required?
`company_ref_id`	Your unique company reference ID	Yes
`approved_pc`	The ID of the Catalog product category into which all created content is inserted	Yes
`blanks_pc`	The ID of the Catalog product category containing available product blanks	Yes
`time`	The number of seconds since the UNIX epoch	Yes
`nonce`	A random alphanumeric string that should be different each time you load the VPC	Yes
`origin`	The origin of the page loading the VPC	Yes
`hmac`	A HMAC message digest	Yes

Calculating the HMAC Message Digest

Due to the nature of the VPC tool, it is necessary for the personalisation platform to be able to verify that your site is who it says it is. This is accomplished via the use of the HMAC algorithm.

The input to the HMAC algorithm should be the query part of your iframe URL (minus the hmac parameter itself) whilst the HMAC secret key is your API key. sha512 should be selected as the hashing algorithm.

The time query parameter is used to ensure that any HMAC value older than 15 seconds is rejected. This means that it is important that your server has the correct date and time set.

For example, given the following query parameters:

Name	Value
`company_ref_id`	`99999`
`approved_pc`	`1`
`blanks_pc`	`2`
`time`	`1543581543`
`nonce`	`randomstring`
`origin`	`https://myshop.com`

the HMAC input data would be:

company_ref_id=99999&approved_pc=1&blanks_pc=2&time=1543581543&none=randomstring&origin=https%3A%2F%2Fmyshop.com

which gives the below message digest when using AAAAAAAAAAAAAAAAAAAAAAAAAAA as the HMAC secret key:

faf1b78c10bab271ba3a37933a642cfa371ce6bd4c82575d5180b2a1af904cb9ab8379dd997a2bfb90c3213a92928fe54187a75cc085b24a811747b4955f9f89

resulting in the final iframe URL:

https://whitelabel.custom-gateway.net/artists/vpc?company_ref_id=99999&approved_pc=1&blanks_pc=2&time=1543581543&none=randomstring&origin=https%3A%2F%2Fmyshop.com&hmac=faf1b78c10bab271ba3a37933a642cfa371ce6bd4c82575d5180b2a1af904cb9ab8379dd997a2bfb90c3213a92928fe54187a75cc085b24a811747b4955f9f89

Product Creation Callback

JSON

<!DOCTYPE html>
<html>
    <head>
        <style>
            html, body { margin: 0; padding: 0; width: 100%; height: 100%; overflow: hidden; }
            iframe { width: 100%; height: 100%; border: 0; }
        </style>

        <script>
        window.addEventListener('message', function(e) {
            if(e.data.name == 'PRODUCTS_CREATED' && e.source == document.getElementById('iframe').contentWindow) {
                let products = e.data.body;

                // Do something to create the products within your own eCommerce
                // platform
            }
        });
        </script>
    </head>
    <body>
        <iframe id="iframe" src="https://whitelabel.custom-gateway.net/artists/vpc?..."></iframe>
    </body>
</html>

Once the end user has created their products using the VPC tool, a PRODUCTS_CREATED message will be passed back to the parent site using the postMessage API.

Your site can listen for such messages using Javascript.

When the message is received, your site should use the data provided within the message to create relevant products in the most appropriate way for your particular eCommerce package.

After creating the products, the VPC iframe should be closed and the user redirected to an appropriate landing page.

The body field of the message will be an array containing an element for each product that the user selected.

Each element has the following fields:

Name	Description
`id`	The Catalog module product ID that can be used in a Smartlink to reload the user's design
`description`	The design description entered by the user.
`name`	The design name entered by the user.
`retail_sku`	A unique SKU generated by the VPC tool using the product's supplier SKU as a base
`snapshots.small`	A 600x600 preview of the user's product
`base_product.productCode`	The SKU to use when sending future order lines for the product.