Nozzle Piping Mismatch

    @adobe/magento-storefront-events-sdk
    TypeScript icon, indicating that this package has built-in type declarations

    1.1.19 • Public • Published

    Adobe Commerce Events SDK

    version downloads size build typescript contributing

    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 Adobe Commerce Events Collectors 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 Adobe Commerce Events Collectors.

    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/commerce-events-sdk/dist/index.js"></script>
    

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

    npm install @adobe/commerce-events-sdk

    Quick start

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

    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/commerce-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);

    Schemas and supported events

    The below methods allow you to set specific contexts based on the SDK schema and to publish a set of events supported by this API.

    Addiontally, you can publish custom events or add a custom context to a supported event.

    API reference

    The SDK 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 context 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.

    setCategory

    mse.context.setCategory(categoryCtx);

    Sets the Category context.

    setChangedProducts

    mse.context.setChangedProducts(changedProductsCtx);

    Sets the ChangedProducts context.

    setAccount

    mse.context.setAccount(accountCtx);

    Sets the Account context.

    setCustomUrl

    mse.context.setCustomUrl(customUrlCtx);

    Sets the CustomUrl context.

    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.

    setMagentoExtension @deprecated

    mse.context.setMagentoExtension(magentoExtensionCtx);

    Sets the MagentoExtension context. Includes Data Services extension version.

    This field is deprecated. setDataServicesExtension should be used instead.

    setDataServicesExtension

    mse.context.setDataServicesExtension(dataServicesExtensionCtx);

    Sets the DataServicesExtension context. Includes Data Services extension version.

    setExperiencePlatformConnectorExtension

    mse.context.setExperiencePlatformConnectorExtension(experiencePlatformConnectorExtensionCtx);

    Sets the ExperiencePlatformConnectorExtension context. Includes Experience Platform Connector extension version.

    setOrder

    mse.context.setOrder(orderCtx);

    Sets the Order context.

    setPage

    mse.context.setPage(pageCtx);

    Sets the Page context.

    setProduct

    mse.context.setProduct(productCtx);

    Sets the Product context.

    setRecommendations

    mse.context.setRecommendations(recommendationsCtx);

    Sets the Recommendations context.

    setRecommendationsExtension

    mse.context.setRecommendationsExtension(recommendationsExtensionCtx);

    Sets the RecommendationsExtension context. Includes Recommendations extension version.

    setReferrerUrl

    mse.context.setReferrerUrl(referrerUrlCtx);

    Sets the ReferrerUrl context.

    setSearchExtension

    mse.context.setSearchExtension(searchExtensionCtx);

    Sets the SearchExtension context. Includes Live Search extension version.

    setSearchInput

    mse.context.setSearchInput(searchInputCtx);

    Sets the SearchInput context.

    setSearchResults

    mse.context.setSearchResults(searchResultsCtx);

    Sets the SearchResults context.

    setShopper

    mse.context.setShopper(shopperCtx);

    Sets the Shopper context.

    setShoppingCart

    mse.context.setShoppingCart(shoppingCartCtx);

    Sets the ShoppingCart context.

    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.

    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.getChangedProducts();
    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:

    mse.publish.addToCart();
    mse.publish.createAccount(ctx);
    // write a `commerce-custom` event to the adobeDataLayer
    // any object passed in will be set under `customContext` for this event
    mse.publish.custom({
        /*...*/
    });
    mse.publish.customUrl(ctx);
    mse.publish.editAccount(ctx);
    mse.publish.initiateCheckout(ctx);
    mse.publish.openCart(ctx);
    mse.publish.pageActivitySummary(ctx);
    mse.publish.pageView(ctx);
    mse.publish.placeOrder(ctx);
    mse.publish.productPageView(ctx);
    mse.publish.recsItemAddToCartClick(unitId, productId, ctx);
    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.createAccount(handler, options);
    mse.subscribe.custom(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.openCart(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.createAccount(handler);
    mse.unsubscribe.custom(handler);
    mse.unsubscribe.customUrl(handler);
    mse.unsubscribe.editAccount(handler);
    mse.unsubscribe.dataLayerChange(handler);
    mse.unsubscribe.dataLayerEvent(handler);
    mse.unsubscribe.initiateCheckout(handler);
    mse.unsubscribe.openCart(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.

    Keywords

    none

    Install

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

    DownloadsWeekly Downloads

    2,573

    Version

    1.1.19

    License

    MIT

    Unpacked Size

    130 kB

    Total Files

    81

    Last publish

    Collaborators

    • adobehalls
    • fullcolorcoder
    • marbec
    • tripod
    • garthdb
    • lazd
    • adobe-admin
    • patrickfulton
    • trieloff
    • shazron
    • krisnye
    • dcpfsdk
    • natebaldwin
    • devongovett
    • aspro83
    • symanovi
    • dpfister
    • stefan-guggisberg
    • korra
    • rofe
    • kptdobe