@grahamcrackers/commerce-events-sdk

Magento Storefront Events SDK

Overview

This package serves as the foundation for eventing on an Adobe Commerce storefront. It provides access to a common data layer, and an event publishing and subscription service.

You can handle the events in a custom implementation, or use the Magento Storefront Event Collector package that listens for events and sends them to Adobe Commerce edges for processing.

Note: When an event is published through the SDK, all subscribers to that event get notified. Defining a custom listener shouldn't preclude you from also running the Magento Storefront Event Collector.

Our context schemas are designed to simplify forwarding to two edges:

• Adobe Commerce Data Services (maintained by Adobe Engineering and used to power merchant performance dashboards)
• Adobe Experience Platform (requires a subscription and additional merchant setup; data can be used by merchants inside the Adobe Experience Platform for detailed analytics, targeted merchandising, real time customer data profiles, and more)

Installation

This SDK can be used as a hosted script, or bundled in a JavaScript application. The script version is hosted on unpkg, and the bundled version is hosted on npm.

To load the SDK as a script, use the following snippet.

<script src="https://unpkg.com/@adobe/magento-storefront-events-sdk/dist/index.js"></script>

To install the script as a dependency, run this command.

npm install @adobe/magento-storefront-events-sdk

Quick Start

Once imported, you have access to the four main functions of the Events SDK.

• Context - set context data
• Publish - publish events
• Subscribe - subscribe to events
• Unsubscribe - unsubscribe from events

Below is a code example of how to get started.

IMPORTANT: Relevant context data must be populated before publishing events that require it.

import mse from "@adobe/magento-storefront-events-sdk";
// handler - can go in a different module
function addToCartHandler(event) {
    // do something with the event
}
// subscribe to events
mse.subscribe.addToCart(addToCartHandler);

// set context data
const shoppingCartContext = {
    id: "1",
    items: [
        {
            id: "shoppingCart",
            product: {
                productId: 111111,
                sku: "ts001",
                pricing: {
                    regularPrice: 20.0,
                    currencyCode: "USD",
                },
            },
            quantity: 1,
        },
    ],
};
mse.context.setShoppingCart(shoppingCartContext);

// publish events
mse.publish.addToCart();

// unsubscribe from events
mse.unsubscribe.addToCart(addToCartHandler);

API Reference

The SDK API is broken down into four major parts: Context, Publish, Subscribe, Unsubscribe.

Context

These setters can be used to specify context in the mse:

setAEP

mse.context.setAEP(aepCtx);

Sets the AEP which can be used by event handlers to forward events to the Adobe Experience Platform. A client must have an AEP subscription and provide a valid IMS Org Id and Datastream Id.

• context schema definition
• context example

setCategory

mse.context.setCategory(categoryCtx);

Sets the Category context.

• context schema definition
• context example

setAccount

mse.context.setAccount(accountCtx);

Sets the Account context.

setCustomUrl

mse.context.setCustomUrl(customUrlCtx);

Sets the CustomUrl context.

• context schema definition
• context example

setEventForwarding

mse.context.setEventForwarding(eventForwardingCtx);

Sets the EventForwarding context. Tells a handler if it should forward events to Adobe Commerce DataSolutions (commerce: true), Adobe Experience Platform (aep: true), or both.

• context schema definition
• context example

setMagentoExtension @deprecated

mse.context.setMagentoExtension(magentoExtensionCtx);

Sets the MagentoExtension context. Includes Data Services extension version.

This field is deprecated. setDataServicesExtension should be used instead.

• context schema definition
• context example

setDataServicesExtension

mse.context.setDataServicesExtension(dataServicesExtensionCtx);

Sets the DataServicesExtension context. Includes Data Services extension version.

• context schema definition

setOrder

mse.context.setOrder(orderCtx);

Sets the Order context.

• context schema definition
• context example

setPage

mse.context.setPage(pageCtx);

Sets the Page context.

• context schema definition
• context example

setProduct

