Versione: 1.0.0

Ultimo aggiornamento: 25/03/2026

Guida all'Integrazione Manuale

Questa guida è destinata a sviluppatori o merchant che utilizzano temi Shopify personalizzati o legacy che non supportano gli App Blocks "drag & drop" di OS 2.0. Seguendo questa guida, puoi integrare manualmente ARShades VTO, Visualizzatore 3D e ARPDMeter direttamente nel codice Liquid del tuo tema.

warning

Questa è una guida avanzata che richiede la modifica dei file .liquid del tema. Crea un backup del tuo tema prima di procedere.

Prerequisiti

Prima di iniziare, assicurati di avere:

Il Plugin Shopify ARShades installato e la tua licenza collegata.
I prodotti sincronizzati — il plugin scrive automaticamente i metafield necessari negli oggetti Shop e Variant.
Accesso al codice del tuo tema (Online Store > Themes > Edit code).

Dove inserire il codice: Nel file del template prodotto (es. sections/main-product.liquid, sections/product-template.liquid, o snippets/buy-buttons.liquid), vicino al pulsante "Add to Cart".

Step 1: Lettura dei Metafield e Costruzione delle Mappe Varianti

Il primo blocco legge i metafield globali dello shop e itera sulle varianti del prodotto per costruire due mappe compatibili con JSON:

Mappa VTO: Associa ogni ID variante Shopify al suo catalogueVariantId ARShades.
Mappa 3D: Associa ogni ID variante Shopify a un oggetto contenente sia catalogueVariantId che catalogueProductId.

Se almeno una variante ha i metafield richiesti, il flag della funzionalità corrispondente (ars_has_vto / ars_has_3d) viene impostato su true.

{%- comment -%} ===== ARShades VTO + 3D Buttons ===== {%- endcomment -%}
{%- liquid
  assign ars_catalogue_id    = shop.metafields.arshades.catalogueId
  assign ars_web_domain      = shop.metafields.arshades.webDomain
  assign ars_viewer_id       = shop.metafields.arshades.viewerId
  assign ars_studio_domain   = shop.metafields.arshades.studioDomain
  assign ars_lang            = request.locale.iso_code | slice: 0, 2

  assign ars_has_vto = false
  assign ars_has_3d  = false
  assign ars_current_variant = product.selected_or_first_available_variant

  assign ars_vto_parts = ""
  for variant in product.variants
    if variant.metafields.arshades.catalogueVariantId != blank
      assign ars_has_vto = true
      assign entry = variant.id | append: '":"' | append: variant.metafields.arshades.catalogueVariantId | append: '"'
      if ars_vto_parts != ""
        assign ars_vto_parts = ars_vto_parts | append: ',"'
      else
        assign ars_vto_parts = '"'
      endif
      assign ars_vto_parts = ars_vto_parts | append: entry
    endif
  endfor

  assign ars_3d_parts = ""
  for variant in product.variants
    if variant.metafields.arshades.catalogueVariantId != blank and variant.metafields.arshades.catalogueProductId != blank
      assign ars_has_3d = true
      assign entry3d = variant.id | append: '":{"variantId":"' | append: variant.metafields.arshades.catalogueVariantId | append: '","productId":"' | append: variant.metafields.arshades.catalogueProductId | append: '"}'
      if ars_3d_parts != ""
        assign ars_3d_parts = ars_3d_parts | append: ',"'
      else
        assign ars_3d_parts = '"'
      endif
      assign ars_3d_parts = ars_3d_parts | append: entry3d
    endif
  endfor
-%}

Step 2: Rendering dei Pulsanti e Stili

I pulsanti vengono renderizzati solo se almeno una funzionalità è disponibile. Ogni pulsante ha una guardia aggiuntiva che verifica i metafield globali richiesti (es. catalogueId + webDomain per VTO, viewerId + studioDomain per 3D).

Il CSS fornisce pulsanti a larghezza piena su mobile e pulsanti centrati a larghezza automatica su desktop (breakpoint: 769px). Puoi personalizzare la classe .vto-button per adattarla al tuo tema.

{%- if ars_has_vto or ars_has_3d -%}
<style>
  .arshades-buttons-row .vto-button {
    width: 100%;
  }
  @media (min-width: 769px) {
    .arshades-buttons-row {
      justify-content: center !important;
    }
    .arshades-buttons-row .vto-button {
      width: auto !important;
      min-width: 0 !important;
      max-width: none !important;
      flex: 0 0 auto !important;
      padding-left: 32px !important;
      padding-right: 32px !important;
    }
  }
