5Configure Web Widgets

Web Widget Templates

Control how your customers receive recommendations on your commerce storefronts using web widget templates. If you integrate with an email service provider, you can also use the email widget code to include personalized recommendations in your email campaigns.

Most widgets use machine learning to control recommendations displayed on your commerce site. Other widgets, such as recently viewed and trending items, use basic recommendation algorithms that don’t require advanced machine learning.

These predefined widget templates give you a starting place for your designs.

Widget Type Purpose Uses Adaptive Intelligence
Product (Single) Shows individual product recommendations Yes
Product (Carousel) Shows groups of product recommendations Yes
Promotion Shows individual promotions Yes
Also Bought (Carousel) Shows a group of items that other shoppers bought together with the highlighted product No
Also Viewed (Carousel) Shows a group of items that other shoppers viewed together with the highlighted product No
Recently Viewed (Carousel) Shows a group of items that the shopper viewed within a recent time period No
Trending Items (Carousel) Shows a group of items that have current purchasing trends No
Clickstream Collects clickstream activity to feed into the adaptive intelligence models. Not applicable for widget design or displaying recommendations. Not applicable
Important: For all widgets, you specify details, such as the display title, either directly in the widget code or in the commerce application. Any specifications you make for a widget type apply to all widgets of that type.

Recently Viewed Carousel

You can use the Recently Viewed widget to remind shoppers about products that they previously viewed. This gives you another chance to influence the shopper’s decision to purchase. When a shopper purchases a product that’s also in the Recently Viewed carousel, that product is then removed from the carousel.

Clickstream tracking in the widget collects information about what products shoppers view and when they view them. The tracking is slightly different for registered and anonymous shoppers.

  • For registered shoppers, tracking is in the current and previous sessions for the same browser across all devices.

  • For anonymous shoppers, tracking is the same as for registered shoppers, except only on the same device.

By default, the Recently Viewed widget tracks up to thirty items viewed within the last three months. To change these values, you must use the REST API. See Set Tracking Period and Count for Recently Viewed Items in REST API for Oracle Adaptive Intelligent Apps for CX.

Trending Items Carousel

You can use the Trending Items widget to highlight products that are gaining popularity. The recommendation algorithms identify trending items by comparing products purchased in a specified interval to the previous interval. Suppose your widget uses the weekly trending interval. The carousel shows the products with the highest percentage increase in purchases between the last seven days and the previous seven days. For example, on March 22, it shows the products with the highest growth in sales from 9-15 March to 16-22 March.

Parameter Description Values
interval (Required) The trending period to calculate trends
  • DAY (24 hours)

  • WEEK (7 days)

  • MONTH (30 days)

n (Required) The number of trending items to display Any whole integer
minOrderThreshold (Optional) The minimum number of times a product must be ordered in the previous time interval for it to be considered in trending calculations. You can use this value to filter out certain scenarios. For example, if there’s an increase from 1 item sold to 2 items sold, it could appear as a top-trending item. Any whole integer. Default value is 0.
priceThreshold

(Optional) The minimum price so that only products above this price threshold are considered for trending.

If you have a product price policy set on the Policies page, it will filter out the products under that price. So only products whose prices are greater than both the policy and the widget’s price threshold are considered.

A number value in the format for your default currency. For example, 19.99.

If you’re using Oracle Commerce Cloud, you can set these parameters in the widget design. Otherwise, you can use the REST API calls in your widget code. This cURL example uses these specifications to derive trending items:

  • Compare the weekly intervals

  • Display 10 items

  • Consider only 5 or more product orders for trending

  • Consider only products over 12.99

curl -X GET --header 'Accept: application/json' 'https://<tenant>.oraclecloud.com:<port>/offers/widget/v1/tr/product/<site-id>?interval=WEEK&n=10&minOrderThreshold=5&priceThreshold=12.99'

Configure Widgets for Oracle Commerce Cloud

For each widget, you create an extension ID from Oracle Commerce Cloud, enter it on the Commerce Widgets page to generate templates. Download the templates and then upload them to Oracle Commerce Cloud. You can choose the following widget templates:
  • Clickstream

  • Product (Single)

  • Product (Carousel)

  • Promotion

  • Recently Viewed (Carousel)

  • Trending Items (Carousel)

  • Also Bought Items (Carousel)

  • Also Viewed Items (Carousel)

