=== 3D/AR/VR Model Viewer for WooCommerce ===
Contributors: racmanuel, freemius
Donate link: https://racmanuel.dev 
Tags: Augmented Reality, AR, Model Viewer, 3D, WooCommerce
Requires at least: 5.9
Tested up to: 7.1
Stable tag: 2.1.1
Requires PHP: 7.4
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

The AR Model Viewer for WooCommerce plugin shows 3D models on your website and in augmented reality. It supports product and variation models managed through WooCommerce, including .glb, .gltf and optional .usdz files.

== Description ==

The AR Model Viewer for WooCommerce is a versatile plugin designed to enhance your online store by displaying 3D models of your products. Customers can view these models in augmented reality (AR), providing an interactive and immersive shopping experience. The plugin supports .glb and .gltf files for browser viewing, with optional .usdz files for Apple AR, and is easy to use.

Whether your website is an eCommerce platform or a WooCommerce-based store, the AR Model Viewer plugin seamlessly integrates to allow customers to explore your products in 3D and AR.

Start offering an extraordinary shopping experience today! 🚀

The **AR Model Viewer for WooCommerce** is a practical plugin for showcasing your products in 3D and AR. Customers can interact with product models in an immersive way, improving their shopping experience and engagement.

### Key Features ✨  

- **Display 3D Models Anywhere**: Showcase 3D models of your products on any part of your website using a simple shortcode.  
- **Augmented Reality Viewing**: Allow customers to view your 3D models in augmented reality for an immersive shopping experience.  
- **Broad File Format Support**: Compatible with **.glb** and **.gltf** file formats for seamless 3D model integration.  
- **Effortless WooCommerce Integration**: Easily integrates with WooCommerce to enhance your eCommerce platform.  
- **Native Product and Variation Fields**: Manage model files, posters, AR options and fallback behaviour from the WooCommerce product editor.
- **Public REST Loading**: The viewer requests each product's model and public viewer configuration through a read-only REST endpoint, including for anonymous visitors.
- **Public REST Catalog**: Integrations can list published, catalog-visible products with effective 3D models through `GET /wp-json/ar-model-viewer/v1/products`.
- **Private REST Analytics**: Administrators with `manage_options` can read filtered, grouped anonymous aggregates through `GET /wp-json/ar-model-viewer/v1/analytics`.
- **External Model URLs**: Use hosted **.glb**, **.gltf** or **.usdz** files from a trusted source. The plugin stores and validates the model reference; it does not generate 3D assets through an external AI service.

### Why You Should Install This Plugin ✅  

- **Improve Customer Engagement**: Provide your customers with an interactive shopping experience that increases time spent on your store.  
- **Boost Conversion Rates**: Help customers make informed purchasing decisions by allowing them to visualize products in 3D and AR.  
- **Stay Ahead of the Competition**: Stand out in the eCommerce market by integrating innovative AR technology into your store.  
- **Easy to Use**: No advanced technical skills required; integrate and manage 3D models effortlessly.  
- **Flexible and Scalable**: Works perfectly for both small and large eCommerce businesses with WooCommerce.  
- **Seamless Integration**: Compatible with most WordPress themes and plugins, ensuring a smooth setup.  

### Pro Version 🚀  

Unlock the full potential of the AR Model Viewer for WooCommerce with the **Pro Version**, which includes additional premium features and support:  

- **Elementor Widget**: Display 3D models using a dedicated widget in Elementor.  
- **Bulk Import and Export**: Manage 3D models and viewer overrides using the native WooCommerce importer/exporter.
- **Direct AR Links and QR Codes**: Pro users can generate stable product/variation links and download local SVG or PNG QR codes.

## Quick start

1. Install and activate WooCommerce and AR Model Viewer for WooCommerce.
2. Open **Settings -> AR Model Viewer for WooCommerce** and choose whether the viewer should appear as a product tab, button, or both.
3. Edit a WooCommerce product and open **Product data -> 3D and augmented reality**.
4. Add the model URL, poster and AR settings. A variable product can keep the parent model or enable a separate model for each variation.
5. Add the viewer to another page with the shortcode below, replacing `123` with the product ID:

`[ar_model_viewer_for_woocommerce_shortcode id="123"]`

The shortcode accepts the `id` attribute only. Variation-specific data is resolved automatically on product pages when the shopper selects a variation.

## REST API

The API base URL is `https://example.com/wp-json/ar-model-viewer/v1`. Replace `example.com` with the site's domain.

