Shopify

1. Install the Orbital Vision Shopify App

Orbital Vision will provide you with a private installation link for the OV25 Shopify App. To get started:

1. Click the installation link provided by Orbital Vision
2. Log into your Shopify admin account if prompted (must be store owner)
3. Review and accept the app installation permissions

2. Configure Shopify Admin Settings

The Orbital Vision Shopify App allows you to integrate 3D product configurators into your Shopify store. To get started, you'll need to configure a few settings in your Shopify Admin. In the Shopify Admin, select the Orbital Vision App and navigate to the settings page.

Store Domain Configuration

Enter your Shopify store domain in the format:

shop.com

or

store.shop.com

API Key Configuration

You need to obtain and configure an API key with the productConfiguratorAccess type.

HTML Query Selectors

You need to configure query selectors for various page elements to properly integrate the configurator with your Shopify theme. Enter the appropriate CSS selectors for the following elements:

Gallery Selector

Where you want the configurator iframe to appear (usually replaces product images)

Example: .product-gallery or #ProductGallery

Variant Controls Selector

If you have existing controls that you want to replace, you can specify the classname in the ov25 admin panel. Otherwise (recommended), follow these steps:

1. Open the Shopify theme editor
2. Go into theme customization and add the ov25-controls block into the page where you want the variant controls to appear
3. Save the theme

Example: .product-variants or #ProductVariants

Price Selector

Where the product price is displayed

Example: .product-price or #ProductPrice

Name Selector

Where the product name is displayed

Example: .product-title or #ProductTitle

Additional Settings

Logo URL

The image that appears on the configurator UI when it is fullscreen.

Example: https://www.orbital.vision/logo.png

Auto Carousel

Turn on to automatically insert carousel underneath the 3D viewer/image gallery. This creates a slideshow of product images that users can browse alongside the 3D configurator.

Defer 3D

Turn on to use your product images first, and only switch to 3D when the user makes a variant selection. This improves initial page load time and provides a smoother user experience by loading the 3D scene in the background.

3. Linking Products

After configuring the settings, you need to link your Orbital Vision products to your Shopify products:

Product Linking Process

1. Navigate to the Products tab in the Orbital Vision Shopify App interface.

2. Select an Orbital Vision product from your catalog that you want to display on your Shopify store.

3. Select the corresponding Shopify product that should be linked to the Orbital Vision 3D configurator.

4. In the Shopify Admin, update the price of the Shopify product to match the base price of the Orbital Vision product.

5. Once linked, the product configurator will be active on your Shopify product page. Check the pricing and product are as expected.

4. Swatches Page Setup

The OV25 swatches page displays fabric samples from your entire range of products. Customers can make their selections and order a sample pack.

Setup Instructions

1. Visit https://app.orbital.vision/dashboard/api-keys and generate a privateApiKey.
2. Input this into the settings page of the Orbital Vision Shopify App in your Shopify admin.
3. In the Shopify Theme Editor, create a new template. Click "Add Section" and add the "OV25 Swatches" app block to the template.
4. Create a new page and assign it the new template.
5. Preview the page and consider styling it to match your site's theme.
6. Add a link to the swatches page in your site navigation, footer, or wherever it makes sense for your customers to discover it.

5. Custom App Integration

OV25 integrates with default Shopify themes, but custom Shopify storefronts may require some extra steps for full integration. This may require editing the .liquid files for any custom parts of your storefront that show or use pricing. It may also require some custom CSS styling.

Pricing

OV25 handles pricing of products and variants. These values are stored in an item's properties, and are accessible on Liquid line_item objects properties.

Shopify Line Item Documentation

OV25 provides analogues to four line_item properties. You should replace these in the .liquid code for any custom parts of your storefront that show or use pricing:

item.original_price --> ov25_original_price
item.original_line_price --> ov25_original_line_price
item.final_price --> ov25_final_price
item.final_line_price --> ov25_final_line_price

