Custom Shopify Theme Integration Guide

This document describes the installation of Artifi's Shopify app with a custom theme. Store Administrators can install and configure your Artifi Product Personalization app using this document with their Shopify store.

Before Installation

Please check the below file schemas to make sure no special characters are available in schema JSON.

cart-template.liquid
theme.liquid
page.liquid
product.liquid

Installing the App

Next, install the Artifi Product Personalization app using the URL below:

https://shopify.artifi.net/index.php?shop=<shop-domain>

Note: <shop-domain> is Your Shopify Store Domain

After navigating to the installation URL, the Shopify Store Administrator will see the below screen. Click the "Install App" button to install the Artifi Product Personalization app.

Once the app is installed, the client will see the below screen and be redirected to the App Admin page.

After installation successfully, go to Artifi App Settings and fill in the below details. These details are required to link Shopify with Artifi using the given credentials.

Artifi App Settings Details

Setting	Details
Website ID	Whitelisted Website's Website ID in Artifi.
WebAPI Client Key	Web API client key provided by Artifi.
JS URL	Artifi's dependent Javascript URL is provided by Artifi.
Caption For Personalize Button	Changes the button label displayed to the shopper on the Product Detail Page button to initialize Artifi designer.
Caption for Add To Cart Button	Changes the button label displayed to the shopper on the Product Detail Page "Add to Cart" button.

Update the Shopify Theme

Select a theme to sync up content in Artifi, The Artifi app is using the theme code to update the content.

Note: If you change the store theme after app installation, you need to follow the below steps to update your new store theme with the app code.

Steps to Update Shopify Theme

Go to the Update Theme Tab
Select your current Theme
Click update. After the update is complete, go to the Artifi App Settings tab and save the settings again.

Verify Installation

Verify the below file content to make sure everything is added or not while installing the Artifi App in Shopify.

Note: You might need to manually add these code snippets if you are using a custom theme.

Change 1 - Theme.liquid

Loading Artifi.js & Artifi.css

Using the below theme.liquid file head tag code, Artifi is loading the Artifi.js and Artifi.css file.

Check the below code in the theme.liquid file. If not available, please include it with proper content. Also, make sure the PageId in the IF condition is correctly added.

Using this code will load the artifi.js and artifi.css files in the below pages.

Product Page
Cart Page
Personalize Page (PageId): Artifi will create this page at the time of App installation.

If <PageId> is missing in the IF condition, please navigate to Go to Online Theme -> Pages -> Personalize Page and find PageId from the URL.

https://domain.myshopify.com/admin/pages/56376197258

{% if template.name == 'product' or template.name == 'cart' or template.name == 'order' or page.id == <PageId> %}
  {{ 'artifi.css' | asset_url | stylesheet_tag }}
  <script src="{{ 'artifi.js' | asset_url }}"></script> 
{% endif %}

Change 2 - Updating the UserId

Add/validate this code is available in the footer of the theme.liquid file. By using this code Artifi is converting the guest UserId to Logged in userId.

Here are the details related to the Guest and Logged In User Id.

{% if customer %}
  <script>
    jQuery.get('/cart.js').complete(function (data) {
      var responseObject = JSON.parse(data.responseText);
      var updatedUserId = jQuery('#artifiUserId').val();
      var personalize_url = artifi_integration_url + '/Designer/Services/UpdateUserId?newUserId=' + updatedUserId + '&oldUserId=' + responseObject.token + '&websiteId=' + website_id + '&webApiClientKey=' + webapi_client_key;
      var cartToken = responseObject.token;
      jQuery.ajax({
        type: 'GET',
        url: personalize_url,
        success: function (data) {
          //console.log(‘User Id updated successfully’)
        }
      });
 
    });
  </script>
{% endif %}
<input type='hidden' name='artifiUserId' id='artifiUserId' value='{{ customer.id }}'></input>

Change 3 - Page.liquid

In this liquid, we are storing the customerID in a hidden field.

This field is mandatory to keep designs separately based on customerID.

<div class="rte">
  {% if page.title == 'Personalize' %}<input type='hidden' name='artifiUserId' id='artifiUserId'
    value='{{ customer.id }}'>{% endif %}{{ page.content }}
</div>

Change 4 - Product.liquid

On this page, Artifi is trying to get product metadata details from the product page.

{% for field in product.metafields.artifi %}
  <input type="hidden" id="{{ field | first }}" name="{{ field | first }}" value="{{ field | last }}">
{% endfor %}

Change 5 - Product-Template.liquid

Artifi displays and manages the Personalization button and Add to cart button action and label on this page. You may change this implementation based on your theme structure.

Here we have used the Narrative custom theme to display the Artifi. However, the liquid template may vary based on your themes.

Here, in this code, we maintain the “Product_id” and actions of the Personalize button based on the input given by the user in App>Artifi>Manage Product screen(Screenshot given below).