mse.context.setProduct(productCtx);

Sets the Product context.

• context schema definition
• context example

setRecommendations

mse.context.setRecommendations(recommendationsCtx);

Sets the Recommendations context.

• context schema definition
• context example

setRecommendationsExtension

mse.context.setRecommendationsExtension(recommendationsExtensionCtx);

Sets the RecommendationsExtension context. Includes Recommendations extension version.

• context schema definition

setReferrerUrl

mse.context.setReferrerUrl(referrerUrlCtx);

Sets the ReferrerUrl context.

• context schema definition
• context example

setSearchExtension

mse.context.setSearchExtension(searchExtensionCtx);

Sets the SearchExtension context. Includes Live Search extension version.

• context schema definition

setSearchInput

mse.context.setSearchInput(searchInputCtx);

Sets the SearchInput context.

• context schema definition
• context example

setSearchResults

mse.context.setSearchResults(searchResultsCtx);

Sets the SearchResults context.

• context schema definition
• context example

setShopper

mse.context.setShopper(shopperCtx);

Sets the Shopper context.

• context schema definition
• context example

setShoppingCart

mse.context.setShoppingCart(shoppingCartCtx);

Sets the ShoppingCart context.

• context schema definition
• context example

setStorefrontInstance

mse.context.setStorefrontInstance(storefrontCtx);

Sets the StorefrontInstance context. This context is used when forwarding data to Adobe Commerce Data Services to identify the Adobe Commerce instance associated with the data.

• context schema definition
• context example

setContext

mse.context.setContext(name, ctx);

Sets a custom Context.

These getters are available for accessing context data:

mse.context.getAEP();
mse.context.getCategory();
mse.context.getContext(name);
mse.context.getCustomUrl();
mse.context.getEventForwarding();
mse.context.getMagentoExtension();
mse.context.getDataServicesExtension();
mse.context.getOrder();
mse.context.getPage();
mse.context.getProduct();
mse.context.getRecommendations();
mse.context.getReferrerUrl();
mse.context.getProduct();
mse.context.getRecommendations();
mse.context.getRecommendationsExtension();
mse.context.getSearchExtension();
mse.context.getSearchInput();
mse.context.getSearchResults();
mse.context.getShopper();
mse.context.getShoppingCart();

Publish

These functions publish events which notify all subscribers:

// requires shoppingCart ctx to be set
mse.publish.addToCart();

// requires shoppingCart ctx to be set
mse.publish.abandonCart();

mse.publish.createAccount(ctx);

mse.publish.customUrl(ctx);

mse.publish.editAccount(ctx);

mse.publish.initiateCheckout(ctx);

// requires shoppingCart ctx and productCtx to be set
mse.publish.instantPurchase(ctx);

mse.publish.pageActivitySummary(ctx);

mse.publish.pageView(ctx);

// requires shoppingCart ctx and orderContext to be set
mse.publish.placeOrder(ctx);

// requires shoppingCart ctx and productCtx to be set
mse.publish.productPageView(ctx);

// requires recommendationsContext to be set
mse.publish.recsItemAddToCartClick(unitId, productId, ctx);

// requires recommendationsContext to be set
mse.publish.recsItemClick(unitId, productId, ctx);

mse.publish.recsRequestSent(ctx);

mse.publish.recsResponseReceived(ctx);

// requires recommendationsContext to be set
mse.publish.recsUnitRender(unitId, ctx);

// requires recommendationsContext to be set
mse.publish.recsUnitView(unitId, ctx);

mse.publish.referrerUrl(ctx);

mse.publish.removeFromCart(ctx);

// requires searchResultsContext to be set
mse.publish.searchCategoryClick(searchUnitId, name, ctx);

// requires searchResultsContext to be set
mse.publish.searchProductClick(searchUnitId, sku, ctx);

// requires searchInputContext to be set
mse.publish.searchRequestSent(searchUnitId, ctx);

