Drive Commerce Cartographer

# Questionnaire Integration

Cartographer provides the hosted JavaScript plugin (https: //api.cartographer.drivecommerce.com/api/v3/runtime/client) that implements functional flow and responsible for communication with the backend services. Salesforce Commerce Cloud implementation side, in turn, provides elements necessary for skinning the experience, such as HTML templates, CSS, and JavaScript implementing presentation aspects of the experience.

# Commerce Cloud Integration

Recommender instances may be deployed to Salesforce Commerce Cloud using one of the following options:

  • Custom Pipeline: Salesforce Commerce Cloud storefront uses a custom pipeline coupled with a template file.
    • Pros: A developer friendly option, it provides the most flexibility when it comes to experience rendering. Additionally, a custom URL may be possible.
    • Cons: May restrict potential recommender placement options. Requires code deployment and replication.
  • Content Asset and/or Slots: Recommender code is placed within a content asset or a slot.
    • Pros: This provides most flexibility with regards to placement of recommender tool on the site, as it may be easily reused on a number of pages. Typically, no code deployment is required.
    • Cons: However, all HTML, CSS, and JavaScript code has to be placed in the same content asset, which makes code less readable and harder to maintain, unless third-party code management tools are used to mitigate the impact.

# Making Open Commerce API Changes

Cartographer uses OCAPI to ingest product data and make it available for recommendation builder. While it is generally recommended that a production deployment should use Salesforce Commerce Cloud production OCAPI endpoints to provide the most up-to-date pricing and inventory availability data, staging access may also acceptable given a few conditions:

  • Staging environment contains representative pricing information
  • Unavailable products are marked as such in staging to reflect production inventory status
  • Staging provides representative product data, including base image URLs

Cartographer requires access to the Shop API to retrieve product information, pricing, and availability. Depending on the preferred approach, Cartographer can use existing Client ID or can be provided with a new Client ID.

If Open Commerce API is already configured and client ID will be reused:

  • Navigate to OCAPI settings area:
    • Business Manager
    • Administration
    • Site Development
    • Open Commerce API Settings
    • Select Shop API in either global or site context
  • Validate that JSON configuration is populated
  • Validate that access to product, product_search, and category resources is allowed by checking for presence of permissions to following resources:
    • /categories/
    • /products/
    • /products/images/
    • /products/availability/
    • /products/prices/
    • /products/links/
    • /products/promotions/
    • /products/options/
    • /products/set_products/
    • /products/bundled_products/
    • /products/variations/
    • /product_search/
    • /product_search/availability/
    • /product_search/images/
    • /product_search/prices/
    • /product_search/variations

If Open Commerce API is NOT configured, please refer to the Salesforce Commerce Cloud Open Commerce API documentation for details described in the following steps.

  • Navigate to the Salesforce Commerce Cloud Account Manager and create new API client ID.
  • Populate Open Commerce API Settings:
    • Create a new set of OCAPI configuration settings. Drive Commerce can provide a template configuration upon request.

# Script Loading

Dynamic loading is a preferred method of integrating Cartographer, as it does not block page functionality while the script is loading and being initialized.

WARNING

Dynamic loading methods using jQuery getScript function, deferred, or async script tags are not supported.

# Page Initialization Code (Modern Browsers)

(function (d, url, c) {
    var script = d.createElement('script');
    script.type = 'text/javascript';
    script.onload = function () { if (c) { c(); } };
    script.src = url;
    d.getElementsByTagName('body')[0].appendChild(script);
}(document, 'https://api.cartographer.drivecommerce.com/api/v3/runtime/client', function () {

    // Script has been loaded and Cartographer is now ready for use.
    var recommender = new Drive.GuidedRecommender({
        // etc.
    });

}));

# Page Initialization Code (IE8-Compatible)

(function (d, url, c) {
    var script = d.createElement('script');
    script.type = 'text/javascript';
    if (script.addEventListener) {
        script.addEventListener('load', function () { if (c) { c(); } }, false);
    } else if (script.readyState) {
        script.onreadystatechange = function () { if (this.readyState === 'loaded' && c) { c(); } };
    }
    script.src = url;
    d.getElementsByTagName('body')[0].appendChild(script);
}(document, 'https://api.cartographer.drivecommerce.com/api/v3/runtime/client', function () {

    // Script has been loaded and Cartographer is now ready for use.
    var recommender = new Drive.GuidedRecommender({
        // etc.
    });

}));

# Static Script Loading

The simplest method of integration comes at a cost of blocking page functionality while the script is loading, which may reduce overall page performance.

# Add at End of Body Tag

<script type="application/javascript" src="https://api.cartographer.drivecommerce.com/api/v3/runtime/client"></script>

# Page Initialization Code

$(function () {
    // Cartographer is now ready for use.
    var recommender = new Drive.GuidedRecommender({
        // etc.
    });
});

# Waiting for DOM Ready

Most commonly, Cartographer recommenders are integrated into the site through available platform's CMS capabilities by placing required HMTL, CSS, and JavaScript snippets in some placeholder on the target page. This often results in Cartographer's integration code being rendered inline within the page HTML, with inline JavaScript being run immediately during page parsing, including code may use jQuery for its operations. This conflicts with the modern optimization recommendations to place all JavaScript near the end of the tag, including jQuery.

In order to avoid running recommender code prematurely and thus failing, it is recommended to use one of the following techniques to defer script initialization.

# jQuery Loaded in Head Element

<script>
    $(function () {
        // Load and initialize Cartographer script
    });
</script>

# jQuery Loaded at Bottom of Page

<script>
    // Note: IE8 compatibility requires a more complex event handling.
    document.addEventListener('DOMContentLoaded', function (event) {
        // Load and initialize Cartographer script
    });
</script>

← Reporting Conversions →