Integrations

SFCC Cartridge Installation Guide

Summary

Follow our video tutorial below:

‌

ThisImplementation Guide describes how to integrate an int_videowise cartridge into Commerce Cloud reference application Store Front Reference Architecture (SFRA).

The int_videowise component supports the following:

  • Widget Integration in Storefront
  • Videowise Back-Office - Content Configuration

The integration of the cartridge into your storefront application does not imply modifications of core cartridge, SFRA approach of files overwriting should be used instead.

For more information over the features above, please contact our customer support.

Components Overview

Supported Features

  • Widget for Shoppable Videos
  • Videowise Back-Office - Content Configuration

Functional Overview

A shoppable video allows a user to buy products associated with the current video. It is a fully client-side solution, where the videos are generated and managed by the external scripts configured in site preferences.

In terms of functionality we have the following:

  • A user enters the site and accesses a page.
  • Goes to the Videowise section.
  • Click on the video to play it.
  • Access the product/products associated with the video.
  • Add products to the cart.
  • Goes to Cart → Checkout and finalizes the order.
Notion image

Use Cases

Videowise has developed the following use cases:

  • Widget integration in Homepage
  • Widget integration in PDP
  • Widget integration in Articles(Content pages)
  • Widget integration in Page Designer
  • Videowise Back-Office: Accessible only for the business team required to configure the shoppable videos content.

Headings & Constraints

The int_videowise cartridge doesn’t support the following types of products:

  • Product Bundles
  • Product Sets

Only the following types of products are supported:

  • Standalone Product
  • Master Product
  • Variation Product

Compatibility

The int_videowise cartridge has been available since Commerce Cloud version 21.2.

Implementation Guide

SFCC Setup

To integrate Videowise, you need to add int_videowise to your target site cartridge path.

Cartridge Installation

For cartridge installation, please follow the steps:

  • Upload int_videowise to your CI or development sandbox. Apply the standard flow used to upload cartridges to your environment.
  • Upload and import metadata from the metadata folder. To do so, go to Business Manager → Administration → Site Development → Site Import & Export. Then apply the standard procedure for uploading metadata into the Commerce Cloud site. You can compress the Site Template folder to a .zip archive or upload it via XML files and import it separately.
    • Notion image
  • Insert int_videowise into the cartridge path of a target site. To do so, go to Business Manager → Administration → Sites → Manage Sites → <Your Target Site> → Settings and insert int_videowise before your cartridges record.
    • Notion image
  • Insert bm_videowise into the Business Manager cartridge path. To do so, go to Business Manager → Administration → Sites → Manage Business Site -> Cartridges and insert bm_videowise before your cartridges record
    • Notion image

Site Preference Configuration

The settings for Videowise in Business Manager are managed in Site Preferences, in the Videowise Configurations group. We have the following site preferences:

  • Videowise Enabled: flag to enable/disable the Videowise functionality
  • VideoWise external stylesheet URL: the CSS style sheet for Videowise widget
  • VideoWise external client script URL: the JS external script for client side
  • Images View Type: the image type that will be used for Videowise products. By default it is configured for medium.
  • VideoWise Encryption Authentication Key: the encryption key that is used to generate the header signature for endpoints request/response validation between SFCC and Videowise.
    • Notion image

Encryption Authentication Key Generation

This key is generated in Videowise Back-Office when a new site is installed. This key must be added in Videowise Encryption Authentication Key preference.

This is used to generate the header signature that will validate the request/response between SFCC and Videowise. For generating the signature, we use HMAC with SHA512 algorithm.

Example of signature generated:

64ffedaf9fa6892a872fb94ed35babf01b376c06f02bc178cdc02003cb0f5fcd5f3a9a746f3beb74adb738bbbf25f9c45e8e8beb1ca2a08c37fa16e108b8fb94

Page Designer Configuration

A new Page Designer component named Videowise Shoppable Video will be created that will hold the container where the widget will be injected into the site. The component will only hold plain HTML.

This component will be available after the import of the metadata, described in the above steps.

Notion image

Tracking Pixel Configuration

For tracking pixel configuration what must be done is to add the script link in Site Preferences, as already shared above.

Notion image

A tracking pixel will be added to the order confirmation page after successful orders.

Integration endpoints