If you have multiple commerce storefronts or sites, you have the option of enabling one or all sites for adaptive intelligence. You can use any of your widgets on all the sites that you enable. Before configuring widgets, ensure that filtering is enabled as described in the next section.

Configuration Steps

Each widget you configure must have an extension ID. Perform the following steps for each widget to configure:

  1. In the Oracle Commerce Cloud Service administration area, create an extension ID as follows:

    1. On the Settings page, click Extensions.

    2. Click the Developer tab.

    3. Click Generate ID.

    4. In the New Extension ID window, enter a unique name for the widget, and then click Save.

    5. Copy the newly generated extension ID.

      You will paste this value in the next step.

  2. In Oracle Adaptive Intelligent Apps for CX, associate the extension ID with a widget type and get the widget code as follows:

    1. On the navigation menu, under Connections, select Commerce Widgets.

      Widget Templates page for Oracle Commerce Cloud templates showing fields for extension ID and option to download

    2. Ensure that the value in the Platform list is Oracle Commerce Cloud.

    3. Enter the newly generated extension ID for the widget type you want to configure.

    4. Click Download Widget.

    5. Save the downloaded zip file to your file system.

  3. In Oracle Commerce Cloud, upload the zip file as follows:

    1. On the Settings page, click Extensions.

    2. Click the Installed tab.

    3. Click Upload Extension.

    4. Locate the zip file, and then click Open.

  4. Make any required modifications to fit your specific usage or in-house style or specific using the editor in Oracle Commerce Cloud.

    Refer to the Modifying Uploaded Extension Widgets section in Using Oracle Commerce Cloud Service for more information.

  5. For promotion widgets, see Configure Promotions for Oracle Commerce Cloud for steps to enable them for display and click tracking.

Adaptive Intelligence Settings

For additional settings, such as setting the number of products to display in the carousel, display text, timeout period, or filtering, perform the following steps for each widget:

  1. In Oracle Commerce Cloud, click Design in the navigation menu.

  2. For each widget that you want to configure, select the widget and then click the Widget Settings icon.

  3. To change the default display text for the widget, enter the text you want in the Title field.

  4. To change the number of items to show for carousel widgets, change the number in the Number of Products field. For new widgets, the default number of items is 12.

  5. To change the timeout period, change the value in the Timeout Period field. The default timeout period is 6000 milliseconds (6 seconds).

  6. To use restrictions to limit which recommendations are placed on a product detail page or on a collection's landing page on the storefront:

    1. Select one of these general restrictions, or select None. A selection is required.
      • Parent Collection (only products in the collection being viewed or searched)

      • Parent Brand (only products of the brand being viewed or searched)

      • On Sale

      • New - Past Month

      • New - Past Week

      • New - Past Day

    2. To restrict the shown products to a specific brand or collection, enter the ID or comma-separated brand IDs for the respective field.

  7. To use exclusions to prevent recommendations on a product detail page or on a collection's landing page on the storefront:

    1. Select one of these general exclusions, or select None. A selection is required.
      • Parent Collection (exclude products in the collection being viewed or searched)

      • Parent Brand (exclude products in the collection being viewed or searched)

      • On Sale

      • New - Past Month

      • New - Past Week

      • New - Past Day

    2. To exclude one or more specific products, enter the product ID or comma-separated product IDs.

    3. To exclude products in one or more specific brands or collections, enter the ID or comma-separated IDs into the respective field.

Important:
  • The adaptive intelligence models work best when no restrictions are applied so that there's sufficient opportunity to learn and react to preferences and behavior. Because restrictions and filters you use will affect recommendations, it's best practice to use them only in special circumstances.

  • Depending on how you set up your recommendation widgets, be careful that you don't specify conditions that cancel each other out or affect recommendations in a way you didn’t expect.

  • Filtering occurs after recommendations are generated through machine-learning. Therefore, if you have any exclusions that include items already boosted, they will be hidden in recommendations using the widget where exclusions were applied.

Configuring Promotions for Oracle Commerce Cloud

To configure promotions to display on your storefront and to track consumer responses through click tracking, your promotions must be associated with one or more products. You associate them using image URLs and link URLs as described in this topic.

