Manual Integration Guide

This guide is intended for developers or merchants using custom or legacy Shopify themes (which do not support OS 2.0 "drag & drop" App Blocks). By following this guide, you will be able to manually integrate ARShades services (VTO and 3D Viewer) directly into your theme's Liquid code.

Warning

This is an advanced guide that requires editing theme code files (.liquid). We strongly recommend creating a backup of your theme before proceeding.

---

1. Initial Configuration (Mandatory)

This step is fundamental to activate the service.

Where to insert: In the layout/theme.liquid file, before the closing </head> tag or just before </body>.

Code to copy:

<!-- ARShades Core Configuration -->
<script>
  window.ARShadesVTOConfig = {
    catalogueId: "{{ shop.metafields.arshades.catalogueId }}",
    shopDomain: "{{ shop.permanent_domain }}",
    language: "{{ request.locale.iso_code | slice: 0, 2 }}",
    singleSku: true, // Set to 'false' if there are multiple different glasses on the page
    
    // --- BASIC UI OPTIONS ---
    modalWidth: 90,           // Modal width % (default: 90)
    modalHeight: 90,          // Modal height % (default: 90)
    modalRadius: 16,          // Modal border radius px (default: 16)
    overlayOpacity: 80,       // Background opacity % (default: 80)
    loadingText: "Loading...",
    
    // --- MOBILE SPECIFIC OPTIONS ---
    modalWidthMobile: 100,    // Width on mobile (default: 100%)
    modalHeightMobile: 100,   // Height on mobile (default: 100%)
    modalRadiusMobile: 0,     // Border radius on mobile (default: 0)
  };
  
  // ARShades CDN Resources
  window.ARSHADES_CDN_URL = 'https://phpstack-686701-6034003.cloudwaysapps.com/arshades.js';
  window.ARSHADES_CDN_CSS_URL = 'https://phpstack-686701-6034003.cloudwaysapps.com/assets/arshades-vto-bundle.css';
</script>

<!-- ARShades Loader Script (Full Manual Integration) -->
<script>
(function() {
  'use strict';
  
  if (window.__ARSHADES_LOADER_LOADED__) return;
  window.__ARSHADES_LOADER_LOADED__ = true;

  // 1. Resources Configuration
  var BUNDLE_URL = window.ARSHADES_CDN_URL || 'https://phpstack-686701-6034003.cloudwaysapps.com/arshades.js';
  var BUNDLE_CSS_URL = window.ARSHADES_CDN_CSS_URL || 'https://phpstack-686701-6034003.cloudwaysapps.com/assets/arshades-vto-bundle.css';
  var config = window.ARShadesVTOConfig || {};

  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;
  }

  // Listen for bundle events and forward to Shopify
  window.addEventListener('arshades:vto:modal:open', function(e) {
    var payload = {
      catalogueId: config.catalogueId || null,
      catalogueVariantId: e.detail ? e.detail.catalogueVariantId : null,
      source: 'manual_integration'
    };
    // Modern event + Legacy for compatibility
    safePublish('arshades:vto_started', payload);
    safePublish('ars_vto_started', payload);
  });

  // 3. Resource Loading (Lazy Load)
  function loadResource(type, url) {
    return new Promise(function(resolve, reject) {
      var el;
      if (type === 'css') {
        if (document.querySelector('link[href="' + url + '"]')) return resolve();
        el = document.createElement('link');
        el.rel = 'stylesheet';
        el.href = url;
      } else {
        if (document.querySelector('script[src="' + url + '"]')) return resolve();
        el = document.createElement('script');
        el.src = url;
        el.async = true;
      }
      el.onload = resolve;
      el.onerror = reject;
      document.head.appendChild(el);
    });
  }

  // Initialize when DOM is ready
  function init() {
    Promise.all([
      loadResource('css', BUNDLE_CSS_URL),
      loadResource('js', BUNDLE_URL)
    ]).then(function() {
      if (window.ARShadesVTO && window.ARShadesVTO.init) {
        window.ARShadesVTO.init(config);
        console.log('[ARShades] Initialized manually');
      }
    }).catch(function(err) {
      console.error('[ARShades] Load error:', err);
    });
  }

  if (document.readyState === 'loading') {
    document.addEventListener('DOMContentLoaded', init);
  } else {
    init();
  }
})();
</script>

---

2. VTO Button Integration (Virtual Try-On)

Use this code to display the "Virtual Try-On" button on the product page.

Where to insert: Usually in sections/product-template.liquid or snippets/buy-buttons.liquid, near the "Add to Cart" button.

Metafields Logic: The code automatically checks if the current product has the associated ARShades Metafields.

Code to copy:

{%- comment -%} ARShades VTO Button Integration {%- endcomment -%}
{%- assign has_vto = false -%}
{%- for variant in product.variants -%}
  {%- if variant.metafields.arshades.catalogueVariantId != blank -%}
    {%- assign has_vto = true -%}
    {%- break -%}
  {%- endif -%}
{%- endfor -%}