// requires searchResultsContext to be set
mse.publish.searchResponseReceived(searchUnitId, ctx);

// requires searchResultsContext to be set
mse.publish.searchResultsView(searchUnitId, ctx);

// requires searchResultsContext to be set
mse.publish.searchSuggestionClick(searchUnitId, suggestion, ctx);

// requires shoppingCartContext to be set
mse.publish.shoppingCartView(ctx);

mse.publish.signIn(ctx);

mse.publish.signOut(ctx);

mse.publish.updateCart(ctx);

Subscribe

These functions subscribe to events:

mse.subscribe.addToCart(handler, options);
mse.subscribe.abandonCart(handler, options);
mse.subscribe.createAccount(handler, options);
mse.subscribe.customUrl(handler, options);
mse.subscribe.editAccount(handler, options);
mse.subscribe.dataLayerChange(handler, options);
mse.subscribe.dataLayerEvent(handler, options);
mse.subscribe.initiateCheckout(handler, options);
mse.subscribe.instantPurchase(handler, options);
mse.subscribe.pageActivitySummary(handler, options);
mse.subscribe.pageView(handler, options);
mse.subscribe.placeOrder(handler, options);
mse.subscribe.productPageView(handler, options);
mse.subscribe.recsItemAddToCartClick(handler, options);
mse.subscribe.recsItemClick(handler, options);
mse.subscribe.recsRequestSent(handler, options);
mse.subscribe.recsResponseReceived(handler, options);
mse.subscribe.recsUnitRender(handler, options);
mse.subscribe.recsUnitView(handler, options);
mse.subscribe.referrerUrl(handler, options);
mse.subscribe.removeFromCart(handler, options);
mse.subscribe.searchCategoryClick(handler, options);
mse.subscribe.searchProductClick(handler, options);
mse.subscribe.searchRequestSent(handler, options);
mse.subscribe.searchResponseReceived(handler, options);
mse.subscribe.searchResultsView(handler, options);
mse.subscribe.searchSuggestionClick(handler, options);
mse.subscribe.shoppingCartView(handler, options);
mse.subscribe.signIn(handler, options);
mse.subscribe.signOut(handler, options);
mse.subscribe.updateCart(handler, options);

Unsubscribe

These functions unsubscribe from events:

mse.unsubscribe.addToCart(handler);
mse.unsubscribe.abandonCart(handler);
mse.unsubscribe.createAccount(handler);
mse.unsubscribe.customUrl(handler);
mse.unsubscribe.editAccount(handler);
mse.unsubscribe.dataLayerChange(handler);
mse.unsubscribe.dataLayerEvent(handler);
mse.unsubscribe.initiateCheckout(handler);
mse.unsubscribe.instantPurchase(handler);
mse.unsubscribe.pageActivitySummary(handler);
mse.unsubscribe.pageView(handler);
mse.unsubscribe.placeOrder(handler);
mse.unsubscribe.productPageView(handler);
mse.unsubscribe.recsItemAddToCartClick(handler);
mse.unsubscribe.recsItemClick(handler);
mse.unsubscribe.recsRequestSent(handler);
mse.unsubscribe.recsResponseReceived(handler);
mse.unsubscribe.recsUnitRender(handler);
mse.unsubscribe.recsUnitView(handler);
mse.unsubscribe.referrerUrl(handler);
mse.unsubscribe.removeFromCart(handler);
mse.unsubscribe.searchCategoryClick(handler);
mse.unsubscribe.searchProductClick(handler);
mse.unsubscribe.searchRequestSent(handler);
mse.unsubscribe.searchResponseReceived(handler);
mse.unsubscribe.searchResultsView(handler);
mse.unsubscribe.searchSuggestionClick(handler);
mse.unsubscribe.shoppingCartView(handler);
mse.unsubscribe.signIn(handler);
mse.unsubscribe.signOut(handler);
mse.unsubscribe.updateCart(handler);

Support

If you have any questions or encounter any issues, please reach out on GitHub.