Perform the following steps in Oracle Commerce Cloud for each promotion:

  1. If you already have an image to use for the promotion, on the Media page, copy the value in the Path field.

    You will use this value when creating the image URL for the promotion.

  2. If don't already have media for the promotion, upload media as follows:

    1. On the Media page, select either Products, Collections, or General.

    2. Click Upload and browse to select the image to upload.

    3. In the Location section, copy the value in the Path field.

      You will use this value when creating the image URL for the promotion.

    4. Click Save.

  3. Click Marketing.

  4. If you already have a promotion that you want to enable for display and click tracking, skip to the next step. Otherwise, create a promotion as follows:

    1. In the New Promotion list, select the promotion type you want to create.

    2. Enter a display name.

    3. Click OK

    4. Enter values for promotion fields as appropriate, and then click Create.

  5. Click the promotion to configure it for click tracking.

  6. In the Description section, click the Image icon.

  7. In the URL field, enter the full path to your storefront URL. Append the URL with/file/ and then the path value you copied from the media page. For example, https://mystorefront.com/file/products/10DollarsOffJacket.png.

  8. Optionally, add alternative text or change the size or formatting in the appropriate fields.

  9. On the Link tab, enter the URL to which you want to direct consumers when they click on the widget. This is typically the product or collection detail page. For example, https://mystorefront.com/womenjackets/product/1024.

  10. Optionally, select a target value, such New Window.

  11. Click OK.

  12. In the Availability section, ensure that there is a valid start date and select Enabled.

    These values are required for the promotion widget to be available.

  13. Click Save.

Configure Widgets for Oracle Commerce Platform

Before you begin working with widget configuration, you must register the API used by the plug-in, modify XML files, and restart the server. The prerequisite steps set up the JavaScript and widget templates that you can copy as needed to configure your widgets. The widget configuration steps show you how to use the widget code to configure individual widgets.

Prerequisite Steps

For initial configuration or after server updates, perform the following steps:

  1. Register the REST API getProduct method used by the plug-in as follows:

    1. Locate the ActorChainRestRegistry.properties file and open it for editing.

      This file is typically in the following location: /CommerceAccelerator/Plugins/Account/src/mail/config/atg/rest/registry/

    2. Add a comma followed by a backslash character (,\) to the last line in the file.

    3. Add the following line to the end of the file:
      /atg/commerce/catalog/ProductCatalogActor/getProduct
      Note: Ensure that the path is the same as the path created when installing the plug-in.
  2. Add the profile ID in the profile object as follows:

    1. Locate the beanFilteringConfiguration.xml file and open it for editing.

      This file is typically in the following location: /app/oracle/product/atg/ATG/CommerceAccellerator/Plugins/Account/src/main/config/atg/dynamo/service/filter/bean/

    2. Add the line<property name="id"/> into both the short and summary filters of the user item as shown here:

      <item-descriptor name="user" default-filter="short">
         <filter id="short">
            <property name="id"/>
            <property name="email"/>
            <property name="securityStatus"/>
            <property name="middleName" xml-combine="remove"/>
         </filter>
         <filter id="summary">
            <property name="id"/>
            <property name="gender"/>
      
    3. Save and close the file.

  3. Alter the promotion description to be a rich text area as follows:

    1. Locate the pricingModels.xml file and open it for editing.

      This file is typically in the following location: app/oracle/product/atg/ATG/CommerceAccelerator/Applications/B2CStore/src/main/config/atg/commerce/pricing/

    2. For the descriptionDefault property at around line 28, change the data-type value from string to big string as shown here:

      <property name="descriptionDefault" data-type="big string" column-name="description" category-resource="categoryBasics" display-name-resource="descriptionDefault">
    3. Restart the Commerce Platform server.

  4. In Oracle Adaptive Intelligent Apps for CX, copy the clickstream JavaScript as follows:

    1. On the navigation menu, under Connections, select Commerce Widgets.

    2. In the Platform list, select Oracle Commerce Platform.

    3. In the row for the Clickstream widget type, click Copy Code.

  5. Paste the code into a file so you can access it easily later.

    You will paste this code on the pages to track when a consumer performs an action on your site, as described in the next section.

Widget Configuration Steps