The Videowise cartridge has the following endpoints added:

  • Videowise - GetDetails
    • This endpoint is used to get product information directly from the client side, in the widget.
  • Videowise - BackOfficeProducts
    • This endpoint is used to get product information for Videowise Back-Office. It supports the following:
      • Retrieve product information based on a list of SKUs.
      • Retrieve product information based on search query.
    • This will be added and configured when a new site is installed in Videowise Back-Office.

Image to be added

The following use cases are inherited from SFCC base:

  • Add single product to basket
  • Add multiple products to basket

This will allow us to use the site specific customisation for adding products to the cart. Both actions are managed by a single endpoint:

  • Cart - AddProduct

Videowise Back-Office Configuration

To integrate a new site/brand in Videowise back-office, the following information will be required:

  • Site Domain
  • Site ID

Image to be added

This configuration will allow the following:

  • Access in Videowise dashboard to the site products.
  • Possibility to choose and configure shoppable videos with the site products. The IDs generated for the content will be in SFCC Business Manager to configure the container for the content.
  • Possibility to search for products taking into consideration the following options:
    • Search by SKU
    • Search by Product Name
    • Search by Product Brand
      • Notion image

Site Domain

The site domain will need to be configured according to how it is set in SFCC Site Alias configuration. This will be used in building the URLs for the endpoints mentioned above.

Encryption Key

The encryption key generated must be configured in Videowise Back-Office, in the same way as it is done in SFCC Business Manager. This will be used for the security middleware configured for Videowise endpoints.

Customising Code

Storefront Reference Architecture (SFRA) does not imply modification of core cartridge to enable any of LINK integration cartridges. The development of int_videowise follows best practices recommended by Salesforce, and due to this reason no code changes are required for the default installation.

Building the client side code

You need to make sure that the client side JS is bundled, so make sure to include the new int_videowise cartridge in your bundler’s entries configuration.

The cartridge is designed around the same build concepts as the SFRA core cartridges and plugins provided by Salesforce.

Once the cartridge is added into the bundler’s configuration, you can proceed as usual and build your client side files, then upload them to your environment (usually npm run compile:js)

Updating your application

In an ideal scenario where you only have SFRA base cartridge and Videowise cartridge installed, there is no need to make any changes to your application, the functionality provided by the cartridge will be available immediately after the cartridge is built and deployed as described above.

In the real world there are lots of other 3rd party cartridges and plugins which may override the same components as the ones in Videowise SFRA cartridge (int_videowise).

In that case you will need to merge changes from all those cartridges and plugins following the guidelines from this example repository provided by Salesforce: ‣

Changes to templates

  • To add the application scripts, go to your \common\scripts.isml template and add the following line at the end of the file (last line):
    • <isinclude template="videowise/scripts"/>
      Notion image
  • To add the tracking pixel JavaScript helpers, go to your checkout/confirmation/confirmation.isml and add the following line at the top of the page, inside the <isscript> tag, right before it closes:
    • var shouldTrackPurchase = dw.system.Site.getCurrent().getCustomPreferenceValue('videoWiseEnabled');
      
      var trackingAPIUrl = dw.system.Site.getCurrent().getCustomPreferenceValue('videowiseTrackingApiUrl');
      
      if (shouldTrackPurchase) {
      
      assets.addJs('/js/videowisePurchaseTracking.js');
      
      }
      Notion image
  • To add the tracking pixel data container, go to your checkout/confirmation/confirmation.isml and add the following line at the end of the file, right before the closing of </isdecorate> tag:
    • <isinclude template="videowise/trackingPixelDataContainer"/>
      Notion image

Testing

For local testing you need to contact Videowise customer support to provide access to a Videowise testing instance where to start configuring the site and to have access to all required values for site preferences.

Operations and Maintenance

Logs

This integration introduces a few new custom logs specifically for Videowise. This log type can be identified by the following name: custom- VideoWise-ecom-app-55ffb7dc57-qddzl-0-appserver-20230522.log. All log files are located in the Logs folder (under Administration → Site Development → Development Setup → Logs).

This Log file contains all errors related information in the int_videowise cartridge.

Support

For any questions or concerns, to get help from Videowise please follow the next steps:

  • Read our FAQ to verify if your question is already answered,
  • If your question or concern is not among the available answers, you can email the Videowise Customer Support team at support@videowise.com.

Known Issues

No reported issues so far.

Did this answer your question?
😞
😐
🤩