</style>
<div class="arshades-buttons-row"
     style="display:flex; gap:10px; padding:12px 5px; justify-content:center;">

  {%- if ars_has_vto and ars_catalogue_id != blank and ars_web_domain != blank -%}
    <button type="button" id="arshades-btn-vto" class="vto-button">
      {{- 'virtual-try-on.svg' | inline_asset_content -}}
      {{- 'products.vto.button.label' | t | default: 'Virtual Try-On' -}}
    </button>
  {%- endif -%}

  {%- if ars_has_3d and ars_catalogue_id != blank and ars_viewer_id != blank and ars_studio_domain != blank -%}
    <button type="button" id="arshades-btn-3d" class="vto-button">
      <svg width="22" height="22" viewBox="0 0 24 24" fill="none" stroke="currentColor"
           stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
        <path d="M12 2L2 7l10 5 10-5-10-5z"/>
        <path d="M2 17l10 5 10-5"/>
        <path d="M2 12l10 5 10-5"/>
      </svg>
      View in 3D
    </button>
  {%- endif -%}
</div>

Nota: Il pulsante VTO usa 'virtual-try-on.svg' | inline_asset_content e 'products.vto.button.label' | t. Se questi asset/traduzioni non sono disponibili nel tuo tema, sostituisci con un'icona SVG inline e una stringa di etichetta fissa.

Step 3: Incorporamento Dati come JSON

Le mappe varianti costruite nello Step 1 vengono emesse come blocchi <script type="application/json">. Questo mantiene i dati accessibili a JavaScript senza eseguirli direttamente, ed evita problemi con l'escaping di Liquid all'interno degli script inline.

Dati VTO includono l'ID catalogo, l'URL base per l'iframe VTO, la lingua dello store e la mappa variante-a-catalogueVariantId.

Dati 3D includono l'ID viewer, l'URL base di Studio e una mappa varianti dove ogni voce ha sia variantId che productId.

{%- if ars_has_vto -%}
<script type="application/json" id="arshades-vto-data">
{
  "catalogueId": {{ ars_catalogue_id | json }},
  "shopifyProductId": {{ product.id | json }},
  "baseUrl": {{ ars_web_domain | json }},
  "language": {{ ars_lang | json }},
  "currentVariantId": {{ ars_current_variant.id | json }},
  "variants": { {{- ars_vto_parts -}} }
}
</script>
{%- endif -%}

{%- if ars_has_3d -%}
<script type="application/json" id="arshades-3d-data">
{
  "viewerId": {{ ars_viewer_id | json }},
  "catalogueId": {{ ars_catalogue_id | json }},
  "shopifyProductId": {{ product.id | json }},
  "baseUrl": {{ ars_studio_domain | json }},
  "currentVariantId": {{ ars_current_variant.id | json }},
  "variants": { {{- ars_3d_parts -}} }
}
</script>
{%- endif -%}

Step 4: JavaScript — Utilità

Il blocco script racchiude tutto in un IIFE per evitare di inquinare lo scope globale. Inizia con due sezioni di utilità:

Bridge Shopify Analytics

safePublish() inoltra gli eventi a Shopify.analytics.publish() così l'estensione Pixel ARShades può tracciare l'utilizzo di VTO/3D. Fallisce silenziosamente se l'API Shopify analytics non è disponibile.

Rilevamento Variante

getActiveVariantId() determina quale variante il cliente ha attualmente selezionato. Controlla, in ordine:

L'input del form prodotto (input[name="id"] o select[name="id"]) — funziona con la maggior parte dei temi.
Il parametro query URL ?variant= — fallback per temi che aggiornano l'URL alla selezione.
La variante inizialmente selezionata renderizzata da Liquid — fallback finale.

