WordPress (WooCommerce) + 3D Viewer

This guide outlines the process of integrating the iJewel 3D Viewer into WordPress using Twenty Twenty-Four or related themes with WooCommerce. The iJewel 3D Viewer added Model Viewer on the Product Display Page(PDP), offering high-quality rendering for jewelry and fashion items, and additional features like custom configurators, post-processing effects, AR TryOn etc

Prerequisites

• Access to your Wordpress admin portal
• Understanding of Wordpress & Woocommerce theme structure
• Basic Familiarity with HTML, CSS, and JavaScript
• iJewel3D SDK Website License. Check out the license page for more details.

TIP

If you are looking for a development team for the integration, check our Development Partners

Step 1: Install and Activate ACF Plugin

1. Go to Plugins > Add New in the WordPress dashboard.
2. Search for Advanced Custom Fields
3. Install and activate the plugin.

TIP

This Plugin is required to create custom field for product.

Step 2: Create a Custom Field for .glb File Upload

1. Go to Custom Fields > Add New.
2. Add a field group title 3D Model.
3. Click Add Field to create a new custom field.

• Field Label: 3D Model (.glb)
• Field Name: 3d_model
• Field Type: Select File from the dropdown menu.
• Return Format: Choose File URL (you'll need the URL to load the model later).

4. Under Location, set Show this field group if to:

• Post Type is equal to Product.

5. Click Publish.

Step 3: Display the .glb File on the Product Page

To display the 3D model on the front-end WooCommerce product page, you need to modify your WooCommerce product template.

Modify Product Image Gallery Template (Optional)

If you want more control over how and where the custom image appears, you can override the WooCommerce product gallery template.

1. Copy the WooCommerce Template:

• Copy the template from wp-content/plugins/woocommerce/templates/single-product/product-image.php to your theme folder under your-theme/woocommerce/single-product/product-image.php.

2. Modify the Template:

• In the copied template file, you can add your custom image logic. For example, add the custom image right before or after the existing gallery:

product-image.php

// 3D model viewer
if(get_field('3d_model'))
{
echo '<div id="viewer-root" class="ij-model-product woocommerce-product-gallery__image slide" style="width: 100%; height:
100%"></div>';
}

This will display the custom image either before or after the main product images in the gallery.

INFO

Some theme may have custom products image gallery slider. This may require some developer attention.

Step 4: Add code into theme function.php

1. Go to project_folder/wp-content/themes/
2. Add the following code in the bottom of function.php file.
3. Save the file

function.php

// 3D model viewer
function ij_custom_javascript() {
    ?>
	<script src="https://releases.ijewel3d.com/libs/mini-viewer/0.1.9/bundle.iife.js"></script>
    <script type="module">
        const project = {
          modelUrl: "<?php the_field('3d_model'); ?>",
          // Additional project configuration
        }; 
        const viewerOptions = {
          showLogo: true,
          showCard: true,
          diamondKey: "DOMAINKEYHERE"
          // Additional viewer options
        }; 
        new ijewelViewer.Viewer(document.getElementById("viewer-root"), project, viewerOptions); 
        window.addEventListener("webgi-viewer-ready", async (ev) => {
          const viewer = ev.detail.viewer;
          // Additional actions to perform with the viewer instance
        });
</script>
    <?php
}
add_action('wp_head', 'ij_custom_javascript');
// Allow Upload
add_filter('upload_mimes', function($mime_types) {
    $mime_types['gltf'] = 'model/gltf+json';
    $mime_types['glb'] = 'model/gltf-binary';
    return $mime_types;
  });

  add_filter('wp_check_filetype_and_ext', function($data, $file, $filename, $mime_types, $real_mime_type) {
    if (empty($data['ext'])
        || empty($data['type'])
    ) {
        $file_type = wp_check_filetype($filename, $mime_types);
        if ('gltf' === $file_type['ext']) {
            $data['ext']  = 'gltf';
            $data['type'] = 'model/gltf+json';
        }
        if ('glb' === $file_type['ext']) {
            $data['ext']  = 'glb';
            $data['type'] = 'model/glb-binary';
        }
    }
    return $data;
  }, 10, 5);

Step 5: Styles and Customize (Optional)

Next, we need to add some css styles as per design. You can add these css styles into Appearance > Customize > Additional CSS

#mini-viewer #webgi-wrapper+.absolute button {
  display: none !important;
}
#webgi-wrapper button.z-0 {
  padding-left: 10px;
  padding-right: 10px;
  margin: 0;
}
.row-small>.flickity-viewport>.flickity-slider>.col.ij-item a::before {
  content: "";
  position: absolute;
  right: 5px;
  top: 5px;
  z-index: 1;
  width: 25px;
  height: 25px;
  background: url('image/3d-rotate-icon-1.svg');
  background-repeat: repeat;
  background-repeat: no-repeat;
  opacity: 0.6;
}
.ij-model-product {
  min-height: 640px;
}
@media (max-width:1350px){
.ij-model-product {
  min-height: calc(50vw - 30px);
  max-height: 640px;
}
}
button.group {
  color: #000;
}
@media(max-width:849px) {
  .ij-model-product {
    min-height: calc(58vw - 30px);
  }  
}
@media(max-width:549px) {
  .ij-model-product {
    min-height: calc(100vw - 30px);  }
}

INFO

Note that you need to adjust css properties as per design needs.

Save all modified changes

Step 6: Add 3D Models to Products

Once you've done above process Add new or Edit product.

1. Navigate to WooCommerce > Products.
2. Choose a product, or create a new product.
3. You should see an option to upload 3D model.
4. Upload a GLB or GLTF file

• Test model: Download Test Model

5. Save the changes

Step 7: Test the Integration

1. Preview the product page with the 3D model and the theme.
2. Verify that the iJewel viewer loads correctly and functions as expected
3. Test on various devices and browsers to ensure compatibility

Troubleshooting

• If the viewer doesn't appear, check the browser console for JavaScript errors
• Ensure all file paths are correct in your theme files
• Verify that the 3D model file is in a supported format (GLB or GLTF)

Next Steps

• Explore additional iJewel SDK features and integrate them as needed
• Check out other products at iJewel3D

Remember to thoroughly test your changes before pushing the updated theme live. Regularly check for updates to the Theme, WooCommerce Plugin and the iJewel SDK to ensure compatibility and access to new features.

Contact

For any questions or assistance with the integration, or questions about the license, email us at [email protected],