- `GET /products`: public catalog of published products with an effective 3D model. Supports `page`, `per_page`, `search` and `category`.
- `GET /products/{product_id}/model`: public model and viewer configuration for one product. Add `?variation_id={variation_id}` to resolve a variation model and its parent fallback.
- `GET /analytics`: private, grouped aggregate analytics. Supports date, product, variation, event, mode, grouping and pagination filters. It requires the `manage_options` capability.
- `POST /events`: public event ingestion endpoint used by the viewer. It accepts validated anonymous events and does not store IP addresses, user agents or personal data.

The catalog and model endpoints are read-only and public so storefront visitors and external catalog integrations can use them. Analytics reads require an authenticated user with `manage_options`; analytics recording remains optional and disabled until enabled in the plugin settings.

## Direct AR links and QR codes

Direct AR pages are a Pro feature. The product-editor controls generate stable URLs in this format:

`https://example.com/ar-model-viewer/{product_id}/`

For a variation, append `?variation_id={variation_id}`. QR links append `&armvw_qr=1` (or `?armvw_qr=1` when no variation parameter exists) so the plugin can measure QR opens when analytics is enabled. Pro users can preview and download the generated QR code as SVG or PNG.

## Compatibility

- WordPress `5.9` or newer.
- WooCommerce `3.9` or newer, active before using product and variation fields.
- PHP `7.4` or newer.
- A modern browser with WebGL for 3D viewing. AR features depend on device and browser support for WebXR or the platform's AR handoff, such as Android Scene Viewer or Apple's USDZ flow.
- A `.glb` or `.gltf` model for browser viewing; add `.usdz` when Apple AR support is required.

### Open Source and Community Contribution 🌟  

