How to Set Up Shoppable® DTC Lite (V4) In 10 Quick Steps

Shoppable® DTC Lite is a standardized Shoppable product that helps you set up Shoppable technology faster. This guide will help you integrate Shoppable on your website.

A Guide to Setting Up Shoppable DTC Lite In 10 Quick Steps

Introduction 

What is Shoppable DTC Lite?

Shoppable DTC Lite is a standardized Shoppable product that helps you set up Shoppable technology faster.  (Shoppack has been renamed Shoppable DTC Lite.)

This version of Shoppable does not allow for customizations, but it will reduce the time it takes you to launch Shoppable so you can get your business up and running quickly.  The one customization with Shoppable DTC Lite is you can choose the accent color of the buttons in the checkout process so they match your branding. 

Shoppable DTC Lite provides javascript files and API interfaces to integrate the shopping cart and hosted checkout functionality into your brand site. This document describes the steps required to integrate as a js ‘widget’ which greatly reduces the amount of effort required to integrate the Shoppable experience. The widget delivers a fully functional PDP (with an add to cart feature), cart update, and mini cart elements, with no more than a few lines of well-placed code.

References 

The following are the documents referenced in defining the overall scope of this project.

V4 bundle
Staging:

Production:

Styles (base CSS for both environments):

Let's get Started

Step 1: Get your API token

As a first step for implementing Shoppable DTC Bundle, you need to obtain an API token from Shoppable. You can set up an account through publishers.shoppable.com and Shoppable allocates two different API tokens, for Staging and Production environments 

Staging Endpoint:

Production Endpoint:

Note: Wherever <token> is referred to in this document replace it with the corresponding token assigned to your site and the environment.

Step 2: Creating a brand feed file 

Note: this step is only if you need to override images and names of products. 

After you have received your token you should have someone at your company create a brand feed file.  This feed file will include the information about the UPC of the product, the name you want the product to be, and the image you want for the product.

Note: At this point, you can decide on what merchants to use. If there are any restrictions that might be in place between you and retail partners

Product, please advise within the file. Your Customer Success Manager at Shoppable will send you a sample brand feed file post-kick-off.

Step 3:  Configure your bundle settings 

On the brand site page where the shopping bag functionality is being implemented, add the following Shoppable JS script as shown below.

Note: If you are loading in any version of angular 1.x on your page you should use shoppable_new_bundle_no_angular.js instead of shoppable_new_bundle.js. However, the Shoppable loaded after you load your version of angularjs.

Bundle Configuration Parameters: 

  • Token : Your token (required).
  • site_language: The default language you want the bundle to use. This can be updated at any time by calling Product.update_language (new language, callback)
    • All available languages are in the standard format of  languagecode_country code i.e. en_us, es_us, fr_ca, etc.
  • order_complete_page: This is the page that the shopper is sent to once they have finished checking out. (required)
  • page_after_complete_page: This is the page that the shopper is sent to after the thank you page. (required)
  • campaign: This determines your checkout page design after Shoppable has styled it. Confirm this field with your Project Manager before proceeding. (required)
  • checkout_page: This is the link to where the checkout iframe will be held
  • cart_tab_parent_id:  This is the element that is the parent of the cart tab, leave blank if you want to position the cart_tab yourself. This determines the mini-cart location and open.

And example of what your include is as follows:

: <script id="shoppable_bundle" options='"token":"someTokenHere", "developerMode":"true", "order_complete_page":"shoppable.com","page_after_complete_page":"http://yourcompletepageURLhere"' src="https://d4rzy2891kad2.cloudfront.net/assets/shoppable__new_bundle.js"></script>

Script Dependencies:

  • Angularjs 1.7.2 or higher
  • Jquery 1.7.1 or higher
  • Angular Materials 1.1.0-rc2.

Our script will not attempt to load these files if they are already available on your site therefore to ensure that duplicate files are not loaded you must load our script after your scripts have loaded.  When our file has finished loading it will dispatch the
Event: Shoppableloaded.

Ready to launch? 

Request your Production Credentials from your Shoppable customer success manager a CDN-hosted link to the production version of the Shoppable Commerce Bundle during the UAT phase.

Step 4:  Add the CSS Files 

You will need to include the following CSS files on your page to ensure that Shoppable’s bundle has correctly propagated all Styles classes. 

You will need to add the following two Stylesheets everywhere you've added the cart bundle script: 

Note: Shoppable will be enhancing the CSS files listed above over time and it is not recommended to make major customizations for your site layout.

Step 5: Setup your Products with Add to Bag Buttons

In order to set up your PDP, you should have your product page laid out in a similar fashion to the following image:

Within this image, you will see that the PDP allows for the selection of the product's key attributes (size/color), and selecting one of these key attributes should set the values that you will pass to Shoppable. This value will be passed to the following function:

Single Product (ATC):

Product.pop_pdp(“upc”, upc,”variant”,null,(e)=>{});

Parameters:

  • upc: The part_number or UPC code for this product.
  • variant:  
    • addToBag:  UPC to be added to the Cart (user selects the size and color on your PDP or the cart).
    • requireColor: If there is no color selection on your PDP but the product requires it
      (this parameter will offer the variation selection as a dropdown in the cart).
    • requireSize: If there is no size selection on your PDP but the product requires it (this parameter will offer the variation selection as a dropdown in the cart).
    • requireSizeAndColor: If there is no color and no size selection on your PDP but the product requires it.
    • addPreselectedProduct: if you need to add to the cart the exact product and its size/color without providing a variation selection.
    • null:  this parameter is used by legacy customers who updated the contents of the cart on their own page 
    • callback: pass in a function to get a response when the pop_pdp is complete. 

    Note: If you have set up the add to bag button properly you should be able to see the side cart appear as follows:

    Multi-Product Bundling (ATC):

    If you'd like to create bundles of your selected products to add to the cart, you can use the Product.pop_pdp_bundle()  function and create an array of items and the pertinent fields as displayed in the code-block example below.

    Product.pop_pdp_bundle({
    items: [
    {
    idType:'upcs',
    id: '044444444440',
    mode:'addProduct'
    },
    {
    idType:'upcs',
    id: '011111111110',
    mode:'addProduct'
    }
    ]
    });

    Parameters:

    • idType: The type of identifier used, only  use "upcs"
    • id:  A valid 12 digit UPC
    • mode: The type of action to perform, only use "addProduct"

    Product Added to Cart:

    Variation Selections:
     

    Step 6: Styling Elements 

    As seen in the above screenshot, the side panel will come in Shoppable’s default styling, and using this styling can take your customer out of the experience causing mistrust and may prevent people from finishing the checkout process. So you will need to update some of the stylings of the following fields:

    • Shoppable-V.4 checkout-btn: This is the button that takes the shopper to the checkout page. It should match the colors of all the other call to actions buttons on your site.
    • Shoppable-V.4 view-bag-item-name: This is the name of the items that are added to your side cart. This should match the fonts on your site.
    • Shoppable-v4 checkout-free-shipping-text: This is the bold free shipping text in your side cart. This should match the fonts on your site.
    • Shoppable-v4 checkout-spend-more: This is a marketing copy to notify the shopper how much more they need to spend to get free shipping. This displays in your side cart. This should match the fonts on your site.

    Step 7: Subscribe to Shoppable Events 

    You can subscribe to a large number of events in order to perform custom actions. This can be used to capture analytics or to perform your own functions after a call is made. 

    ADD_TO_CART

    Fires when an item is added or when an item is updated in the cart.

    Product.eventSubscriber('ADD_TO_CART',(e) =>{ })

    Returns cart information and events that can be utilized in a tracking system like GA.

    Example: 

    {"cart": {
    "cartinfoevent": {
    "lastQtyAdded": {
    "item":"sku",
    "name":"name",
    "qty":"qty",
    "price":price,
    "upc":"upc"
    }
    }
    }
    }

    REMOVE_FROM_CART

    Which fires when an item is removed from the user's cart.

    Product.eventSubscriber(‘REMOVE_FROM_CART”,(e) =>{ })

    Returns cart information and events that can be utilized in a tracking system like GA.

    Example: 

    {"cart": {
    "cartinfoevent": {
    "lastQtyRemoved": {
    "item":"sku",
    "name":"name",
    "qty":"qty",
    "price":price,
    "upc":"upc"
    }
    }
    }
    }

    FOUND_CART

    Which is fired on get cart calls. 

    Product.eventSubscriber(‘FOUND_CART’,(e) =>{ })

    CART_RENDERED

    Which is fired when the Shoppable cart button is rendered.

    Product.eventSubscriber(‘CART_RENDERED’,(e) =>{ })

    CLOSE_CART

    Which is fired when the Shoppable cart is closed.

    Product.eventSubscriber(‘CLOSE_CART’,(e) =>{ })

    OPEN_CART

    Which is fired when the Shoppable cart is opened.

    Product.eventSubscriber(‘OPEN_CART’,(e) =>{ })

    Shoppable invokes yourCustomHandler() method and passes back JSON data.

    Event Callback:

    To ensure that the Shoppable bundle has been loaded, you will need to listen to the Shoppable loaded event:

    document.addEventListener('Shoppableloaded', function(){console.log('shoppable loaded');

    Step 8: Set up Your Hosted Checkout Page

    Shoppable_Checkout_Jan_2021

    In order to use Shoppable's hosted checkout, you will create your own iframe on your checkout page the URL that you will supply to this iframe in order to get the checout_url is obtained by the function 

    Cart.get_checkout_url(): Returns the checkout url.

    Note: The parameters of the checkout URL are based on your bundles parameters. This URL is in the following structure for staging if you wish to not load the bundle on the checkout page or if the checkout page is hosted on a separate server: 

    URL Example: 

    https://secure.shoppable.co/checkout?cart={cartID}&orderComplete={yourThankyoutPagePath}&campaign={yourCampaign}&publisherCheckout={yourSiteWithHttps://}&apiToken={YourTokent}&returnToSite={yourHomepagePath}&language=en_us&noiframe=0

    For the checkout page, we highly recommend based on industry standards that you have a small simple header bar that only has a small version of your logo for the shopper to navigate away from the Checkout Page.
    Example: 

    The size of this checkout header should have a height of 42 pixels.

    For the iframe itself for optimal usability, we suggest to following Styling Parameters:

    • width: 100%
    • min-height: 1250px; 
    • padding: 10px; (from the header bar to delineate separation. )

    Step 9:  Managing Messages from the Checkout Page

    The Hosted Checkout page is implemented on the brand’s site with an iframe. The iframe includes the checkout page provided by Shoppable. When the order is completed, Shoppable will not be able to redirect to the parent page URL directly, hence Shoppable has implemented a “Post Message” event to the iframe after checkout is completed. 

    This uses a simple built-in html5 Window.postMessage method that is designed for the window to window communication cross-domain or otherwise. The following sample code needs to be implemented on the Brand site checkout page to receive the posted message. 

    Parsing the lux_data passed from the PostMessage event.

    The posted message contains a lux_data JSON object that contains various information.

    The lux_data is in JSON format, in order to parse and retrieve the order data JSON.stringify or another method of parsing the JSON data is required to retrieve the lux_data 

    Add the following to the brand site Checkout page:

    // Create IE + others compatible event handler

    var eventMethod = window.addEventListener ? "addEventListener" : "attachEvent";

    var eventer = window[eventMethod];

    var messageEvent = eventMethod == "attachEvent" ? "onmessage" : "message";

    // Listen to message sent from child window

    eventer(messageEvent,function(e) {

     console.log('parent received order details!:  ',e.data);

    },false);

    The messages will only be sent to the publisherCheckout domain.  

    Here is the Iframe post message invocation:             

    parent.postMessage(orderDetails, "<%= @publisherCheckout %>");

    Checkout Analytics Tracking

    Event listeners can also be added to the brand’s publisherCheckout page in order to set up Analytics tracking. Setting up tracking will allow the client to track the user as they complete the checkout process steps through Shoppable's GA tracking events that are captured when the user reaches or completes a certain action on the form. 

    The following events can be added:

    • checkout
    • shipping_first_name: ON KEYDOWN
    • billing_first_name: ON KEYDOWN
    • payment_first_name: ON KEYDOWN

    Event Object:

    {
    "cart_id": "{CART_ID}"
    "event":"Order Shipping Form Reached",
    "event_type": "GA"
    "step":1
    "option":'Shipping Address'
    "name": "Product Name"
    "upc": "{UPC_NUMBER}"
    "merchant": Walmart
    "brand": "brand name"
    }
    {
    "cart_id": "{CART_ID}"
    "event":"Order Billing Form Reached",
    "event_type": "GA"
    "step":2
    "option":'Billing Address'
    "name": "Product Name"
    "upc": "{UPC_NUMBER}"
    "merchant": Walmart
    "brand": "brand name"
    }
    {
    "cart_id": "{CART_ID}"
    "event":"Order Payment Form Reached",
    "event_type": "GA"
    "step":3
    "option":'Payment Method'
    "name": "Product Name"
    "upc": "{UPC_NUMBER}"
    "merchant": Walmart
    "brand": "brand name"
    }
    {
    "cart_id": "{CART_ID}"
    "event":"Order Submission Reached",
    "event_type": "GA"
    "step":4
    "option":'Checkout'
    "name": "Product Name"
    "upc": "{UPC_NUMBER}"
    "merchant": Walmart
    "brand": "brand name"
    }

     Trigger scroll on checkout errors using PostMessage

    If an error occurs on the checkout page when the submit button is clicked, due to an invalid shipping address, minimum order threshold, etc. A dialog box (modal) will be displayed in the checkout iframe, informing the shopper of the issue. Since the modal is in the iframe and the shopper is at the bottom of the iframe clicking the submit button, they will not be able to see the dialog box that appears at the middle section of the checkout page.

    Since the iframe cannot control the scrolling when the error occurs, a {"LUX_DATA":"ErrorInForm:scrolltop"} object is passed via postMessage from the iframe to the parent window, this will allow the brand site the ability to add a scroll event when an error occurs in the iframe checkout page. 

    With the event listener code (Step 7) added to the brand site checkout page, the 

    if(e.data.LUX_DATA.indexOf('ErrorInForm') > -1) {

      console.log('Listener found the LUX ErrorInForm event! ', e.data.LUX_DATA);

     }

      

    Above code will listen for when the {"LUX_DATA":"ErrorInForm:scrolltop"} is sent via postMessage.

    Thank You Page & Successful Order Confirmation

    In order to redirect the user to your thank page one of the lux_data options that can be passed back is the orderComplete parameter and order data for the thank you page. Upon receiving the window.postMessage data after the checkout process, redirect to the specified brand thank you page. The redirect must be done on the brand side.

    if(e.data.LUX_DATA.indexOf(url) > -1) { console.log(‘checkout url ', e.data.LUX_DATA); }

     Step 10: Successful Order Confirmation & Order API

    "Thank You Page":

    Add a “Thank You Page” to the brand site, this page is a redirect after the customer checks out and displays their Shoppable Order Number. 

    Shoppable redirects the user to the brand site thank you page with the following query string parameters.

    https://<YOUR WESBITE.com/ShoppingBagCheckoutPage>?email=YOU&oid=<orderId>&opt_in=<opt_in>&qty=1&shipping=<shipping_total>&subtotal=<subtotal>&tax=<tax>&total=<total>

    Thank_you_page

    Note: The "R Number" (Reference Number) parameter Shoppable uses internally to identify a Shoppable Multi-Retailer Order. It is only for your logs and tracking internally or with Shoppable and should not be displayed to the shopper. This is because they will get an order confirmation from the merchant and displaying the "R Number" will confuse the shopper and potentially create processing and fulfillment issues with the merchant(s).

    If you need to log the details of the order, use rnumber (order Id) to call the Shoppable API to retrieve the order details. (The “r number” is the order reference number. 

    Shoppable uses reference numbers because a universal checkout order can have multiple merchants and each merchant has their own “Order Number” which is used with the shopper. R numbers are meant to be used internally by you and Shoppable only and not shared with consumers. It’s best for consumers to use the merchant order numbers.

    Order API: 

    After completing the checkout process you may want to retrieve the order data in order to store it within your own system. An OAuth user name and password will be provided to you. Once you get this information you will need to make the following calls   

    Auth request :

    curl --location --request POST 'https://orders.shoppable.co:4433/auth' \

    --header 'Content-Type: application/json' \

    --data-raw '{

       "userId": "userId",

       "password": "Password"

    }'

    Replace userId with the userId we provided and the password with the password we provided this will return an access token with an expiration time in the following format. 

    {

        "auth": true,

        "token": "authtokenI",

        "expire": 1611253796

    }

    You will use this response to make GET requests using the newly tokenized value provided from the "token" parameter above to authenticate your requests:

    Order data range call:

    curl --location --request GET 'https://orders.shoppable.co:4433/v3/orderData/100/page/0/startdate/2020-10-01T12:35:42.025Z/enddate/2020-10-01T12:37:42.025Z' \

    --header 'x-access-token: yourAccessTokenForm First request' \

    Order-Data Range Parameters:

    • rows: the number of rows you are request
    • page: the page offset for paging
    • startdate: the date and time of the first order you want to request in Iso format
    • enddate: the date and time of the first order you want to request in Iso format

    Order data call:

    This returns the data to a specific order.

    curl --location --request GET 'https://orders.shoppable.co:4433/v3/orderData/{order_number}' \

    --header 'x-access-token: yourAccessTokenForm First request' \

    Order-Data Parameters:

    order_number:  is the order you want to get information about we return this order_number  in the thank you page to redirect

    Order API EndPoints:

    Staging:

    https://orders.shoppable.co

    Production:

    https://orders.shoppable.com

    Advanced options functionality 

    Below are some advanced bundle options that can be used for some advanced customization options:

    • skip_cart_tab_mouse_enter: If this value is set to true the cart hover functionality will not be enabled.
    • auto_close_cart_time: This option is defaulted to 5 for five seconds for the cart to auto-close. You can increase this time or set it to false to prevent it from closing.
    • color_label_overide: You can set this value to change all of the labels that would say color to something else.
    • qty_label_overide: You can set this value to change all of the labels that would say QTY to something else.
    • size_label_overide: You can set this value to change all of the labels that would say size to something else.
    • retailer_label_overide: You can set this value to change all of the labels that would say retailer to something else.
    • out_of_stock_message: You can change the out of stock message which appears when the customer attempts to add an out of stock product to cart.
    • empty_cart_message: You can change this  empty cart message that appears when the customer opens the cart while it is empty