Perform the following steps for each widget to configure:

  1. In Oracle Adaptive Intelligent Apps for CX, get the widget code as follows:

    1. On the navigation menu, under Connections, select Commerce Widgets.

    2. In the Platform list, select Oracle Commerce Platform.

    3. Click Copy Code for the widget type you want to configure.

      Tip: To ensure that you don't overwrite content on your clipboard, paste the code to a temporary text file.
  2. Add the widget code to the page as appropriate for your storefront. For example, you might insert the widget code as follows:

    1. Log in to the Oracle Commerce Platform Business Control Center as an administrator.

    2. Click Workbench and then click Experience Manager.

    3. Select Web > Home Pages > Default Homepage.

    4. On the Editor tab, select mainContent, and then click Add.

    5. In the Select Cartridge window, select RichTextMain, and then click OK.

    6. In the Section Settings section, enter a unique name.

    7. In the Contents section, click Enter Text.

    8. In the Edit Text Area window, paste the copied widget code, and then click OK.

    9. Click Save.

      See Adding cartridges to rules in the Oracle Commerce Workbench User's Guide for more information.

  3. To track when a consumer performs an action on your site (such as adding or removing an item from their cart, or making a purchase) paste the clickstream code on all pages right before the closing </body> tag.

  4. For promotion widgets, ensure that you have associated a name and image as required for display in the application. Refer to Field Mapping and REST API for Oracle Adaptive Intelligent Apps for CX for more information.

Configure Widgets for Other Commerce Applications

To configure widgets for non-Oracle commerce applications, you must follow these general steps summarized here:

  1. Get the widget template code

  2. Update the widget code with your REST service calls.

    • Add a call to your own REST service.

    • Paste the widget template code into your code.

  3. Add clickstream event tracking to your site pages.

To get the widget code:

  1. On the navigation menu, under Connections, select Commerce Widgets.

    Widget Templates page for other commerce applications showing widget type, sample code, and option to copy to clipboard

  2. In the Platform list, select Other Commerce Application.

  3. Click Copy Code for the widget type you want to configure.

    Tip: To ensure that you don't overwrite content on your clipboard, paste the code to a temporary text file.
  4. Repeat these steps for each widget type, as needed.

See Create REST Service Calls in Widget Templates, Add Clickstream Event Tracking to Site Pages, and Override Default Titles for Recommendation Widgets for additional tasks to perform.

Creating REST Service Calls in Widget Templates

The scripts in the widget templates contain a method named getData. If you're using a non-Oracle commerce system, you must use the getData method to retrieve an array of recommendation IDs and pass an array of details about that product or promotion.

To use the getData method for a product or promotion:

  1. Add a call to your own REST service and paste the widget template code into your code.

  2. When you obtain your data, you can change the temporary values between the single quote characters with the actual values for the product or promotion.

    getData: function(data) {
    
        var results = [], _self = this, i = 0;
        $.each(data.items, function(key, value){
            result = {
                product : {
                    prodID: value,
                    listPrice: '*** INSERT LIST PRICE HERE ***',
                    displayName: '*** INSERT DISPLAY NAME HERE ***',
                    smallImageURLs: '*** INSERT IMAGE URL HERE ***',
                    route: '*** LINK TO PRODUCT HERE *** '  +'?r='+data.id
                }
            };
            results[key] = result.product;
            if(data.items.length === ++i) _self._render(results);
        });
        this.resize();
    },

    For example, you might modify this in your code substituting values as shown here.

    getData: function(data) {
        var results = [], _self = this, i = 0;
        $.each(data.items, function(key, value){
    
            $.getJSON('https:www.mysite.com/rest/service/for/your/products?
                productId=value', function (myData) {
                    result = {
                        product : {
                            prodID: value,
                            listPrice: myData.price,
                            displayName: myData.name,
                            smallImageURLs: myData.url,
                            route: myData.link  +'?r='+data.id
                            }
                       };
                       results[key] = result.product;
                       if(data.items.length === ++i) _self._render(results);
               });
                                 
         });
    }
    
  3. To add parameters to your recommendations, such as the maximum number of items in the carousel or a custom title, or to add filters, add them directly before the get command. For example:

    $.AioClickStream.aioEventListeners('3rd-party', false, false,
      function(aioRecommendData) {
        aioRecommendData.numberOfItems = 12;
        aioRecommendData.filters = [
          {
            usage: "filter",
            strategy: "productCategory",
            id: "PC1"
          },{
            usage: "exclusion",
            strategy: "brand",
            id: "Brand1,Brand2"
          }
        ];
        aioRecommendData.get('product', function (data) {
          .....
        });
      }
    );
    Note: The adaptive intelligence models work best when no filters are applied so that there's sufficient opportunity to learn and react to preferences and behavior. Because filters can affect recommendations, it's best practice to use them only in special circumstances.

See Add Clickstream Event Tracking to Site Pages for additional steps to perform.

