Articles on: API

Dynamic USDZ Viewer

Dynamic USDZ Viewer

The dynamic AR is a completely different product of ours, called the Dynamic USDZ Viewer (with a similar but separate tier pricing than the Dynamic 3D Viewer), with a slightly different implementation.

Embed code

For the dynamic USDZ viewer to work correctly, you should disable the web AR in the 3D Viewer, which does not support dynamically updated texture. Instead, for dynamic AR experience on iOS devices, you need to add an embed code of the following format to your page:

<div id="sayduck-dynamic-usdz-viewer-container"
    "launch-on-load": true, // if false, the user will need to tap on the loaded
                            // icon/preview to launch the AR experience.
                            // if true, the Dynamic USDZ Viewer will not add any visible element to the site 
                            // but automatically launch the AR experience on each new image loaded.
    "previewUrl": "[a preview url]"   // the Dynamic USDZ Viewer will show the preview image with an 
                                      // AR Quick Look icon in the top right corner.
                                      // If you do not pass a preview, only the AR Quick Look icon itself is displayed
                                      // In both cases, the preview/icon will fill in 100% of the height and width
                                      // of the container div
     "replacements": [
        "image-url": "[the image url to put on the product]",
        "map-fingerprint": "[TEXTURE_ASSET_FILE_NAME]"
      ... // possibly more than one image can be customized simultaneously on a given product
<script src=""></script>

Interact with the Viewer

Once you have the script embedded on the page, if you want to switch the texture again, you can use the following code (if launch-on-load is set, the AR experience will once again launch as soon as the new texture has been downloaded and applied):

document.dispatchEvent(new CustomEvent('sayduck.dynamicUsdzViewer.replace', {
  detail: {
    replacements: [
        "image-url": "[url-of-the-new-texture-to-apply]",
        "map-fingerprint": "[texture-to-replace-filename*]"


The Dynamic USDZ Viewer will sent an event when it has finished downloading the image and applying it to the 3D model (and launch the AR experience if launch-on-load is true). By listening to this event, you can show a loading indicator to your users as soon as you have requested a new image (or added the Viewer code to your site for the first time). You can then hide the loader when you receive the event.

    function() { // code to react to Dynamic USDZ Viewer ready }

Load viewer only on iOS devices

Finally, as you well now, Ar Quick Look is only supported on iOS device, and Dynamic USDZs are only supported from iOS 13. Thus, we recommend implementing the Dynamic USDZ Viewer only when devices meet those conditions. Here are helper functions you might want to use for checking support:

function isIosWebArSupported() {
  try {
    const a = document.createElement("a");
    return a.relList.supports("ar");
  } catch (e) {
    return false;

function isIos13OrOver() {
  if (/iP(hone|od|ad)/.test(navigator.platform)) {
    var v = navigator.appVersion.match(/OS (\d+)_(\d+)_?(\d+)?/);
    return parseInt(v[1], 10) > 12;
  return false;

Updated on: 04/04/2023

Was this article helpful?

Share your feedback


Thank you!