{%- if shop.metafields.arshades.catalogueId != blank and has_vto -%}
  <div class="arshades-vto-container" style="margin-top: 10px; margin-bottom: 10px;">
    <button type="button" 
            id="arshades-manual-vto-btn"
            class="arshades-custom-btn"
            onclick="ARShadesVTO.openModal('{{ product.selected_or_first_available_variant.metafields.arshades.catalogueVariantId }}')">
      
      <!-- Optional Icon -->
      <svg width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
        <path d="M2 12s3-7 10-7 10 7 10 7-3 7-10 7-10-7-10-7Z"/>
        <circle cx="12" cy="12" r="3"/>
      </svg>
      
      <span>Virtual Try-On</span>
    </button>
  </div>

  <!-- Inline CSS styles for quick customisation -->
  <style>
    .arshades-custom-btn {
      width: 100%; 
      padding: 12px; 
      background: #000000; 
      color: #ffffff; 
      border: none; 
      border-radius: 4px; 
      cursor: pointer; 
      display: flex; 
      align-items: center; 
      justify-content: center; 
      gap: 8px;
      transition: background 0.3s ease;
    }
    .arshades-custom-btn:hover {
      background: #333333;
    }
  </style>

  <!-- Variant Change Handling -->
  <script>
    // NOTE: The 'variant:changed' event is a standard example.
    // Some themes (like Dawn) use different events or Web Components.
    // Check your theme documentation for the correct event name.
    document.addEventListener('variant:changed', function(e) {
      var btn = document.getElementById('arshades-manual-vto-btn');
      // Safe check on variant data
      var variantData = e.detail.variant;
      var vtoId = (variantData && variantData.metafields && variantData.metafields.arshades) 
                  ? variantData.metafields.arshades.catalogueVariantId 
                  : null;

      if(btn && vtoId) {
        btn.setAttribute('onclick', "ARShadesVTO.openModal('" + vtoId + "')");
        btn.style.display = 'flex';
      } else if(btn) {
        btn.style.display = 'none'; // Hide if variant has no VTO
      }
    });
  </script>
{%- endif -%}

---

3. 3D Viewer Button Integration

Use this code for the 3D Viewer (360° product visualisation).

Requirements: Requires arshades.viewerId in the Shop Metafields and arshades.catalogueProductId in the Variant Metafields.

Code to copy:

{%- comment -%} ARShades 3D Viewer Button {%- endcomment -%}
{%- if shop.metafields.arshades.viewerId != blank and product.selected_or_first_available_variant.metafields.arshades.catalogueProductId != blank -%}
  <button type="button" 
          class="arshades-3d-btn"
          onclick="ARShades3D.open('{{ product.selected_or_first_available_variant.metafields.arshades.catalogueProductId }}')">
    View in 3D
  </button>
  <style>
    .arshades-3d-btn {
      padding: 10px 20px; 
      background: #f0f0f0; 
      border: 1px solid #ccc; 
      border-radius: 4px; 
      cursor: pointer;
      margin-top: 10px;
    }
    .arshades-3d-btn:hover {
      background: #e0e0e0;
    }
  </style>
{%- endif -%}

---

4. Automatic Integration (Floating Widget)

If you prefer the button to appear automatically (e.g., bottom right) without modifying the product template.

Where to insert: layout/theme.liquid, before </body>.

Code to copy:

<div id="arshades-embed-root"></div>

<script>
  document.addEventListener('DOMContentLoaded', function() {
    // Check if we are on a product page and if VTO data exists
    var currentVariantId = "{{ product.selected_or_first_available_variant.metafields.arshades.catalogueVariantId }}";
    
    if (currentVariantId) {
      // You can pass style options directly here
      ARShadesVTO.createButton(currentVariantId, {
        mode: 'floating',
        position: 'bottom-right', // 'bottom-left', 'top-right', etc.
        text: 'Try On',
        color: '#000000',
        textColor: '#ffffff',
        borderRadius: 8,
        icon: true // Show glasses icon
      }).then(function(btn) {
        document.body.appendChild(btn);
      });
    }
  });
</script>

---

5. Advanced Customisation

You can deeply customise the ARShades experience via the global configuration object.

Configuration Options

You can add these keys to the window.ARShadesVTOConfig object in the "Initial Configuration" section:

Option	Type	Default	Description
modalWidth	Number	90	Modal width in % (Desktop)
modalHeight	Number	90	Modal height in % (Desktop)
modalRadius	Number	16	Modal border radius in px
modalWidthMobile	Number	100	Width on mobile %
modalHeightMobile	Number	100	Height on mobile %
overlayOpacity	Number	80	Dark background opacity (0-100)
modalBackground	String	'#ffffff'	Modal background colour (HEX)
loadingText	String	'Loading...'	Text shown during load

---

Technical Appendix: Metafields

The ARShades plugin automatically saves the necessary references in Shopify Metafields. If you need to retrieve them manually via code, here are the correct keys:

Shop Metafields (Global)

• shop.metafields.arshades.catalogueId: Your ARShades Catalogue ID.
• shop.metafields.arshades.viewerId: The ID for the 3D Viewer.
• shop.metafields.arshades.webDomain: The base domain (usually https://webvto.it).

Variant Metafields (SKU Specific)

• variant.metafields.arshades.catalogueVariantId: The unique variant ID for the VTO.
• variant.metafields.arshades.catalogueProductId: The 3D product ID.