Skip to content

1C-Bitrix module

The module Ziex Try-On — virtual try-on (module code ziex.tryon) adds a "Try it on" button to the product card of a 1C-Bitrix shop. The shopper uploads a photo of themselves and sees the garment on themselves.

The current version is 0.1.4. The module is at an early stage (0.1): it is handed over as an archive and is not published for download.

What the module does

  • Prints a "Try it on" button under the purchase buttons of the product card and starts the widget when the shopper presses it.
  • Connects the site to the service with your secret key. The key is stored in the site's database only; it is not in the HTML of the pages and not in the logs.
  • Puts only the publishable key (pk_…) on the pages. The module gets it from the service itself. See Keys.
  • Decides for each product, by its catalogue sections, whether the button is shown and what kind of garment it is.
  • For a product with colours and sizes (trade offers), tries on the photo of the selected offer.
  • Prints no inline <script> on the pages. It adds the service's loader asynchronously; the widget script is loaded on the first click of the button, or at once on a page where a try-on of this shop is still pending in the tab.

The button is on the product card only. It is not in product lists, quick-view windows or cards loaded through AJAX. If the site answers on several unrelated domains, the button works only on the domain the key is bound to, together with www. and subdomains. The module has no try-on statistics in the Bitrix admin: the history is in the client portal at https://app.ziex-tryon.com.

Requirements
Product 1C-Bitrix Site Management on your own server. The cloud Bitrix24 is not supported.
Main module (main) 23.0.0 or newer. Tested on 26.150.0.
PHP 7.4 or newer (7.4 to 8.x)
Encoding UTF-8 (the UTF-8 mode in the core settings)
Modules Information Blocks (iblock). The trade catalogue (catalog) is preferable.
Write access The folders /local/components and /bitrix/js. The installer copies the button component, the script and the styles there.
A key A live secret key (tryon_…) bound to your site's domain

Colour and size photos (trade offers) need an edition with a shop: Small Business, Business or Enterprise. Start and Standard work with a plain information-block catalogue.

The key is issued by us. It is shown once, when it is created, so keep it. A domain bound to the key also covers its www. form and its subdomains. A Cyrillic domain must be bound in its punycode form (xn--…), because the module sends the site's address in that form. Tell your manager when the key is issued.

Get the module

The archive ziex.tryon-<version>.zip is issued by your manager. It is not published for download yet: the entry for this module in the integrations block of GET /api/v1/tryon/integration has download_url: null (see Building a plugin). To ask for the archive and a key, see Contact.

Install and connect

  1. Unpack the archive into the /local/modules/ folder of the site (by FTP or SFTP, through the hosting panel or a file manager), so that the file /local/modules/ziex.tryon/install/index.php exists. Create /local/modules/ if it is missing. Keep the module in one place: while a copy sits in /local/modules/ziex.tryon/, Bitrix loads the module from it, and a newer copy in /bitrix/modules/ziex.tryon/ has no effect.
  2. In the admin area open Marketplace → Installed Solutions. Bitrix lists there the modules it finds in /local/modules/. Find Ziex Try-On — virtual try-on, open the row's menu and choose Install.
  3. The installer checks the requirements. If something does not fit, it says "The Ziex Try-On module is not installed" and lists the reasons: the PHP version, the UTF-8 mode, the Information Blocks module, the version of the main module, write access to /local/components or /bitrix/js. Fix the reason and install again. Nothing is installed until the requirements are met.
  4. When all is well, press Open settings. The settings page is Store → Virtual try-on. On a site without the sale module the item is under Services.
  5. On the Connection tab paste the secret key into API key and press Save and check. The module asks the service whether the key fits this site. The status card turns to Connected and shows the account, the allowed website, the plan and the generations left.
  6. On the Catalog and categories tab press Suggest from section names, review the choices and press Save.
  7. Open a product card and add the button to the card template (below).
  8. Add the paragraph about the service to your privacy policy. See Privacy, CSP and test keys.

The installation copies the button component to /local/components/ziex/tryon.button/ and the script and styles to /bitrix/js/ziex.tryon/, adds an agent that re-checks the key once an hour, creates the product property "Virtual try-on" in the catalogue information blocks and adds a menu item. It changes no products, sections or site templates.

Settings