<script>
(function(){
  'use strict';

  function safePublish(eventName, payload) {
    try {
      if (window.Shopify && window.Shopify.analytics &&
          typeof window.Shopify.analytics.publish === 'function') {
        window.Shopify.analytics.publish(eventName, payload);
        return true;
      }
    } catch (e) { console.warn('[ARShades] publish error', e); }
    return false;
  }

  function getActiveVariantId(fb){
    var i = document.querySelector('input[name="id"], select[name="id"]');
    if(i && i.value) return String(i.value);
    var p = new URLSearchParams(window.location.search);
    var v = p.get('variant');
    if(v) return String(v);
    return String(fb || '');
  }

Step 5: JavaScript — Sistema Modale

Il sistema modale crea un overlay a piena viewport con un iframe, uno spinner di caricamento e un pulsante di chiusura. Caratteristiche principali:

Creazione lazy: getOrCreateModal() crea gli elementi DOM solo al primo utilizzo.
Stato di caricamento: Uno spinner viene mostrato finché l'iframe non termina il caricamento (iframe.onload).
Trigger di chiusura: Il pulsante X, il click sull'overlay scuro, o la pressione di Escape.
Blocco scroll: document.body.style.overflow = 'hidden' impedisce lo scrolling dello sfondo.

Lo stesso sistema modale viene riutilizzato sia per VTO che per 3D — ognuno ha il proprio modalId così non entrano in conflitto.

  function getOrCreateModal(modalId, loadingText) {
    var existing = document.getElementById(modalId);
    if (existing) return existing;

    var overlay = document.createElement('div');
    overlay.id = modalId;
    overlay.setAttribute('style',
      'display:none;position:fixed;top:0;left:0;width:100%;height:100%;' +
      'z-index:2147483647;background:transparent;' +
      'align-items:center;justify-content:center;'
    );
    overlay.innerHTML =
      '<div style="position:absolute;inset:0;background:rgba(0,0,0,0.8);' +
        'cursor:pointer;z-index:1;" data-close></div>' +
      '<div style="position:relative;z-index:2;width:90vw;height:90vh;max-width:1200px;' +
        'background:#fff;border-radius:12px;overflow:hidden;' +
        'box-shadow:0 25px 80px rgba(0,0,0,0.5);">' +
        '<button data-close style="position:absolute;top:12px;right:16px;z-index:10;' +
          'background:rgba(255,255,255,0.95);border:none;width:44px;height:44px;' +
          'border-radius:50%;font-size:22px;cursor:pointer;color:#333;line-height:1;' +
          'display:flex;align-items:center;justify-content:center;' +
          'box-shadow:0 2px 12px rgba(0,0,0,0.2);">&times;</button>' +
        '<div class="ars-loader" style="position:absolute;inset:0;display:flex;' +
          'flex-direction:column;align-items:center;justify-content:center;gap:16px;' +
          'background:#fff;z-index:5;font-size:14px;color:#666;">' +
          '<div style="width:40px;height:40px;border:3px solid rgba(0,0,0,0.1);' +
            'border-top-color:#1a1a2e;border-radius:50%;' +
            'animation:ars-spin 0.8s linear infinite;"></div>' +
          '<span>' + (loadingText || 'Loading...') + '</span>' +
        '</div>' +
        '<iframe src="" frameborder="0" ' +
          'allow="camera *; microphone; gyroscope; accelerometer; xr-spatial-tracking" ' +
          'allowfullscreen style="width:100%;height:100%;border:none;display:block;">' +
        '</iframe>' +
      '</div>';

    if (!document.getElementById('ars-spin-style')) {
      var st = document.createElement('style');
      st.id = 'ars-spin-style';
      st.textContent = '@keyframes ars-spin{to{transform:rotate(360deg)}}';
      document.head.appendChild(st);
    }

    document.body.appendChild(overlay);
    overlay.querySelectorAll('[data-close]').forEach(function(el){
      el.addEventListener('click', function(){ closeModal(modalId); });
    });
    return overlay;
  }

  function openModal(modalId, url, loadingText) {
    var m = getOrCreateModal(modalId, loadingText);
    var iframe = m.querySelector('iframe');
    var loader = m.querySelector('.ars-loader');
    if (loader) loader.style.display = 'flex';
    iframe.src = url;
    iframe.onload = function(){ if(loader) loader.style.display = 'none'; };
    m.style.display = 'flex';
    document.body.style.overflow = 'hidden';
  }

  function closeModal(modalId) {
    var m = document.getElementById(modalId);
    if (!m) return;
    m.style.display = 'none';
    m.querySelector('iframe').src = '';
    var loader = m.querySelector('.ars-loader');
    if (loader) loader.style.display = 'flex';
    document.body.style.overflow = '';
  }

  document.addEventListener('keydown', function(e){
    if(e.key === 'Escape'){
      closeModal('arshades-modal-vto');
      closeModal('arshades-modal-3d');
    }
  });

Puoi personalizzare l'aspetto della modale modificando questi valori inline:

Parametro	Predefinito	Cosa controlla
`width:90vw;height:90vh`	90% viewport	Dimensione modale
`max-width:1200px`	1200px	Larghezza massima su schermi grandi
`border-radius:12px`	12px	Arrotondamento angoli
`background:rgba(0,0,0,0.8)`	80% opacità	Overlay scuro dietro la modale

Step 6: JavaScript — Handler Pulsante VTO

Quando il pulsante VTO viene cliccato, l'handler:

Legge i dati JSON da #arshades-vto-data.
Rileva l'ID variante Shopify attivo.
Cerca il corrispondente catalogueVariantId nella mappa (ricade sul primo disponibile se la variante corrente non è mappata).
Costruisce l'URL dell'iframe VTO con i parametri query richiesti.
Pubblica eventi analytics per il Pixel ARShades.
Apre la modale.

  window.addEventListener('message', function(event) {
    if (event.data && event.data.type === 'ars_vto_add_to_cart') {
      safePublish('arshades:vto_add_to_cart_clicked', {
        shopifyVariantId: event.data.variantId ? String(event.data.variantId) : null,
        shopifyProductId: event.data.productId ? String(event.data.productId) : null,
        source: 'vto_iframe_message'
      });
      safePublish('ars_vto_add_to_cart_clicked', {
        variantId: event.data.variantId ? String(event.data.variantId) : null,
        productId: event.data.productId ? String(event.data.productId) : null
      });
    }
  });

  var vB = document.getElementById('arshades-btn-vto');
  var vD = document.getElementById('arshades-vto-data');
  if(vB && vD){
    var vto = JSON.parse(vD.textContent);
    vB.addEventListener('click', function(){
      var sid = getActiveVariantId(vto.currentVariantId);
      var cid = vto.variants[sid];
      if(!cid){
        var k = Object.keys(vto.variants);
        if(k.length) cid = vto.variants[k[0]];
      }
      if(!cid){ alert('No VTO variant available'); return; }

      var url = vto.baseUrl
        + '?c=' + encodeURIComponent(vto.catalogueId)
        + '&m=' + encodeURIComponent(cid)
        + '&layout=v1'
        + '&lang=' + encodeURIComponent(vto.language || 'en')
        + '&sin=1';

      var payload = {
        shopifyVariantId: sid,
        shopifyProductId: vto.shopifyProductId ? String(vto.shopifyProductId) : null,
        catalogueId: vto.catalogueId,
        catalogueVariantId: cid
      };
      safePublish('arshades:vto_started', payload);
      safePublish('ars_vto_started', {
        variantId: sid,
        productId: vto.shopifyProductId ? String(vto.shopifyProductId) : null,
        catalogueId: vto.catalogueId
      });

      openModal('arshades-modal-vto', url, 'Loading...');
    });
  }

L'URL VTO viene costruito come segue:

Parametro	Valore	Descrizione
`c`	Catalogue ID	Identifica il tuo catalogo ARShades
`m`	Catalogue Variant ID	Il modello specifico da provare
`layout`	`v1`	Versione dell'interfaccia VTO
`lang`	Locale dello store (2 lettere)	Lingua dell'interfaccia
`sin`	`1`	Modalità SKU singolo (apre direttamente sulla variante selezionata)

Il listener dell'evento message gestisce le azioni add-to-cart attivate dall'interno dell'iframe VTO e le inoltra a Shopify analytics.

Step 7: JavaScript — Handler Pulsante 3D

L'handler 3D segue lo stesso pattern del VTO ma costruisce un URL diverso usando il dominio Studio e l'ID viewer.

Il formato dell'URL del visualizzatore 3D è:

{studioDomain}/Arshades3d/{viewerId}/glasses/{catalogueProductId}/variant/{catalogueVariantId}

  var tB = document.getElementById('arshades-btn-3d');
  var tD = document.getElementById('arshades-3d-data');
  if(tB && tD){
    var td = JSON.parse(tD.textContent);
    tB.addEventListener('click', function(){
      var sid = getActiveVariantId(td.currentVariantId);
      var obj = td.variants[sid];
      if(!obj){
        var k = Object.keys(td.variants);
        if(k.length) obj = td.variants[k[0]];
      }
      if(!obj){ alert('No 3D variant available'); return; }

      var url = td.baseUrl + '/Arshades3d/' + td.viewerId
        + '/glasses/' + obj.productId
        + '/variant/' + obj.variantId;

      safePublish('arshades:3d_opened', {
        shopifyVariantId: sid,
        shopifyProductId: td.shopifyProductId ? String(td.shopifyProductId) : null,
        catalogueId: td.catalogueId,
        viewerId: td.viewerId,
        catalogueVariantId: obj.variantId,
        catalogueProductId: obj.productId
      });

      openModal('arshades-modal-3d', url, 'Loading 3D...');
    });
  }
})();
</script>
{%- endif -%}
{%- comment -%} ===== END ARShades Buttons ===== {%- endcomment -%}