Please place the below code inside the “Product” form.

<input type="hidden" name="product_id" value="{{ product.id }}">
<!--  Assigning personalization value if personalize option is required / optional -->
  {% for field in product.metafields.artifi %}
    {% if field.first == 'isPersonalizationOptional'%}
      {% assign personalizevalue = field.last %}
    {% endif %}
  {% endfor %}
<!-- end artifi code -->

Change 6 - Product-Template.liquid

Artifi displays and manages the Personalization button and Add to cart button action and label on this page. You may change this implementation based on your theme structure.

Here we have used the Narrative custom theme to display the Artifi. However, the liquid template may vary based on your themes.

Here, in this code, we maintain the “Product_id” and actions of the Personalize button based on the input given by the user in App>Artifi>Manage Product screen(Screenshot given below).

Please place the below code inside the “Product” form.

<input type="hidden" name="product_id" value="{{ product.id }}">
<!--  Assigning personalization value if personalize option is required / optional -->
  {% for field in product.metafields.artifi %}
    {% if field.first == 'isPersonalizationOptional'%}
      {% assign personalizevalue = field.last %}
    {% endif %}
  {% endfor %}
<!-- end artifi code -->

On the product detail page, we need to find the code of the current Add To Cart button and replace it with the below-mentioned script.

{% if personalizevalue == 0 %}
 
  <input style="display:none" type="submit" class="btn" id="buttonAddToCart"
    value="{{ 'products.product.add_to_cart' | t }}">
 
  <button class="btn" id="artifiPersonalize" name="personalize" type="button"><span
      id="artifiPersonalizeText">Personalize</span></button>
 
{% elsif personalizevalue == 1 %}
 
  <input type="submit" class="btn" id="buttonAddToCart" value="{{ 'products.product.add_to_cart' | t }}">
  <button class="btn" id="artifiPersonalize" name="personalize" type="button"><span
      id="artifiPersonalizeText">Personalize</span></button>
 
{% else %}
 
  <input type="submit" name="add" class="btn" id="buttonAddToCart" value="{{ 'products.product.add_to_cart' | t }}">
 
{% endif %}

The above code is finding which option is selected by the user in the below dropdown and displaying Add-To-Cart items based on that.

Change 7 - Artifi.js

In this file, we are managing all Javascript-related things used in the theme like given below.

Artifi Initialization
Add to cart data listeners
Shopify Add to cart after Artifi Add to cart.
Show Artifi Preview
Edit Artifi Design
Reorder

In this file, we need to check if the below variable's IDs or classes are the same as the IDs available in the DOM element.

var artifiButtonAddToCart = 'button#AddToCart';
var artifiSpanAddToCartText = '#AddToCartText';
var artifiHiddenProductSelector = '#productSelect';
var artifiPersonalizeButtonClass = "btn";

Check the quantity field selector is the same as available in Artifi. This quantity field is required to display the price based on quantity in Artifi.

If the quantity selector is not enabled on the product template then we need to enable it from the customize theme.

Shopify Admin -> Online Store ->Customize ->

Change 8 - Cart-template.liquid

On this page, we are making changes related to the images and adding some links for preview and Edit Design like the below screenshot. Also, we have made changes in the remove cart item functionality to remove the abandoned design from the Artifi as well.

When the user will click on the Preview link, it will open the preview of the design in popup with details like the image given below.

Here is the code related to the thumbnail preview and link of image, this code will be automatically appended when the user is installing the application.

{% for item in cartItems %}
<tr class="cart-item{% if item == 'template' %} ajax-cart__template{% endif %}" data-cart-item
  data-cart-item-id="{{ item.key }}" data-cart-item-line-number="{{ forloop.index }}">
  <td class="cart-item__image-wrapper">
    {% assign itemImage = true %}
    {% if item.image == blank and item.product.featured_image == blank %}
    {% assign itemImage = false %}
    {% endif %}
    <a class="cart-item__image-link" href="{{ item.url }}" style="background-image: {% if itemImage %}url('{% if item.properties._ArtifiPersonalizedImageThumb %}
            {{ item.properties._ArtifiPersonalizedImageThumb }}
            {% else %}
            {{ item | img_url: 'medium' }}
            {% endif %}'){% else %}none{% endif %};" data-cart-item-background-image data-cart-item-href>
      <img class="cart-item__image lazyload {% unless itemImage %}hide{% endunless %}" src="{% if item.properties._ArtifiPersonalizedImageThumb %}
            {{ item.properties._ArtifiPersonalizedImageThumb }}
            {% else %}
            {{ item | img_url: 'medium' }}
            {% endif %}" alt="{{ item.title | escape }}" data-cart-item-image>
    </a>{% if item.properties._ArtifiDesignId %}<a href="javascript:void(0);" class="link-btn"
      onclick="openArtifiPreviewPopup('{{item.variant_id}}','{{ customer.id }}','','{{item.properties._ArtifiDesignId}}',{{item.product.variants.size}},'{{item.properties._ArtifiUserIdInQuote}}','{{item.properties._ArtifiProduct}}','{{item.properties._ArtifiVariant}}');">Preview</a><br><a
      href="javascript:;" class="link-btn"
      onclick="artifiEditItem('{{item.variant_id}}','{{item.properties._ArtifiDesignId}}','',{{item.product.variants.size}},'','{{ item.quantity }}','{{ forloop.index }}','{{customer.id}}','{{item.properties._ArtifiProduct}}','{{item.properties._ArtifiVariant}}','{{item.product.id}}');"
      title="Edit item parameters">Edit</a>{% endif %}
  </td>