The settings page has the tabs Connection, Catalog and categories, Button, Privacy policy and Access. If one Bitrix installation has several sites, a Site: selector at the top chooses the site; every setting is kept per site.

Connection

Setting What it does
API key The secret key. The field is always empty after saving; the stored key is shown masked. An empty field on save keeps the stored key. A pk_… key is refused with a message that a secret key is needed. A key that is not tryon_ followed by 32 to 64 letters, digits or underscores is refused as well. Nothing is saved on a refusal.
Show the button on the site On by default.
Visitor cabinet («My looks») On by default. The widget keeps the shopper's results in their browser for up to 30 days, and their photo only if they tick "Remember this photo on this device". Turning it off also erases what visitors already stored, on their next visit.
Website address for the check Normally empty. The module works the address out from the site's settings, and the grey text in the field shows which one. Fill it only when the key is "bound to another website" because the module worked the address out wrongly. Enter a full address such as https://shop.example.com/. Only the host name is compared.
Debug in the browser console For troubleshooting only. The module's script writes warnings about the button to the browser console.
Disconnect Removes the key and the status and hides the buttons.

Save and check asks the service about the key, receives the publishable key and shows the result. A key is saved only together with its check. The module repeats the check every hour with a Bitrix agent.

  • A refused key (invalid, revoked, suspended, bound to another website) turns the card to Not connected with the reason and removes the buttons from the site.
  • A network error or an outage of the service never hides the buttons. The last good status stays, and the card shows the time and the reason of the last check. If the service does not answer for more than a day, a notice appears in the admin area.
  • If we rotate the publishable key, the widget fails until the module checks again, within an hour. Press Save and check right after the rotation and leave API key empty: the stored key is kept and the module fetches the new publishable key itself.

Catalog and categories

The service cannot try on every kind of item. The tab shows What can be tried on (usually tops, outerwear, bottoms, dresses and jumpsuits) and what cannot (for example shoes and bags). The list comes from the service and can grow.

Catalog info blocks is set to automatic choice: the site's product catalogues without the trade-offer information blocks. Choose the information blocks by hand if your products live elsewhere.

For each catalogue section (the table with Section, Products, Try-on) choose one value:

Value Meaning
A category name All products of the section are tried on as that kind of garment.
Cannot be tried on The products get no button. If one of a product's sections is marked so, the product has no button.
Detect automatically (mixed section) The service works out the kind of item. For mixed sections such as Sport.
— does not decide The section decides nothing. For collections such as New or Sale. A subsection that does not decide takes the value of its parent.

If a product has several sections with different categories, automatic detection is used when the service offers it; otherwise there is no button. If no section of a product sets a category, there is no button either.

Suggest from section names fills only the empty values from the section names. It saves nothing by itself. Refresh list fetches the list of categories from the service at once. When the service adds a category, a notice asks you to check the mapping. Save applies the choice; the buttons on the pages update by themselves.

Result for your catalog at the bottom counts the products that get the button, those that cannot be tried on, those Switched off on the product and those Not decided, with links to the last ones. It counts the first 2000 active products of each information block.

Choice per product. The product property Virtual try-on (code ZIEX_TRYON_CATEGORY) overrides the sections. Its values are "As in the section" (default), a category, "Detect automatically" and "No try-on for this product". The installation creates the property in the catalogue information blocks. If it is missing, for example for a new information block, press Create the "Virtual try-on" property on this tab.

Button

Setting What it does
Button text Empty means "Try it on" (or its translation by the site language). At most 60 characters.
Button CSS classes The classes that make the button look like the buttons of your template. Default: btn u-btn-outline-primary product-item-detail-buy-button.
Where the button appears A line in the card template (recommended) or Automatically, without editing the template.

The photo that is tried on. For a trade offer with a photo of its own, that photo is used when its colour is selected. Otherwise the product's photo: the detail picture, then the preview picture, then the first of the additional photos (MORE_PHOTO). If neither the selected offer nor the product has a photo, the button is hidden until an offer with a photo is selected. A photo of an earlier offer is never substituted. If neither the product nor its offers have a photo, there is no button.

A line in the card template