Integrazione Manuale ARPDMeter

Se il tuo tema non supporta gli App Blocks per il componente ARPDMeter, puoi integrare il pulsante PD Meter manualmente. Questo richiede che il bundle ARShades sia caricato (tramite l'App Embed vto-embed-loader o tramite lo script di caricamento manuale dell'integrazione VTO sopra).

Prerequisiti

Una licenza ARPDMeter attiva (shop.metafields.arshades.has_arpd deve essere "true").
Il bundle ARShades deve essere caricato sulla pagina (fornisce window.ARShadesVTO.openPDTool).
Il metafield dell'ID licenza deve essere presente (shop.metafields.arshades.licenseId).

Step 1: Verifica della Licenza e Lettura dei Metafield

Il primo blocco verifica se il modulo ARPDMeter è abilitato per questo store leggendo i metafield has_arpd e licenseId. Il pulsante viene renderizzato solo quando entrambe le condizioni sono soddisfatte.

{%- comment -%} ===== ARShades PD Meter Button ===== {%- endcomment -%}
{%- liquid
  assign has_arpd = shop.metafields.arshades.has_arpd
  assign licence_id = shop.metafields.arshades.licenseId
-%}

{%- if has_arpd == "true" and licence_id != blank -%}

Se la licenza non è attiva, puoi opzionalmente mostrare un placeholder nell'Editor Tema (solo modalità design):

