@orbiocloud/shop-widgets

Drop-in, embeddable widgets that show your OrbioShop products on any website and link shoppers through to your live storefront. The default embed is read-only: it displays products and deep-links each one to its product page — the cart and checkout happen on your storefront, not on the embedding page.

What you get

• <div data-orbio-product-list> — a paged grid of products (the feed).
• <div data-orbio-product-card> — a single product card.

Both render with a publishable, read-only, origin-locked API key that is safe to put in your page's HTML.

1. Create a publishable embed key

In your OrbioCloud dashboard: Shop → Admin → API Keys.

1. Enter a key name (e.g. "Marketing site").
2. In Allowed website origins, list the exact origin(s) the embed runs on, comma- or space-separated — e.g. https://example.com, https://www.example.com.
3. Click Create Key and copy the key (it's shown only once).

Filling in origins mints a read-only embed key: it can only read products / categories / brands, only from the origins you listed, and can never place orders or modify a cart. Leave origins blank and you get a server-to-server key instead (not usable from a browser embed).

Use a separate key per site/origin so you can revoke one without affecting the others.

2. Drop in the script

Served from npm via unpkg, pinned to an exact version — never a floating tag like @latest, so a republish cannot change what already-embedded customer pages execute.

integrity is required, not decorative. Without it, anyone able to serve a different body at that URL — a CDN compromise, a cache poisoning, a hijacked npm account republishing the version — executes arbitrary JavaScript on every customer site that embeds this.

Generate the real hash from the published artifact and paste it in (it can only be produced after publish, which is why it is not committed here):

V=1.0.3
curl -sL "https://unpkg.com/@orbiocloud/shop-widgets@$V/dist/orbio-shop-widgets.umd.js" \
  | openssl dgst -sha384 -binary | openssl base64 -A

<script src="https://unpkg.com/@orbiocloud/[email protected]/dist/orbio-shop-widgets.umd.js"
        integrity="sha384-kjs65ZMkhUDfTtHxpf3ejGAolnp6QxyJtkaDTwofaczbt7LcK49m4+rX86WEKd+h" crossorigin="anonymous"></script>
<script>
  OrbioShopWidgets.init({
    apiKey: 'your-publishable-read-key',
    subdomain: 'my-store',
  });
</script>

<!-- A product feed -->
<div data-orbio-product-list data-limit="12" data-columns="4"></div>

<!-- A single product -->
<div data-orbio-product-card data-product-slug="vintage-tee"></div>

init(...) auto-wires the read-only widgets on the page. Clicking a product navigates to https://<subdomain>.shop.orbiocloud.com/shop/product/<slug> (or your brand domain — see baseUrl below).

init options

| Option | Type | Default | Notes | | ----------- | ------- | ------- | ---------------------------------------------------------------- | | apiKey | string | — | Required. Your publishable read key. | | subdomain | string | — | Required. Your store subdomain. | | baseUrl | string | https://<subdomain>.shop.orbiocloud.com | Set this to your brand domain (e.g. https://shop.acme.com) so links and API calls stay on-brand. | | autoInit | boolean | true | Set false to initialize manually. |

<div data-orbio-product-list> attributes

| Attribute | Default | Description | | ---------------------- | ------------ | ------------------------------------------------------- | | data-limit | 12 | Products per page (max 100). | | data-columns | responsive | Fixed column count; omit for auto-fit. | | data-category | — | Filter by category slug. | | data-brand | — | Filter by brand slug. | | data-search | — | Filter by search term. | | data-featured | false | "true" to show only featured products. | | data-show-description| false | "true" to show the short description. | | data-show-rating | true | "false" to hide the star rating. | | data-target | _self | Link target; "_blank" opens the shop in a new tab. |

A Load more button appears when more pages are available.

<div data-orbio-product-card> attributes

| Attribute | Default | Description | | ---------------------- | ------------ | ------------------------------------------------------- | | data-product-slug | — | Preferred. The product slug. | | data-product-id | — | Best-effort fallback (first page only — prefer slug). | | data-show-description| true | "false" to hide the description. | | data-show-rating | true | "false" to hide the star rating. | | data-target | _self | Deep-link target. | | data-deep-link | true | "false" to disable navigate-on-click. |

Programmatic use

<script>
  const shop = OrbioShopWidgets.init({
    apiKey: 'your-publishable-read-key',
    subdomain: 'my-store',
    autoInit: false,
  });
  OrbioShopWidgets.initReadOnlyWidgets(); // re-scan the DOM after dynamic inserts

  // The deep-link URL for any product (built from your config host):
  const url = shop.productUrl('vintage-tee');
</script>

Security model

• The embed key is publishable — it is meant to live in page HTML. It is read-only and locked to the origins you listed at creation time; the OrbioShop API rejects it from any other origin (CORS + server-side origin check).
• The widgets never mutate: no add-to-cart, checkout, or wishlist from the embed. All purchases happen on your storefront after the deep-link.
• All product data is HTML-escaped before rendering, so product copy can't inject script into the embedding page.

Cart-from-embed (in-place add-to-cart) is a separate, write-keyed integration exposed via OrbioShopWidgets.initAllWidgets(). Do not use a write-scoped key in a public page — only the read-only embed key is safe to publish.

License

MIT