This is the default. It is reliable and survives Bitrix updates. The same steps, with the paths of your own site, are shown on the Button tab next to the line.

  1. Find the card template. The card is shown by the bitrix:catalog.element component. In a typical shop its template bootstrap_v4 is in /bitrix/components/bitrix/catalog.element/templates/bootstrap_v4/. The Button tab names the folder your site takes the card from today.
  2. Copy the template folder (by the file manager of the admin area or by FTP) to the place where your site template looks first:
    • The site template lives in /bitrix/templates/ (most shops): copy to /local/templates/.default/components/bitrix/catalog.element/<card template name>/.
    • The site (all pages or some) is drawn by the site template .default itself: copy to /bitrix/templates/.default/components/bitrix/catalog.element/<card template name>/. A /local/templates/.default/ folder would shadow such a site template. If the card comes from a catalogue template /bitrix/components/bitrix/catalog/templates/<catalog template>/, copy that whole folder to /bitrix/templates/.default/components/bitrix/catalog/<catalog template>/ and use bitrix/catalog.element/<card template name>/template.php inside the copy.
    • The site template lives in /local/templates/<site template>/ (it has header.php there): copy to /local/templates/<site template>/components/bitrix/catalog.element/<card template name>/.
    • The card is already taken from a folder inside /local/: copy nothing, add the line to the template.php of that folder.

  3. Paste the line into the copy's template.php, right after the </div> that closes <div data-entity="main-button-container">. The Button tab has a Copy button for it:

    <?php if (\Bitrix\Main\Loader::includeModule('ziex.tryon')) { $APPLICATION->IncludeComponent('ziex:tryon.button', '', ['ELEMENT_ID' => $arResult['ID'], 'OFFER_ID' => $actualItem['ID'] ?? 0, 'CONTAINER_ID' => $itemIds['ID'] ?? ''], $component, ['HIDE_ICONS' => 'Y']); } ?>

  4. Reset the button cache. On the Button tab press Reset the button cache. Saving the module's settings resets it by itself, but after a line is pasted into a template it has to be reset by hand.

  5. Check. Under the line the module writes "The line was found in:" and lists the templates that carry it.

Do not change the line:

  • The includeModule check is required. Without it, once the module is uninstalled every visitor sees the red text 'ziex:tryon.button' is not a component.
  • $component as the fourth argument is required. Without it the button works on the first view and does nothing once Bitrix serves the card from its cache.

Two folders never to create

Never create /local/templates/<site template>/ when the site template itself lives in /bitrix/templates/. Bitrix then takes the whole site template from that folder, and every page loses its header and styles. The Button tab shows a red warning while such a folder exists and names the folder the copy belongs in.

Never create /local/components/bitrix/<component>/ either. Bitrix then takes the component itself from there, and every card shows "'bitrix:catalog.element' is not a component".

The copy no longer receives the fixes Bitrix makes to its own template. If your theme has its own product card, paste the line into it, in the same place.

Automatic placement

A fallback, off by default. On the Button tab choose Automatically, without editing the template and press Save. The module adds the button block to the page itself, and the script moves it next to the card's main buttons after the page has loaded.

  • It needs a card built like the Bitrix core's (with a main-button-container block) and a catalogue page on the core bitrix:catalog component. In a card of another structure the button stays hidden. Use the line in the template then.
  • The button appears after the page has loaded, so a small layout shift is possible.
  • While automatic placement is on, the line in the template prints nothing. Two buttons for one product are never shown.

Access

On the Access tab choose who can do what: No access, View the settings or Change the settings. Only administrators can install and uninstall the module.

Check that it works

  1. Connection shows the green card Connected, with your account and your website, and Show the button on the site is on.
  2. On Catalog and categories, Result for your catalog counts a non-zero number of "Products with the try-on button".
  3. On Button, "The line was found in:" lists the card template you edited, without the note "found, but this copy is not used" and without "without the module check".
  4. Open a product card whose section can be tried on. Try it on sits under the purchase buttons. With colours, the photo of the chosen colour is tried on.
  5. Press it, upload a photo and wait for the result.
  6. Sign in to the client portal at https://app.ziex-tryon.com. The try-on is in the list of jobs with the product's name and link, and the API Keys page shows bitrix/0.1.4 as the last label the key was used with.

Update and uninstall

Update. Unpack the new version over /local/modules/ziex.tryon/, replacing the files. At the next opening of the settings page, or at the next run of the agent (within an hour), the module copies the new script, styles and button component itself and resets the button cache for all sites. Do not uninstall the module to update it: the uninstall asks about the data.