These properties are accessible via this syntax:

{{ item.properties['ov25_final_line_price'] }}

But we recommend defining them with a default value for when a product is not linked via OV25:

{%- assign ov25_original_price = item.properties['_ov25_original_price'] | default: item.original_price -%}
{%- assign ov25_total_price = item.properties['_ov25_original_price'] | default: item.original_line_price -%}
{%- assign ov25_original_line_price = ov25_total_price | times: item.quantity -%}
{%- assign ov25_final_price = item.properties['_ov25_product_price_discounted'] | default: item.final_price -%}
{%- assign ov25_final_line_price = ov25_final_price | times: item.quantity -%}

We also provide a property for the product's base price, without any variants:

{{ item.properties['_ov25_product_base_price'] }}

And for the product's OV25 SKU:

{{ item.properties['_ov25_product_sku'] }}

You can also calculate cart totals by summing prices for all items:

{%- assign ov25_cart_original_total_price = 0 -%}
{%- assign ov25_cart_total_price = 0 -%}
{%- for item in cart.items -%}
    {%- assign ov25_cart_original_total_price = ov25_cart_original_total_price | plus: ov25_final_line_price -%}
    {%- assign ov25_cart_total_price = ov25_cart_total_price | plus: ov25_final_line_price -%}
    ...
{%- endfor -%}
<div> {{ ov25_cart_original_total_price }} </div>
<div> {{ ov25_cart_total_price }} </div>

5. Variants

OV25 handles all variants. So either remove variants from products linked to OV25, or edit your .liquid to only show variants if item.properties['_ov25_product_id'] == nil.

6. Custom Checkout Buttons

Instead of using window.location = '/checkout', instead call window.requestOV25Checkout() on the onClick handler for your checkout button. All checkout buttons must point to the OV25 checkout. If using default checkout, any variant prices will not be shown, or shown as £0.00.

7. Express Checkout

Overview

Express/Accelerated checkout options (like Shop Pay, Apple Pay, or Google Pay) are not compatible with OV25 products due to their dynamic pricing nature. You'll need to conditionally hide these buttons when OV25 products are present in the cart.

Implementation

To properly handle express checkout buttons, follow these steps:

1. Check if any items in the cart are OV25 products
2. Hide express checkout buttons if OV25 products are found
3. Show express checkout buttons only for carts with standard Shopify products

Example Code

Here's how to implement this logic in your Liquid templates:

{% assign has_ov25_product = false %}
{% for item in cart.items %}
    {% if item.properties['_ov25_product_id'] != null %}
        {% assign has_ov25_product = true %}
        {% break %}
    {% endif %}
{% endfor %}
 
{% if has_ov25_product != true %}
    <div class="express-checkout-buttons">
        <span class="cart-express-checkout-divider">
            {{ 'sections.cart.use_express_checkout' | t }}
        </span>
    </div>
{% endif %}

8. V12 Integration

Overview

If you're using V12 Finance or other financing apps that calculate based on product prices, you'll need to configure them to use OV25's pricing instead of Shopify's default pricing. This ensures accurate finance calculations when products have variant-specific pricing.

Configuring V12

V12 Finance integration requires updating the price element selector in its initialization:

1. Locate your V12 initialization code that looks like:

Imm.Promo({
  // ... other configuration options ...
  priceElement: "your-current-selector"
})

2. Update the priceElement to point to the appropriate OV25 price element:
   • For product pages: use .ov25-configurator-price
   • For cart pages: use .cart-total-value

Example Configuration

Imm.Promo({
  // ... other options ...
  priceElement: ".ov25-configurator-price" // For product pages
})

9. Custom CSS

Some custom CSS on your page may interfere with the styling of the OV25 UI. You may also want to style the OV25 UI to match the rest of the theme. We have added IDs and classnames to many parts of the OV25 UI. You can use these to style the OV25 UI.