This plugin is an open-source project, and the code is available on GitHub:  
[https://github.com/racmanuel/ar-model-viewer-for-woocommerce](https://github.com/racmanuel/ar-model-viewer-for-woocommerce)  

We invite you to contribute to the project by suggesting improvements, fixing issues, or enhancing features for the free version. Together, we can make this plugin even better for the WordPress community!  

## Try the plugin 👨🏻‍💻🎉

[Try with WordPress Playground](https://playground.wordpress.net/#ew0KICAgICIkc2NoZW1hIjogImh0dHBzOi8vcGxheWdyb3VuZC53b3JkcHJlc3MubmV0L2JsdWVwcmludC1zY2hlbWEuanNvbiIsDQogICAgInNpdGVPcHRpb25zIjogew0KICAgICAgICAiYmxvZ25hbWUiOiAiQVIgTW9kZWwgVmlld2VyIGZvciBXb29Db21tZXJjZSINCiAgICB9LA0KICAgICJzdGVwcyI6IFt7DQogICAgICAgICAgICAic3RlcCI6ICJpbnN0YWxsVGhlbWUiLA0KICAgICAgICAgICAgInRoZW1lWmlwRmlsZSI6IHsNCiAgICAgICAgICAgICAgICAicmVzb3VyY2UiOiAid29yZHByZXNzLm9yZy90aGVtZXMiLA0KICAgICAgICAgICAgICAgICJzbHVnIjogInN0b3JlZnJvbnQiDQogICAgICAgICAgICB9DQogICAgICAgIH0sDQogICAgICAgIHsNCiAgICAgICAgICAgICJzdGVwIjogImluc3RhbGxQbHVnaW4iLA0KICAgICAgICAgICAgInBsdWdpblppcEZpbGUiOiB7DQogICAgICAgICAgICAgICAgInJlc291cmNlIjogIndvcmRwcmVzcy5vcmcvcGx1Z2lucyIsDQogICAgICAgICAgICAgICAgInNsdWciOiAid29vY29tbWVyY2UiDQogICAgICAgICAgICB9DQogICAgICAgIH0sDQogICAgICAgIHsNCiAgICAgICAgICAgICJzdGVwIjogImluc3RhbGxQbHVnaW4iLA0KICAgICAgICAgICAgInBsdWdpblppcEZpbGUiOiB7DQogICAgICAgICAgICAgICAgInJlc291cmNlIjogIndvcmRwcmVzcy5vcmcvcGx1Z2lucyIsDQogICAgICAgICAgICAgICAgInNsdWciOiAiYXItbW9kZWwtdmlld2VyLWZvci13b29jb21tZXJjZSINCiAgICAgICAgICAgIH0NCiAgICAgICAgfSwNCiAgICAgICAgew0KCQkJInN0ZXAiOiAibG9naW4iLA0KCQkJInVzZXJuYW1lIjogImFkbWluIiwNCgkJCSJwYXNzd29yZCI6ICJwYXNzd29yZCINCgkJfQ0KICAgIF0sDQogICAgImxhbmRpbmdQYWdlIjogIi93cC1hZG1pbi9hZG1pbi5waHA/cGFnZT1hcl9tb2RlbF92aWV3ZXJfZm9yX3dvb2NvbW1lcmNlX3NldHRpbmdzIiwNCiAgICAicHJlZmVycmVkVmVyc2lvbnMiOiB7DQogICAgICAgICJwaHAiOiAiNy40IiwNCiAgICAgICAgIndwIjogIjYuNSINCiAgICB9LA0KICAgICJwaHBFeHRlbnNpb25CdW5kbGVzIjogWw0KICAgICAgICAia2l0Y2hlbi1zaW5rIg0KICAgIF0sDQogICAgImZlYXR1cmVzIjogew0KICAgICAgICAibmV0d29ya2luZyI6IHRydWUNCiAgICB9DQp9)

The Playground blueprint installs Storefront, WooCommerce and this plugin, uses WordPress `6.5` with PHP `7.4`, logs in as `admin` / `password` and opens the plugin settings. It is a demonstration environment and does not activate Pro-only features.

## Customization 🛠️

If you need any customization for the plugin, feel free to send me a message or visit my website: [https://racmanuel.dev](https://racmanuel.dev).

## Privacy Policy 🔒

The optional viewer analytics in AR Model Viewer for WooCommerce is first-party and disabled by default. A store administrator must enable it in Settings -> AR Model Viewer -> Analytics before the plugin records anything.

- The plugin stores anonymous daily counters in the site's own WordPress database.
- It records only event names, product IDs, variation IDs, AR mode, normalized error codes and duration buckets. Historical aggregates use variation ID `0`.
- It does not store IP addresses, user agents, referrers, names, emails, user IDs, cookies or complete model URLs.
- Visitors can exclude their browser with the privacy control shown in the viewer. The preference stays in local storage and is never sent to the site.
- Administrators can review the last 30 days and delete all stored analytics from the Analytics settings tab.
- The feature does not use a CMP, Google Analytics or another external analytics service.

The Freemius SDK may have its own separate product telemetry and consent flow. The viewer analytics described above is independent of that SDK.

Integrating the Freemius SDK **does not immediately start data collection without user confirmation**.

== Installation ==

This section describes how to install the plugin and get it working.

e.g.

1. Upload the plugin files to the `/wp-content/plugins/plugin-name` directory, or install the plugin through the WordPress plugins screen directly.
2. Activate the plugin through the 'Plugins' screen in WordPress.
3. Use the Settings -> AR Model Viewer for WooCommerce screen to configure the plugin.
4. Start adding 3D models to your WooCommerce products from the **3D and augmented reality** group inside the **General** tab of **Product data**. Variable products can configure their own variation models or inherit the parent product model.

== Updating from 2.1.0 or earlier ==

Install the 2.1.1 package over the existing plugin. Product models, variation settings, viewer options and existing analytics are preserved. Controls such as the product button, product tab and shortcode now remain hidden when the effective product or variation has no 3D model. Pro users should resave permalinks once so WordPress registers the `/ar-model-viewer/{product_id}/` rewrite route.

== Frequently Asked Questions ==  

= Which file types are required for the 3D models/scenes? =  
GLTF (*.glb) files are required for the 3D preview in the browser and the AR scenes on Android devices. Apple devices, such as iPhone, iPad, or Apple Vision Pro, require **USDZ** (*.usdz) files to display AR content. AR Model Viewer for WooCommerce also adds support for **Reality** (*.reality) files for Apple devices.  

= Do I have to add models for Android and iOS? =  
To ensure that all visitors to your website can see the AR scenes, each scene must have a dedicated model in both formats (.glb, .usdz) for Android and iOS/Apple devices. However, only a GLTF file is required for the 3D preview in the browser.  

= Can I use the generated 3D models for both Android and iOS? =  
Yes! Add a compatible .glb or .gltf file for the browser and a .usdz file when you need a dedicated iOS/Apple AR asset.

= Where can I find the plugin documentation? =  
You can find comprehensive documentation and support resources here:  
- [WordPress Plugin Directory](https://wordpress.org/plugins/ar-model-viewer-for-woocommerce/)  
- [GitHub Repository](https://github.com/racmanuel/ar-model-viewer-for-woocommerce)  
- [Official Plugin Page](https://racmanuel.dev/ar-model-viewer-for-woocommerce/)  

= Does the Pro version support bulk uploads of models? =
Yes. Pro users can use WooCommerce's native CSV importer/exporter for the 3D model URL, poster URL, alt text, USDZ URL, per-product switches (enabled, AR enabled, AR scale, AR placement, auto rotate) and per-product viewer overrides. It also supports a variation's files through the `AR Model Viewer: Variation ...` columns, so a catalogue of variable products survives an export and a new import with its fallbacks intact.

URLs are the reference the CSV carries, because they are what makes a file portable between installations. Attachment IDs are stored next to the URL for the editor, but they are never the only reference: an export from one site can be imported into another as long as the files are reachable.

An empty cell means "inherit from the parent product", and a column that is missing from the file leaves the stored value untouched. The importer does not download remote files into the Media Library; it validates and stores the URL.

= Can each variation use its own model? =
Yes. Every variation shows an **AR Model Viewer** block with a switch. While it is off, the variation uses the model, the USDZ file and the poster of the parent product. When it is on, the variation uses its own files, and any field left empty keeps inheriting from the parent. The viewer follows the variation the shopper selects without reloading the page.

= Does the public viewer use the WordPress REST API? =
Yes. The viewer loads a product's public model data at `/wp-json/ar-model-viewer/v1/products/{product_id}/model` with a read-only `GET` request. A variable product adds `?variation_id={variation_id}`, and the response always resolves the fallback to the parent product before it is returned. Administrative settings are not exposed through this endpoint. The legacy AJAX action remains available for compatibility.

= Does the plugin generate 3D models with an external AI service? =
No. The plugin displays models supplied by the store owner through WooCommerce fields or trusted model URLs. It does not include an external 3D-generation service.

= Are direct AR links and QR codes available? =
The direct AR route is available when the Pro plan is active for product and variation links. Pro users can generate stable links from the product editor and preview or download local SVG and PNG QR codes.

= Is there API documentation? =
Yes. The complete endpoint reference is in `docs/api.md`, with an OpenAPI description in `docs/openapi.yaml`.

= Is there support for Elementor? =  
Absolutely! The **Pro Version** includes a dedicated Elementor widget to display 3D models seamlessly on your website.  

= How can I contribute to the plugin? =  
This plugin is open source! You can contribute by suggesting improvements, fixing bugs, or adding new features via the GitHub repository:  
- [GitHub Repository](https://github.com/racmanuel/ar-model-viewer-for-woocommerce)  
We welcome all contributions from the community!  


== Mini-Tutorial: Getting Started ==

1. **Install and Activate**: Download and install the AR Model Viewer for WooCommerce plugin from the WordPress plugin repository.
2. **Configure Settings**: After activation, navigate to the Settings -> AR Model Viewer for WooCommerce screen to configure the basic settings for the plugin.
3. **Add 3D Models**: Go to the WooCommerce product edit page and open the **3D and augmented reality** group inside **Product data** to configure the model, poster, AR options and variation fallbacks.
4. **Preview in AR**: Once uploaded, your 3D models will automatically be available for customers to view in augmented reality (AR) on compatible devices.

== Screenshots ==

== Changelog ==  

1.0.5 - Update the tested up to 6.5 and added Appsero  
1.0.6 - Update the tested up to 6.5 and added Appsero  
1.0.7 - Removed the Appsero SDK and added Freemius SDK, tested up to 6.6 version of WordPress, removed uninstall.php, and on plugin deactivation, delete_option('ar_model_viewer_for_woocommerce_settings').  
1.0.8 - Fix: Optional parameter $content declared before required parameter $tag is implicitly treated as a required parameter in ar-model-viewer-for-woocommerce/public/class-ar-model-viewer-for-woocommerce-public.php on line 107.  
1.0.9 - Add assets/blueprints/blueprint.json for execution in WordPress Playground, added one-click "Try Plugin" in README.  
2.0.0 - Major Update:  
  - Simplified 3D model upload process: A **.glb** file is sufficient for browser viewing and Android AR; Apple AR can use an additional **.usdz** file when required.
  - Code optimization for better performance and faster load times.  
  - Implemented **AJAX** for dynamic 3D model loading, enhancing user experience.  
  - Added new **modal windows** to preview 3D models directly within the admin panel.  
  - Improved user interface for easier model management and configuration.  
  - Compatibility updates to ensure seamless operation with the latest WordPress versions.  
  - Various bug fixes and minor improvements.  
2.0.1 - Update Freemius SDK to 2.11.0 
2.0.2 - Updated the display name on wordpress.org to 3D/AR/VR Model Viewer for WooCommerce.
2.0.3 - Update to Freemius SDK and add support for non-logged users in AJAX call
2.1.0 - Added native WooCommerce product and variation model fields, public REST catalog and private analytics endpoints, and analytics for direct-link and QR opens. Pro adds product-editor direct AR links, local SVG/PNG QR generation and WooCommerce CSV import/export support.
2.1.1 - Fixed the product button, product tab and shortcode visibility so they are hidden when no effective 3D model is configured, while preserving parent-model inheritance for variations.

== Upgrade Notice ==  

= 2.1.1 =
Fixes viewer control visibility when a product has no effective 3D model and preserves model inheritance for variations. Includes the native WooCommerce fields, REST catalog, analytics, direct AR links and local QR features from 2.1.0.