{%- else -%}
  {%- if request.design_mode -%}
    <div style="padding: 16px; border: 1px dashed #ccc; border-radius: 8px;
                text-align: center; color: #888; font-size: 14px;">
      <p style="margin: 0 0 8px;">ARShades PD Meter</p>
      <p style="margin: 0; font-size: 12px;">
        This block requires an active ARPDMeter license.
        Activate it from the ARShades app settings.
      </p>
    </div>
  {%- endif -%}
{%- endif -%}

Step 2: HTML del Pulsante e Icona

Il pulsante include un'icona SVG mirino opzionale e un'etichetta di testo personalizzabile. Puoi sostituire l'icona con la tua o rimuoverla completamente.

<div class="arshades-pdmeter-container" data-arshades-pdmeter>
  <button type="button"
          id="arshades-pdmeter-button"
          class="arshades-pdmeter-button"
          aria-label="Measure PD">

    <!-- Default crosshair icon (replace or remove as needed) -->
    <svg class="arshades-pdmeter-icon" width="24" height="24"
         viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg"
         aria-hidden="true">
      <circle cx="12" cy="12" r="10" stroke="currentColor" stroke-width="1.5"/>
      <circle cx="12" cy="12" r="4" stroke="currentColor" stroke-width="1.5"/>
      <line x1="12" y1="2" x2="12" y2="6" stroke="currentColor"
            stroke-width="1.5" stroke-linecap="round"/>
      <line x1="12" y1="18" x2="12" y2="22" stroke="currentColor"
            stroke-width="1.5" stroke-linecap="round"/>
      <line x1="2" y1="12" x2="6" y2="12" stroke="currentColor"
            stroke-width="1.5" stroke-linecap="round"/>
      <line x1="18" y1="12" x2="22" y2="12" stroke="currentColor"
            stroke-width="1.5" stroke-linecap="round"/>
    </svg>

    <span>Measure PD</span>
  </button>
</div>

Step 3: Stile del Pulsante

Il CSS usa proprietà personalizzate CSS (CSS custom properties) così puoi facilmente sovrascrivere colori, raggio e dimensioni da un unico punto. Modifica i valori per adattarli al tuo tema.

