Expivi Shopify Embedding

How to embed the Expivi 3D configurator in your Shopify product page

Thanks for choosing to use Expivi‘s 3D configurator to create  a complete and unique customer experience for your Shopify store!

We‘ve created this guide to show you how you can integrate the Expivi 3D configurator in your Shopify store.

We assume that you have already setup the products in your Shopify store that need to be connected to the products you’ve setup in Expivi.

Head over to Knowledge Base if you’d like to learn how to setup products in Expivi.

How to integrate the Expivi viewer and options in a Shopify product page

To integrate the Expivi viewer and the options within a Shopify theme product page you need to do the following 6 steps.

Steps overview:

  1. Follow the steps 1-3 as described in the Expivi Shopify Integration documentation page
  2. Add HTML tags to the “theme.liquid”
  3. Copy and paste the “expivi-embedded” code into your theme
  4. Add “Metafields Guru” plugin to your theme
  5. Add metafield to Shopify product to connect the Expivi product
  6. Change your “product-template.liquid” to include the new “expivi-embedded.liquid” code

1. Install the Expivi plugin for Shopify

Follow steps 1 to 3 of the Expivi Shopify Integration documentation on our Knowledge Base

These steps will guide you through the setup of the Expivi Shopify plugin that is required to integrate the embedded version of the Expivi viewer and options. Make sure to follow these steps carefully so you are prepared for the further steps.

2. Add HTML tags to the theme.liquid

Integrating Expivi with your Shopify storefront requires some modifications to the theme files of the theme you’re using for your Shopify storefront. If you have no knowledge to do this yourself, please ask a developer to do this for you.

Be aware that each theme has its own unique code, so the instructions below should be used as an example.

Go to Online Store > Themes and select Edit code in the Actions drop down menu (Figure 1). You’ll be taken to the template files editor.

Figure 1

In order to have the Expivi configurator function properly, a few scripts need to be added to the <head> tag in your “theme.liquid” file.

2.1 Adding the <meta> tag

First, a meta tag needs to be added to tell the Expivi plugin that you are using the embedded version, by adding the following line.

<meta name="expivi-embedded" content="true">

2.2 Adding the <link> tag

Then we need to add the style of the “ExpiviComponent” by adding the next line:

<link href="{api_asset_url}/ExpiviComponent.css" rel="stylesheet" />

Note: replace the “{api_asset_url}” in the line above with the provided asset URL that you got from the Expivi support team.

2.3 Adding the <script> tags

The last step is adding some scripts to make the Expivi configurator function properly. These scripts also need to be added to the <head> tag.

<script src="{api_asset_url}/vendor.lib.js"></script>
<script src="{api_asset_url}/index.js"></script>
<script src="{api_asset_url}/ExpiviComponent.js"></script>

Note: replace the “{api_asset_url}” in the line above with the provided asset URL that you got from the Expivi support team.

After you have done this, your “theme.liquid” should look like something shown in figure 2.

Figure 2

3. Copy and paste the Expivi embed code into your theme

In order to add the Expivi 3D configurator to your product page you need to add a new file to your theme. This file needs to be named “expivi-embedded.liquid” and added to the “snippets” folder. You can do this by following the following steps:

  1. Go to your theme file explorer “snippets” folder (figure 3)

    Figure 3
  2. Click Add a new snippet (figure 4)

    Figure 4
  3. Enter the name “expivi-embedded” and click “Create snippet” (figure 5)

    Figure 5
  4. When the file has been created, copy and paste the complete code on the next page to new file

