Custom Print Data Checks

The product designer already checks resolution, contrast, safe margin, overlap and the number of print colours by itself. If your production has further rules, such as “a logo must be at least 15 mm wide” or “no text below 6 mm on hot foil”, you add your own checks: in the browser with JavaScript or on your server via a webhook.

For a rule that has to hold, use the webhook. Ideally you combine both: the browser shows the note straight away, the server makes sure.

Check in the browser

You register a check through the JavaScript API:

Configento.registerDesignCheck('logo-min-width', (ctx) =>
    ctx.placement && ctx.placement.widthMm < 15
        ? { level: 'block', message: 'The logo must be at least 15 mm wide.' }
        : null,
    { appliesTo: ['logo'] });

• The name consists of lower-case letters, digits and hyphens.
• appliesTo lists the Internal names (ID) of the characteristics the check applies to. Without appliesTo it runs for every custom text and every custom image.
• registerDesignCheck returns a function that unregisters the check again.

If your script runs before configento.js has loaded, define the checks in advance:

window.ConfigentoDesignChecks = {
    'logo-min-width': [check, { appliesTo: ['logo'] }],
};

What the check receives

The check runs on every change and receives an object ctx:

What the check answers

• null: everything is fine.
• { level: 'warn', message: '…' }: the note appears at the field, ordering is still possible.
• { level: 'block', message: '…' }: the note appears at the field, and the configurator holds back the cart.
• A list of such results if several things don't fit.

You style the note with the class .cfg-design__check; data-configento-level says whether it is a warning or a block, and data-configento-check names your check. See Customise the design. If a check throws an error, the configurator ignores it and writes the error to the browser console.

Check on your server

With a webhook, your server checks every design before it goes into the cart. That way the rule holds even if someone bypasses the browser.

Setting it up

1. In the admin, open Settings → API and there Design check webhook.
2. Enter the Webhook URL. Only https to a public address is allowed.
3. configento.app generates a Signing secret (dcw_…). Store it on your server. New secret replaces it.
4. Click Send test call. If your server answers, “The webhook answered.” appears.
5. Decide whether Refuse the cart when the webhook does not answer should apply (see below).

The request

When a configuration is added to the cart, configento.app recalculates the price and sends all visible, filled custom texts and pictures to your URL via POST:

{
  "event": "design_check",
  "component_id": "10000021",
  "locale": "en_GB",
  "fields": [ { "characteristic": { "key": "logo", "type": "customimage" }, "placement": { "widthMm": 12.4, "dpi": 310 } } ]
}

Each element in fields has the same structure as ctx in the browser (shown shortened). Only box is always null on the server.

The headers:

Verify the signature before you trust the request, e.g. in Node.js:

const crypto = require('crypto');
const expected = 'sha256=' + crypto.createHmac('sha256', process.env.CONFIGENTO_DCW_SECRET)
    .update(req.headers['x-configento-timestamp'] + '.' + rawBody).digest('hex');
const ok = crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(req.headers['x-configento-signature'] || ''));

Also discard requests whose timestamp is more than a few minutes old.

The answer

Your server answers with status 2xx and:

{ "findings": [ { "field": "logo", "level": "block", "message": "The logo must be at least 15 mm wide." } ] }

field is the internal name of the characteristic. An empty list means everything is fine.

Your server has 2 seconds; configento.app does not follow redirects. The result is valid together with the price for 5 minutes, and an identical configuration does not ask again during that time.

Requirement in the shop

The webhook runs in the price check. If it blocks, the configuration does not go into the cart and your customer sees your message there, from these plugin versions on:

With older plugin versions the block applies as well, but your customer only sees the general message that the configuration is no longer valid or the price could not be confirmed.

So also show your message through a check in the browser; then your customer sees it while designing.

Troubleshooting

1. The browser check has no effect: Is the internal name in appliesTo correct? Is the script loaded after configento.js, or do you use window.ConfigentoDesignChecks? Errors of the check are in the browser console.
2. “The webhook did not answer usably”: Your server does not answer within 2 seconds, redirects, answers without 2xx or without valid JSON.
3. The block has no effect in the shop: In Magento the price check is not set to Enforce. Your customer only sees a general message: The plugin is older than the versions above.
4. The signature does not match: Calculate over the unchanged raw request body, not over re-encoded JSON, and check whether you stored the new secret after New secret.

Next steps

• Custom Text on the Product
• Custom Image on the Product
• JavaScript API
• API: Getting Started