<style>
  .arshades-pdmeter-container {
    --arshades-pd-primary: #000000;
    --arshades-pd-primary-hover: #333333;
    --arshades-pd-text: #ffffff;
    --arshades-pd-btn-radius: 8px;
    --arshades-pd-transition: 0.2s ease;
  }

  .arshades-pdmeter-button {
    display: inline-flex;
    align-items: center;
    justify-content: center;
    gap: 8px;
    width: 100%;
    padding: 14px 24px;
    background-color: var(--arshades-pd-primary);
    color: var(--arshades-pd-text);
    border: none;
    border-radius: var(--arshades-pd-btn-radius);
    font-family: inherit;
    font-size: 16px;
    font-weight: 600;
    cursor: pointer;
    transition: background-color var(--arshades-pd-transition),
                transform var(--arshades-pd-transition),
                box-shadow var(--arshades-pd-transition);
    text-decoration: none;
    line-height: 1.4;
  }

  .arshades-pdmeter-button:hover {
    background-color: var(--arshades-pd-primary-hover);
    transform: translateY(-1px);
    box-shadow: 0 4px 12px rgba(0, 0, 0, 0.15);
  }

  .arshades-pdmeter-button:active {
    transform: translateY(0);
  }

  .arshades-pdmeter-button:focus-visible {
    outline: 2px solid var(--arshades-pd-primary);
    outline-offset: 2px;
  }

  .arshades-pdmeter-icon {
    flex-shrink: 0;
    width: 24px;
    height: 24px;
  }
</style>

Variabile CSS	Controlla	Predefinito
`--arshades-pd-primary`	Colore di sfondo del pulsante	`#000000`
`--arshades-pd-primary-hover`	Colore stato hover	`#333333`
`--arshades-pd-text`	Colore testo del pulsante	`#ffffff`
`--arshades-pd-btn-radius`	Raggio angoli	`8px`

Step 4: JavaScript — Apertura PD Meter

Quando il pulsante viene cliccato, richiama ARShadesVTO.openPDTool() con il token di licenza, i colori dell'interfaccia, le dimensioni della modale e la lingua. Se il bundle è ancora in caricamento, il pulsante mostra lo stato "Loading..." e riprova automaticamente quando pronto.

Lo script ascolta anche due eventi dal PD Meter:

arshades:pdmeter:result — emesso quando la misurazione viene completata con successo.
arshades:pdmeter:error — emesso in caso di errori (es. licenza mancante), che disabilita il pulsante.

<script>
(function() {
  'use strict';

  var button = document.getElementById('arshades-pdmeter-button');
  if (!button) return;

  button.addEventListener('click', function() {
    if (window.ARShadesVTO &&
        typeof window.ARShadesVTO.openPDTool === 'function') {
      window.ARShadesVTO.openPDTool({
        licenseToken: {{ licence_id | json }},
        arpdPrimaryColor: '#42B1AC',
        arpdSecondaryColor: '#42B1AC',
        arpdModalWidth: 100,
        arpdModalHeight: 100,
        language: '{{ request.locale.iso_code | slice: 0, 2 }}'
      });
    } else if (window.ARShadesLoader &&
               !window.ARShadesLoader.isLoaded()) {
      button.textContent = 'Loading...';
      window.ARShadesLoader.onReady(function() {
        button.textContent =
          button.getAttribute('aria-label') || 'Measure PD';
        button.click();
      });
    } else {
      console.error(
        '[ARShades PD Meter] Bundle not loaded. ' +
        'Ensure vto-embed-loader is enabled in theme settings.'
      );
    }
  });

  window.addEventListener('arshades:pdmeter:result', function(e) {
    console.log('[ARShades PD Meter] Result:', e.detail);
  });

  window.addEventListener('arshades:pdmeter:error', function(e) {
    if (e.detail && e.detail.code === 'LICENSE_MISSING') {
      button.disabled = true;
      button.style.opacity = '0.5';
      button.title = 'PD Meter license not active';
    }
  });
})();
</script>

Parametri `openPDTool`

Parametro	Tipo	Predefinito	Descrizione
`licenseToken`	String	—	Il tuo ID licenza ARShades (obbligatorio)
`arpdPrimaryColor`	String (HEX)	`#42B1AC`	Colore di accento primario nell'interfaccia di misurazione
`arpdSecondaryColor`	String (HEX)	`#42B1AC`	Colore secondario nell'interfaccia di misurazione
`arpdModalWidth`	Number	`100`	Larghezza modale in %
`arpdModalHeight`	Number	`100`	Altezza modale in %
`language`	String	`en`	Codice lingua a due lettere (supportate: `en`, `it`, `de`, `es`, `fr`)

