Skip to content

Building a plugin

A checklist for anyone who writes a plugin or module for a CMS or a shop platform that connects a shop to Ziex Try-On. Work through it in order. A plugin that passes every item behaves the way the WooCommerce plugin and the 1C-Bitrix module do. The same checks make a good acceptance test for your own plugin.

Not an automated test

This is a checklist for you to run by hand. We do not yet publish a script that runs it for you.

The shape of a plugin

A plugin has two halves:

  • The server half runs on the shop's server. It holds the secret key (tryon_…) and talks to the API.
  • The page half is printed into the product page. It holds only the publishable key (pk_…) and starts the widget.

The secret key never leaves the server. If it appears in a page, a stranger can read it, and it also opens the shop's client portal with the shoppers' photos. See Keys.

1. Connect the site

  1. [ ] Ask the API about the site. From the server, call GET /api/v1/tryon/integration?site_url=<the shop's address> with the secret key in X-API-Key. Call it when the shop owner saves the key and when the settings page opens, not on every page view: it counts against the general request limit (see Limits) and the answer changes rarely.
  2. [ ] Read site.allowed. Print the widget only when it is true. When it is false, site.reason tells why: key_not_bound (the key has no bound domain), domain_mismatch (the key belongs to another site) or dev_host (a live key on a development host). Show the shop owner a message that matches; for dev_host say "use a test key on a local site". The reasons map onto error codes in Errors.

  3. [ ] Use the rest of the answer. The fields a plugin needs:

    Field What it is
    site.allowed, site.reason, site.host Whether this site may use the key, why not, and the site's host as the API reads it.
    key.publishable_key The pk_… key to print on the page.
    key.mode live or test. For test, tell the shop owner that no money is charged and the result is simulated.
    key.domain, client.name The bound domain and the account name, for the settings page.
    plan The plan name, its limit, the generations used and remaining, and when they reset.
    widget.script_url, widget.api_url The widget script and the API address, from our host.
    capabilities The categories the service supports (below).
    integrations For each known plugin or module: latest_version, download_url (or null when we hand the archive over ourselves) and docs_url. Use it to tell the owner that a newer version of your plugin exists.

  4. [ ] Identify the plugin on every server call. Send X-Ziex-Integration: <name>/<version> and your own User-Agent (see Identification and Quickstart B).

2. Print the widget safely

  1. [ ] No tryon_… key in the page. Check the page the plugin produces: the HTML, the inline script, the JavaScript files, the cookies and the data it passes to the front end. A string that starts with tryon_ must not appear anywhere. Only pk_… does.
  2. [ ] Take the script address and the key only from our answer. Use widget.script_url and widget.api_url from the integration answer, and key.publishable_key. Do not take them from a setting the shop owner can type and do not build them yourself. The script is always loaded from https://api.ziex-tryon.com/embed/; never copy tryon-embed.js to the shop's server, because the widget takes the API address from where its script came from.

  3. [ ] Initialise the widget with these options (all described in the Widget reference):

    Option Value
    apiKey The publishable key, pk_….
    productImage The product's main image, an https:// URL.
    productTitle The product's name.
    productUrl The product's page address.
    category A category id from GET /api/v1/tryon/capabilities (or the capabilities block of the integration answer): tops, outerwear, bottoms, one-pieces, or auto when the product cannot be mapped (unless auto.available is false). Do not hard-code the list: it grows.
    launcher false. The plugin draws its own button and calls TryOn.open().
    lockCategory true. The shop has chosen the category, the shopper is not asked.
    integration "<name>/<version>", for example "acme-cms/1.0.0".

  4. [ ] Pick up a try-on after a page change. Load the widget lazily, but load it at once on a page where the tab holds a try-on in progress, otherwise the shopper never sees the result. Use the loader's ZiexTryOn.hasPending(pk) and ZiexTryOn.load(); do not copy the slot rule. See Lazy loading and pickup.

  5. [ ] Allow the widget in the page's Content-Security-Policy, if the shop sets one. See CSP. A plugin that adds inline script needs the platform's own nonce mechanism.

3. Check it with a test key

Do this on a development stand with a test key, which costs nothing. See Test keys and Local development.

  1. [ ] Verify the test key. GET /api/v1/tryon/integration with a test secret key answers key.mode: "test". On a local or staging host site.allowed is true when the host is allowed for the key.
  2. [ ] Send one try-on from the server with an Idempotency-Key, then poll GET /api/v1/tryon/status/{job_id} until it is completed. The photo must be an upload (a data URI). A repeat of the same request with the same key must answer 200 with the same job and create no second one. See Quickstart B.
  3. [ ] Run the widget once on a page of the stand, with the test key's pk_test_…: open the window, send a photo, reach the result. The window shows a "TEST" badge.
  4. [ ] Verify the webhook signature on a delivery you captured. Register a test endpoint, send a test try-on and check X-TryOn-Signature-V2 over the raw bytes of the body, with a stale-timestamp refusal. See Webhooks.

4. Tell the shopper

  1. [ ] Give the shop a privacy-policy paragraph. The shopper's photo is sent to the service, so the shop must say so. Show the owner the ready text from Privacy text for shops and tell them to add it to their policy.
  2. [ ] Handle errors by code, not by text. Show the shopper a plain message for each code and keep the raw text for your log. See Errors.

Examples to read

Two plugins are ready examples of this checklist:

  • The WooCommerce plugin. The archive is https://app.ziex-tryon.com/downloads/ziex-tryon-woocommerce.zip.
  • The 1C-Bitrix module. We hand the archive over directly; ask us.

When your plugin is ready, write to us (see Contact) with its name and the version label it sends.