Change 9 - Extend the Remove Cart Functionality

In this change, we are extending the remove cart functionality, when the user will delete any cart item we will delete the associated design items from the Artifi as well.

Check if the template below is available or not in the cart-template. If this is missing please include this code in the cart-template file.

{% if item.properties._ArtifiDesignId %}     
        <a href="#" data-confirm="Are you sure to delete this item?" id="removeItem-{{ forloop.index }}" data-id="{{item.variant_id}}" data-datac="{{item.properties._ArtifiDesignId}}"  class="remove toggler" title="Remove Item"> &#215;</a>
{% else %}
        <a class="remove toggler" onclick="return confirm('Are you sure to delete this item?');"  href="/cart/change?line={{ forloop.index }}&quantity=0" title="Remove Item">&#215;</a>
{% endif %}

After adding the above code we need to add the below JS script before closing the loop of the cart item.

<script type="text/javascript">
    // *Note*/ new js code for delete cart items if order has been placed from second tab
    jQuery.get('/cart.js').complete(function (data) {
      var responseObject = JSON.parse(data.responseText);
      var cartToken = responseObject.token;
      
      var index = '#removeItem-{{forloop.index }}';
      $(index).on('click', function(event){
      event.preventDefault();
      var choice = confirm($(this).attr('data-confirm'));
         if (choice) {
            var designID = jQuery(this).data('datac');
              //jQuery.post('/cart/change.js', { quantity:0, line: 1 });            
                 var ajaxRequest = $.post('/cart/change.js', { quantity:0, line: {{forloop.index }} },null,'json');
             //When the request successfully finished, execute passed in function
               ajaxRequest.done(function(response){                             
              if(response.token == cartToken)
                {
     console.log("need to perform Artifi delete call");
                     jQuery.ajax
                       ({
                           url: artifi_integration_url+'/Designer/Services/DeleteCustomizedProduct?websiteid='+website_id+'&webApiClientKey='+webapi_client_key+'&customizedProductId='+designID+'&orderStatus=InProgress',
                           type: 'post',
                           success: function(result)
                           {
                             if(result.Response == 'Success'){
                                 document.location = '/cart';
                             }
                           }
                       });
                 } else {
                     console.log("no need to perform delete call for Artifi");
                     document.location = '/cart/change?line=1&quantity=0';
                 }
               });
               //When the request failed, execute the passed in function
               ajaxRequest.fail(function(status){
              document.location = '/cart/change?line=1&quantity=0';
           });                                              
         }                                                         
       });         
    }); 
   </script>

Suppose the code we have added for delete cart functionality and getting an issue in jQuery, you can add the below jQuery in the cart page before the <Form> tag.

{{ '//ajax.googleapis.com/ajax/libs/jquery/1.12.4/jquery.min.js' | script_tag }}

Artifi Updates on Checkout

After successfully creating an order on the Shopify website we are sending a call to Artifi to update the order status from “Add to cart” to “Checked Out”.

Go to Shopify Admin -> Settings -> Checkout -> Additional Scripts

In the additional script box (textarea), we need to add the below JS code. If any code is present there in the box then we need to add this code below the existing code.

NOTE - Please update your shopify domain name with “yourDomain.myshopify.com”

<script type="text/javascript" src="http://code.jquery.com/jquery-1.11.2.min.js"></script>
 
<script type="text/javascript" >
    var Order_ID = {{ order.id }};
    var shopDomain = 'yourDomain.myshopify.com';
    var custEmail = '{{ customer.email }}';
    window.onload = function() {
        if (window.jQuery) {  
            // jQuery is loaded
            jQuery.ajax({
                type:'post',
                url:'https://shopify.artifi.net/getOrderData.php',
                data: 'order_id='+ Order_ID +'&shop_domain='+ shopDomain + '&email='+ custEmail,                 
                success: function(data){}
            }); 
        } else {
            // jQuery is not loaded
            alert("jQuery doesn't work");
        }
    }
</script>

If your code is working without loading min.js you can remove the reference of jquery-1.11.2.min.js from the script.