The module does not check for new versions itself. The latest version of every plugin and module is listed in the integrations block of the answer of GET /api/v1/tryon/integration. Ask your manager for the new archive.

Uninstall. In Marketplace → Installed Solutions choose Uninstall in the module's row menu. The uninstall takes two steps.

  1. The page "Uninstalling the Ziex Try-On module" warns that the button disappears from the cards and that products, sections, orders and site templates are not deleted. It has:
    • The box Keep the settings and the product property, ticked by default. With the box ticked, the settings (the key included) and the product property stay, and a reinstall brings everything back. Without it they are deleted.
    • The list of card templates that carry a line with the ziex:tryon.button component. A line wrapped in an includeModule check shows nothing once the module is gone. A line without the check is marked red: delete it or wrap it in if (\Bitrix\Main\Loader::includeModule('ziex.tryon')) { … } before uninstalling.
  2. The module removes the button cache, the agent, the notices, its own script and component and its event handlers.

The copy of the card template with the line stays. While the line has its check it is harmless.

Integration label

The module names itself to the service: bitrix/<version>, for example bitrix/0.1.4. The widget sends the label with every try-on, and the module sends it with its two server calls, in the X-Ziex-Integration header. You do not need to set anything. See Identification.

Privacy, CSP and test keys

  • Privacy. The shopper's photo is sent to the service. The service keeps the photo and the result for 180 days, and your shop's privacy policy must say so. A ready paragraph, in English and in Russian, is on Privacy text for shops; the Privacy policy tab of the module carries the same text with Copy buttons. Consent and the transfer of data abroad are questions for your own counsel. This matters in particular for Russian shops: the photo is processed by a platform in the United States.
  • CSP. The module sends no CSP headers and prints no inline script. If your shop has a policy, allow the hosts listed on CSP. Add the address of your image CDN to img-src if the product photos live there.
  • Test keys. The API key field checks only the shape of the key. Test keys are for building an integration; see Test keys.

If something is off

Go through the list from top to bottom.

  1. Connected? The Connection tab must show the green card, and Show the button on the site must be on. A red Not connected card names the reason.
  2. Section mapped? At least one section of the product sets a category, or the category is chosen on the product, and no section is Cannot be tried on. Find the product in Result for your catalog. The product must be active and sit in one of the Catalog info blocks.
  3. Photo? The product or its trade offers need a picture.
  4. The line where the card is taken from? The file must be listed under "The line was found in:" without "found, but this copy is not used". The line needs the includeModule('ziex.tryon') check and $component as the fourth argument. While automatic placement is on, the line prints nothing.
  5. Cache. Press Reset the button cache. If the card stays as it was, clear Bitrix's own cache, and the composite cache if the composite site is on.
  6. Agents. The hourly check is a Bitrix agent. If agents do not run (the simplest cure is to run them from cron), a revoked or reissued key is noticed only on Save and check.
  7. Notices and the event log. A refused key and a long outage raise notices in the admin area, and the module writes its events to the Bitrix event log.
  8. The key is bound to another website. The card names both domains. Ask us to bind the key to the right domain, or fill Website address for the check when the module worked the address out wrongly.
  9. The button says "The try-on service is unavailable right now. Please try again later." The widget script did not load. Check your CSP and that https://api.ziex-tryon.com is reachable from the shopper's network.
  10. The button does nothing after the first view. The line has no $component.
  11. Still unclear. Turn on Debug in the browser console, open the product card and read the browser console. Turn it off afterwards.

Errors the widget shows to the shopper are listed on Errors. To ask for help, quote the label bitrix/<version> and the request id described on Identification.

For developers

The button's settings travel as HTML-escaped JSON in the data-ziex-tryon-config attribute of <div class="ziex-tryon" data-ziex-tryon-box>. The button is <button class="ziex-tryon-button" data-ziex-tryon>. The component ziex:tryon.button takes ELEMENT_ID (required), OFFER_ID, CONTAINER_ID and CACHE_TIME (3600 seconds by default).

The button is cached together with the catalogue card (catalog.element). The module resets that cache whenever its settings change, when the key is checked, when the placement is switched, and on install and uninstall. It cannot see an edit of a template: after one, press Reset the button cache.

Once the widget is loaded, window.TryOn.on(event, fn) is available. See the Widget reference.

See also