Eventi PD Meter

Evento	Payload	Descrizione
`arshades:pdmeter:result`	`e.detail` — dati misurazione	Emesso quando l'utente completa una misurazione
`arshades:pdmeter:error`	`e.detail.code` — codice errore	Emesso in caso di errori (es. `LICENSE_MISSING`)

Note di Adattamento

Quando integri in un tema specifico, potresti dover modificare:

Icona SVG: Il pulsante VTO fa riferimento a 'virtual-try-on.svg' | inline_asset_content. Se non disponibile nel tuo tema, sostituisci con un SVG inline o rimuovi.
Filtro di traduzione: 'products.vto.button.label' | t usa i file locale del tuo tema. Sostituisci con una stringa fissa se la chiave non esiste.
Rilevamento variante: Il codice si basa su input[name="id"] / select[name="id"] per il rilevamento della variante. Se il tuo tema usa un meccanismo diverso (Web Components, eventi personalizzati), modifica getActiveVariantId().
Conflitti CSS: Se gli stili dei pulsanti del tuo tema sovrascrivono .vto-button, usa selettori più specifici o !important.

Appendice Tecnica: Metafield

Il plugin ARShades scrive automaticamente questi metafield quando la tua licenza è collegata e i prodotti sono sincronizzati.

Metafield dello Shop (Globali)

Metafield	Descrizione
`shop.metafields.arshades.catalogueId`	Il tuo ID Catalogo ARShades
`shop.metafields.arshades.webDomain`	URL base per VTO (es. `https://webvto.it`)
`shop.metafields.arshades.viewerId`	L'ID dell'istanza 3D Viewer
`shop.metafields.arshades.studioDomain`	URL base per il 3D Viewer (es. `https://studio.arshades.it`)
`shop.metafields.arshades.has_arpd`	`"true"` se il modulo ARPDMeter è attivo
`shop.metafields.arshades.licenseId`	ID licenza usato per autenticare le chiamate ARPDMeter

Metafield delle Varianti (Per-SKU)

Metafield	Descrizione
`variant.metafields.arshades.catalogueVariantId`	ID variante univoco per VTO e 3D
`variant.metafields.arshades.catalogueProductId`	ID prodotto per il 3D Viewer

Prerequisiti​

Step 1: Lettura dei Metafield e Costruzione delle Mappe Varianti​

Step 2: Rendering dei Pulsanti e Stili​

Step 3: Incorporamento Dati come JSON​

Step 4: JavaScript — Utilità​

Bridge Shopify Analytics​

Rilevamento Variante​

Step 5: JavaScript — Sistema Modale​

Step 6: JavaScript — Handler Pulsante VTO​

Step 7: JavaScript — Handler Pulsante 3D​

Integrazione Manuale ARPDMeter​

Prerequisiti​

Step 1: Verifica della Licenza e Lettura dei Metafield​

Step 2: HTML del Pulsante e Icona​

Step 3: Stile del Pulsante​

Step 4: JavaScript — Apertura PD Meter​

Parametri openPDTool​

Eventi PD Meter​

Note di Adattamento​

Appendice Tecnica: Metafield​

Metafield dello Shop (Globali)​

Metafield delle Varianti (Per-SKU)​

Prerequisiti

Step 1: Lettura dei Metafield e Costruzione delle Mappe Varianti

Step 2: Rendering dei Pulsanti e Stili

Step 3: Incorporamento Dati come JSON

Step 4: JavaScript — Utilità

Bridge Shopify Analytics

Rilevamento Variante

Step 5: JavaScript — Sistema Modale

Step 6: JavaScript — Handler Pulsante VTO

Step 7: JavaScript — Handler Pulsante 3D

Integrazione Manuale ARPDMeter

Prerequisiti

Step 1: Verifica della Licenza e Lettura dei Metafield

Step 2: HTML del Pulsante e Icona

Step 3: Stile del Pulsante

Step 4: JavaScript — Apertura PD Meter

Parametri `openPDTool`

Eventi PD Meter

Note di Adattamento

Appendice Tecnica: Metafield

Metafield dello Shop (Globali)

Metafield delle Varianti (Per-SKU)