Drive Commerce Cartographer

# Event Types

Cartographer generates a number of events and notifications throughout the lifecycle of the recommender instances. These notifications include simple notifications that allow developers to enhance parts of the recommender experience or improve analytics trackers, and more complex events that enable deep functionality customization.

# afterInitialize

afterInitialize event is fired when using built-in lifecycle manager (see run method) after the recommender has been fully loaded, rendered, and is ready to receive user input.

# afterUpdateFactor

afterUpdateFactor event is fired after the recommendation input has changed for any reason such as the user answered a question, some value was selected programmatically, recommender state has been reset, etc.

# summaryChanged

summaryChanged event is fired whenever there is a significant update to the question's answers.

EVENT PARAMETER PURPOSE
summary Summary object. summary method can also be used to retrieve the current summary.

# afterActivateQuestion

afterActivateQuestion indicates that the question has been activated, i.e. at least one (for the multiple-select question type) answer has been selected.

EVENT PARAMETER PURPOSE
options.question DOM element containing the question
options.page DOM element containing the page
options.pageIndex Page index
options.pageLast Indicates whether this is a last page in the experience
options.complete Indicates whether page is complete, e.g. all questions on the page have been answered

# afterDeactivateQuestion

This is the counterpart to afterActivateQuestion, indicating that a question has been deactivated and no longer has any answers selected.

# beforeRetrieveRecommendations

beforeRetrieveRecommendations allows customizing whether to retrieve and display recommendations after question activation or deactivation.

EVENT PARAMETER PURPOSE
options.question DOM element containing the question
options.page DOM element containing the page
options.pageIndex Page index
options.pageLast Indicates whether this is a last page in the experience
options.complete Indicates whether page is complete, e.g. all questions on the page have been answered

# renderRecommendations

renderRecommendations allows the override of the default processing of recommendations data and provide custom rendering instead of using built-in templates.

# afterRenderRecommendations

When using out-of-stock product recommendation templates, afterRenderRecommendations notifications will be triggered after the DOM has been updated with products content.

# afterImpression

Triggered after a recommended product has been made visible to the site user. For example, if a product was shown above the fold or the user has scrolled to reveal recommendations that are below the fold.

EVENT PARAMETER PURPOSE
productId Product ID
parentProductId Parent product ID, if known

# historyChanged

Notifies host page about user history changes. This can be used to improve overall site navigation experience, for example, to support Back browser button and enable returning to the recommendation list without having to start over.

EVENT PARAMETER PURPOSE
history Recommendation events history

# replayComplete

Notifies host page when history replay has been completed and all user selections have been applied.

EVENT PARAMETER PURPOSE
No parameters available

# addToCart

Indicates that built-in template add-to-cart button has been triggered.

EVENT PARAMETER PURPOSE
productId Product ID to be added to cart, may be a variation ID
parentProductId Parent product ID, if known
name Product name
price Product price as captured during the last product import
priceCurrency Price currency

# Custom Page Routing

Recommender experience may contain multiple "pages" (which are presented on the same site page) of questions. Unless Page Routing (v2) is used, default Cartographer behavior is to display them sequentially, while allowing site user to move to another page only after completing all questions on the page. While Cartographer page routing feature can allow to rather complex recommendation flows, this behavior can be customized using following events.

# enterPage

Notifies host page after a user has entered a new page. Allows performing additional UX enhancements, such as page animations.

EVENT PARAMETER PURPOSE
options.page DOM element containing the page
options.pageIndex Page index
options.pageLast Indicates whether this is a last page in the experience
options.complete Indicates whether page is complete, e.g. all questions on the page have been answered

# pageComplete

pageComplete event notifies about the completion of all questions on the current page.

EVENT PARAMETER PURPOSE
options.currentPage Reference to DOM element containing completed page
options.nextPage Next page as determined by routing events
returns options.advance Set to true to automatically advance to the next page without having a user to click Next Page button

# routeAdvancePage

routeAdvancePage is called after the site user has clicked on the "Next" button to advance to the next page and is used to determine the next target page. The default behavior is to navigate to the next page in the list, but this may be overridden by providing an alternate page, or by canceling navigation altogether.

var recommender = new Drive.GuidedRecommender({
        container: $('.placeholder'),

        events: {
            routeAdvancePage: function (e) {
                // Navigate from page one to page three.
                if (e.currentPage.page.is('.slug-page-one')) {
                    e.nextPage = $('.recommender .slug-page-three');
                } else {
                    // Cancel navigation and stay on the current page.
                    return true;
                }
            }
        }
    });

# routeReturnPage

Similar to routeAdvancePage, this event can be used to determine the target page to return to after the user has clicked on the "Back" button.

# beforeAdvancePage

Triggered before playing an animation of advancing the page. This event may be used to provide additional page enhancement or interactivity, such as playing a video upon arriving to the specific page.

# beforeAdvancePage

Similar to beforeAdvancePage, this event will be triggered when returning to one of the previous pages.

# pageAnimation

pageAnimation allows to customize page transition animations.

EVENT PARAMETER PURPOSE
options.from Reference to DOM element containing current page
options.top Reference to DOM element containing next page

# Third-Party Analytics Integration

Cartographer includes a robust built-in analytics tool that tracks user sessions, product impressions, conversions, etc. However, Cartographer also provides an easy way to integrate with third-party analytics packages (e.g., Google Analytics, Adobe Omniture, etc.) to improve the capture and to integrate recommendations into overall storefront metrics. This can be achieved by taking advantage of events model described above. Alternatively developers may tap into the firehose metrics event notifications. Please consult Drive Commerce support (support@drivecommerce.com) for implementation.

# Listing for firehose Metric Events

Attach event listener (via jQuery or another method) to listen to drive::metrics event. Below is a code snippet to listen to analytics events and to write them to the browser console:

    $(document).on('drive::cartographer::metrics', function (e, events) {
        console.log('Cartographer Metrics:', JSON.stringify(events));
    });

← Creating Native Applications →