The widget attaches to any site. However, "attaching" and "recognizing products" are separate matters. When the character appears and chat works but product cards do not show or knowledge collection fails, the cause is usually a condition on the site side.
Check the items below before installation. Installation works even if not all of them are met. However, features tied to an unmet item do not work.
Pre-installation checklist
| Item | How to check | If not met |
|---|---|---|
| Permission to add HTML | Check whether you can edit the shared layout or footer | Look for a "custom code" menu in your hosting service, or pass the code to a developer |
| Domain match | Compare the address the key was issued for with the address visitors actually open | Issue a separate key for each domain |
| Product card links | Pick one card in the product list and check its <a href> with developer tools | Meet one of the four product recognition priorities below |
| Product detail address | Check whether the detail page address contains a marker such as /product or product_no= | Add marker attributes, or specify an address rule with an initialization option |
| Public pages | Check in a private window whether the address opens without signing in | Members-only pages are not collected, so register their content with Paste text |
| Crawler access | Check whether a firewall or bot blocker rejects automated tools (403) | Collection fails until the block is lifted |
The domain must match exactly
The widget key is issued per domain, and the widget appears only on that domain. A key issued for www.example.com does not work on example.com. If you run your store and brand site on different domains, issue a key for each.
For the same reason, the widget does not appear on a development server (localhost). Check behavior on the real domain.
Four product recognition priorities
When a visitor long-presses a product or hovers the cursor over one, the widget decides whether it is a product within the page, without asking the server. It checks in the order below and uses the first match.
1. Marker attribute
This is the most reliable method. Add data-voidx-product to the product card element and put the product name as its value.
<div class="card" data-voidx-product="Basic cashmere muffler">…</div>
To specify the address, price and image as well, use the supporting attributes together.
<div
data-voidx-product
data-voidx-product-name="Basic cashmere muffler"
data-voidx-product-url="/products/muffler-basic"
data-voidx-product-price="KRW 59,000"
data-voidx-product-image="/images/muffler.jpg">
…
</div>
If you add only data-voidx-product without a value, the widget looks for the product name inside that element in this order: itemprop="name", heading tags (h1 to h6), image alt, link text.
2. Product detail link
Without a marker, the widget looks at the link wrapping the product card. If the link points to the same domain and the address contains one of the markers below, it is treated as a product. Matching is case-insensitive.
| Path | Query |
|---|---|
/product | product_no= |
/products/ | product_cd= |
/p/ | goodsno= |
/goods | itemid= |
/item | sku= |
/prd | product_id= |
detail.html | productid= |
If your address rules differ from this list, you can specify them yourself by passing a regular expression to the initialization option productPress.urlPattern.
The widget goes up to 4 levels above the link to find the card boundary, and stops just before a level where another product link appears. The product name is taken in this order: a heading inside the pressed link, the text of that link, a heading within the card boundary, image alt, the title attribute. Prices are read in prefixed forms (₩, KRW, $, €, ¥, £) or in the 12,000원 form.
3. Microdata
An itemscope element with itemtype="https://schema.org/Product" is also treated as a product. Sites that already have structured data are picked up here with no extra work.
4. The product detail page itself
If the address of the open page matches the rules in 2, the whole page is treated as one product. In this case the widget reads the JSON-LD Product first and, if there is none, reads OpenGraph. For OpenGraph, og:type must be exactly product, and product.group is treated as a list page.
If a product link points to another domain, it is not recognized as a product. This covers sites where a brand site sends visitors to an external store, or where the storefront is on a separate domain. On such sites, specify products directly with marker attributes.
Product cards in chat have separate conditions
The rules above apply when a visitor picks a product on the page. The product cards below an answer are built from the answer text. When list items have a bold title or a price along with a link to your own site, up to 3 of them become cards.
Pages that knowledge collection reads
When you choose "Collect entire site" or "Single URL" in knowledge registration, a collector reads the site, not the widget. The collector opens pages under the same conditions as a visitor who is not signed in.
| Condition | Details |
|---|---|
| Address | A public address starting with https. Addresses containing a username and password, or using a non-standard port (other than 80/443), cannot be registered |
| Collect entire site | Up to 1,000 pages, up to 15 minutes. Ends at whichever comes first |
| Single URL | 400KiB per page |
| Count | Deducts from today's collection count, even when it fails |
If a bot blocker or firewall rejects the collector, the source status becomes "Failed". If there is previously collected content, answers continue with that content and only the latest changes are not reflected. Check the reason for the rejection under "Failure cause" in the source details.
Next steps
- For the steps to add the installation code, see Widget installation.
- For initialization options and specifying address rules, see SDK reference.
- For the knowledge registration procedure, see Knowledge management.
- When product cards do not appear, see Product cards not showing.