Browser SDK reference

The CDN script registers <antla-block>, a browser custom element with its own Shadow DOM. It is a complete try-on interface, not a documented collection of importable JavaScript functions.

Installation

<script src="https://cdn.app-antla.com/antla-sdk/antla-sdk.js" defer></script>
<antla-block
  sdk-key="YOUR_ANTLA_SDK_KEY"
  product-id="gid://shopify/Product/123"
  variant-id="gid://shopify/ProductVariant/456"
  cart-url="/cart"
  language="EN"
></antla-block>

These examples use production hosts. Copy the exact script URL and key from your Antla installation if they differ.

Core attributes

Attribute	Required	Behavior
`sdk-key`	Yes	Antla SDK key for an enabled merchant connection. Changing it reinitializes the block.
`product-id`	Yes	Numeric string or Shopify Product GID. Changing it reloads product context and funnel.
`variant-id`	No	Numeric string or ProductVariant GID. A matching supplied variant is preferred; otherwise it chooses an available variant, then the first variant as a fallback.
`cart-id`	No	Full Storefront Cart GID, including any `?key=` portion. Synchronizes the SDK’s cart identity.
`cart-url`	No	Relative or HTTP(S) URL for the configured cart action. Defaults to `/cart`. Does not determine checkout URL.
`language`	No	Shopify LanguageCode, for example `EN` or `PT_BR`. Normalized to uppercase. Reinitializes the Storefront query using Shopify’s language context.

language affects the Storefront query. It is not a promise that all hardcoded SDK messages or all merchant-authored modal text are translated.

IDs must describe the currently displayed Shopify product and selected variant. Do not pass a variant from another product or a theme AJAX cart token in place of a Storefront Cart GID.

Launcher overrides

Launcher attributes are not taken from the merchant’s Antla app settings or the theme extension. The SDK uses the attribute value when it is set, and a built-in default when the attribute is omitted:

Attribute	Value
`launcher-button-text`	Visible launcher label
`launcher-show-promotional-text`	Set the literal string `"false"` to hide; other present values show it
`launcher-promotional-text`	Promotional line beside/below the launcher
`launcher-button-background-color`	CSS color
`launcher-button-text-color`	CSS color
`launcher-button-border-radius`	Number of pixels, clamped to 0-50

<antla-block
  sdk-key="YOUR_ANTLA_SDK_KEY"
  product-id="gid://shopify/Product/123"
  launcher-button-text="Try it on"
  launcher-show-promotional-text="false"
  launcher-button-background-color="#142c28"
  launcher-button-text-color="#ffffff"
  launcher-button-border-radius="8"
></antla-block>

Set launcher-button-border-radius whenever the corner radius matters. If the attribute is missing, the SDK uses 0. It does not fall back to the radius saved in Antla settings.

Modal styling, upload messaging, result behavior, email collection and related options are loaded from Antla’s shop settings. There are no documented attributes for every modal setting.

Cart behavior

On the result action, the SDK creates a cart or adds one unit of the selected available variant to an existing cart. It sets the element’s cart-id to the returned full cart ID.

The merchant’s buttonLeadsTo setting determines what happens after that cart mutation:

cart: navigate to cart-url or /cart.
checkout: navigate to Shopify’s returned checkout URL.
close: close the modal.

close still adds to cart in this implementation. See Cart integration.

Polling and storage

The SDK polls about every 1.5 seconds, with an initial request plus up to 100 further attempts. Network time adds to that duration. Custom API clients should poll about every two seconds, cancel work when the screen is gone, and set a UI timeout.

It shows a temporary preview for SUCCESS / PENDING, with result actions disabled while storage is pending. It proceeds to the final result when the poller receives a usable final URL. Its HTTP client turns failures into messages and does not implement a general automatic Retry-After recovery policy.

Local browser storage holds visitor identity, cached photo URL, email, consent choices and cart/try-on attribution. Keys are not namespaced by merchant. Do not host multiple independent merchant integrations on one shared browser origin without addressing state isolation.

Events and programmatic control

<antla-block> does not dispatch the antla_* events described in the theme documentation. There is no public open(), generate(), success callback, or error event.

Do not use private class methods or Shadow DOM selectors as a supported integration contract. Use the Headless API when your application needs a custom trigger, event analytics, native callbacks or complete UI control.

Browser and image boundaries

The SDK uses custom elements, Shadow DOM, modern browser APIs, local storage and optional camera access. Camera availability and image decoding depend on the browser/WebView. Test on the browsers your audience actually uses; no exhaustive supported-browser matrix is defined by this code.

Client image validation allows at most 10 MiB and varies accepted formats by generation model. See Images and uploads. Products with more than 100 variants or 30 images need special testing because the SDK queries fixed-size lists.

No published package-version compatibility policy or immutable versioned CDN URL is established here. Coordinate upgrades and validate the deployed script before launch.