Adding Clickstream Event Tracking to Site Pages

When a consumer performs an action on your site, this triggers an event to use for clickstream tracking. These events could be signing in, adding or removing an item from their cart, or making a purchase. If you're using a non-Oracle commerce system, you must add event tracking for your widgets manually as described in this topic.

  1. For each page of your commerce site, add clickstream template code after jQuery is imported but before any code that sends events.

    For example:

     $(document).ready(function() {
        /*
         * Set global variables if they haven't already been set somewhere else
         * send data for site entry if it hasn't been sent somewhere else
         */
         if(!window.hasOwnProperty('$aio_settings')) {
            window.$aio_settings = {
               serverUrl: 'https://<myserver>:<port>',
                  timeout: 6000
          };
       }
    
        // initialize
        $.getScript("https://<host>:<port>/offers_public/js/aio_clicks.js", function() {
            aioEventListeners('3rd-party-global', false, false, function(aioClickData) {
               aioClickData.send();
           });
        });
    });
    
  2. Add any other widget in place on the page where you want the widget. Insert the JavaScript for events you want tracked after the clickstream widget.

    Refer to Clickstream Events for a list of events you can use along with code examples.

Override Default Titles for Recommendation Widgets

The default text that displays for recommendations is We think you'd like ${displayName} where displayName is replaced with the product name. You can override this default text by modifying the HTML in the widget template code as described in this topic.

Note: If you're using Oracle Commerce Cloud, use the predefined templates to update the Title setting for the widget you want to modify. See Configure Widgets for Oracle Commerce Cloud.

To override the default title text:

  1. In the HTML you copied for your widgets, locate the tag for the title as shown in this example:

    <div> id="aio_product" class="loading">
       <div class="aio_product_item">
          <h2>We think you'd like ${displayName}</h2>
          <a href="${route}">
             <img class="aio_product_image" delay_src="${largeImageUrl}" alt="${displayName}" />
             <div class="aio_brand_name">${brand}</div>
             <div class="aio_list_price"><span class="glyphicon glyphicon-tag" aria-hidden="true"></span> $${lowestListPrice}</div>
          </a>
       </div>
    </div>
  2. Substitute "We think you'd like" with the text that you want for the widget.

Clickstream Events

If you use Oracle Commerce Platform or a third-party commerce application for your widgets, you can use a variety of predefined events in your code. This table lists these events, their required attributes, and code examples.

Event Name Triggered When Required Attributes Code Example
LoginSuccess A consumer successfully signs in userId should contain the consumer's ID for the storefront $.aioCommerceEvent('LoginSuccess', {userId: 'u123'});
LogoutSuccess A consumer successfully signs out (None) $.aioCommerceEvent('LogoutSuccess');
AddedItem A consumer successfully adds an item to the cart cart containing a comma-separated list of all product IDs currently in the cart

product containing the product ID for the last item added to the cart

$.aioCommerceEvent('AddedItem', {cart:'123,124,125', product:'123'});
RemovedItem A consumer successfully removes an item from the cart cart containing a comma-separated list of all product IDs currently in the cart

product containing the product ID for the last item removed from the cart

$.aioCommerceEvent('RemovedItem', {cart:'123,124,125', product:'123'});
SearchResults A consumer searches the storefront searchTerm containing the user's search term $.aioCommerceEvent('SearchResults', {searchTerm: 'shoes' });
OrderComplete A consumer completes a purchase orderId containing the order ID of the completed order

cart containing a comma-separated list of all product IDs currently in the cart

$.aioCommerceEvent('OrderComplete', {orderId: 'o123',cart:'123,124,125' });
HomePage A consumer arrives on the home page of the storefront (None) $.aioCommerceEvent('HomePage');
ProductPage A consumer arrives on the product page productId containing the product ID of the product page $.aioCommerceEvent('ProductPage', {productId: 'p123' });
CategoryPage A consumer arrives on the category page categoryId containing the category ID of the category page $.aioCommerceEvent('CategoryPage', {categoryId: 'c123' });
PageLoad A consumer arrives on any page with a page ID. This is in addition to the product, category, and home page events. pageId containing the unique ID of the page $.aioCommerceEvent('PageLoad', {pageId: 'home' });
ContentClick A consumer clicks a link inside any content area on the site. contentId containing the unique reference ID for the content area of the page $.aioCommerceEvent('ContentClick', {contentId: 'content-area-1'});