Note: Replace “{api_key}” in the following code snippet on line 61 with the API key that you generated from the Expivi backend (https://admin.expivi.net/). It should be the same “API key” as you’ve entered earlier in the Expivi Shopify plugin settings.

<div class="expivi-single-product-container">
  <div class="expivi-viewer-container">
    <div id="viewerContainer"></div>
  </div>
  <div class="expivi-option-container">
    <div id="priceContainer"></div>
    <div id="optionsContainer"></div>
  </div>
</div>
<div>
  <button class="btn expivi-add-to-cart" data-expivi-save data-product-id="{{ product.id }}" data-url="/cart">
    Add to cart
  </button>
</div>
<script type="text/javascript">
  var apiToken = '{api_key}'; 
      window.expiviInstance = ExpiviComponent({
        catalogueId: {{product.metafields.expivi.product_id}},
        viewerContainer: "#viewerContainer",
        optionContainer: "#optionsContainer",
        priceSelectors: '#priceContainer',
        token: apiToken
  });   
</script>
<style>  
  .expivi-single-product-container {
      display: table;
  height: 500px;
  width: 100%;
    }
    .expivi-single-product-container .expivi-viewer-container {
  display: table-cell;
  width: 64%;
  padding-right: 15px;
  vertical-align: top;
  }   
  .expivi-single-product-container .expivi-viewer-container #viewerContainer {
        display: block;
        width:100%;
        height:100%;
        min-height: 100%;
    }  
    .expivi-single-product-container .expivi-option-container {
  height: 100%;
        display: table-cell;
        width: 36%;
    }  
    .expivi-add-to-cart {
      float: right;
    }  
    @media (max-width: 600px) {    
      .expivi-single-product-container {
        display: block;
        height: unset;
      }   
      .expivi-single-product-container .expivi-viewer-container {
        display: block;
        width: 100%;
        padding-right: 0;
        height: 50vh;
      }    
      .expivi-single-product-container .expivi-option-container {
        height: initial;
        display: block;
        width: 100%;
      }
    }  
</style>

4. Add “Metafields Guru” plugin to your theme

Note: If you already have “Metafields Guru” added to your theme you can skip this step.

Go to https://apps.shopify.com/metafields-editor-2 and click Add app. If you are not yet logged into the Shopify app store, there will be a prompt to login. Please login and afterwards you will be met with the page shown in Figure 6.

Figure 6

Click Install app to add the Metafields Guru plugin to your theme. In the next step you will setup this plugin for the Expivi 3D configurator.

5. Add metafield to Shopify product to connect with Expivi product

Navigate to your Shopify product that you connected with an Expivi product in step 3 of Expivi Shopify Integration. Under the More actions dropdown you will find an option that says Edit Metafields (figure 7).

Figure 7

Once you click on that you can add a new metafield to this product by clicking Create Metafield. This is necessary for the distinguishment between an Expivi 3D configurator on the product page or a standard visualization on the product page.

Create the new metafield as follows. Make sure that the key is called “product_id” (the underscore between product and id is mandatory). Fill in “Expivi” as the namespace. As for the actual value, you want to use the ID that is in the Expivi backend. You can find this under Catalogue in the table as shown in figure 8.

Figure 8

The metafield input fields should look like shown in figure 9.

Figure 9

Don’t forget to click Save to complete adding the metafield.

6. Change your theme file to include the embed code

This the final step to complete the integration.

This following change is very dependent on your theme and can look a little different compared to the example. We need to add a check on the product page to see if we should load the embedded Expivi 3D configurator or if we should show the standard visualization.

The code looks like this:

{% if product.metafields.expivi.product_id %}
  {% include 'expivi-embedded' %}
{% else %}
  <!-- PUT THE ORIGINAL PRODUCT PAGE HTML IN HERE -->
{% endif %}

Depending on how you implement it, it would result in as shown in figure 10 and 11.

Figure 10
Figure 11

As you can see the first part of the code is on line 8-10. After this part the standard visualization is implemented. The last part of the code the “{% endif %})” is put on line 262 after the implementation of the standard visualization.

The result

If you have followed this step by step guide you will see an embedded viewer of the product that you have connected to that product page. It will look like as shown in figure 12.

Figure 12

Well done!

You’ve successfully integrated the Expivi 3D configurator in your Shopify store!