GraphQL API

You can integrate banners into your frontend applications using our BannerGraphQl API. This API allows developers to retrieve banner placeholders with context-awareness (based on page, product, category, cart, etc.) and to track user impressions and clicks for analytics.

tip

The Mirasvit_BannerGraphQl module ships with the extension and is enabled by the installation command, so there is nothing extra to install. Until version 1.4.0 it was a separate package, mirasvit/module-banner-graph-ql; upgrading the extension removes that package by itself.

Use this API to dynamically insert promotional banners in any storefront area and monitor their performance.

For general GraphQL usage, refer to the Magento GraphQL Developer Guide.

Banner GraphQL objects overview

The BannerGraphQl API provides the following object types:

• mstBannerPlaceholder: defines banner placeholder blocks
• mstBannerBanner: defines individual banners
• mstBannerContextInput: input type for contextual filtering
• Two mutations: for tracking banner impressions and clicks

The Query object can contain the following attributes:

Attribute	Description	Data Type
mstBannerPlaceholders	List of banner placeholders filtered by position and context	mstBannerPlaceholder

mstBannerPlaceholder object

Represents a placeholder where banners are rendered on the storefront.

Attribute	Description	Data Type
identifier	Unique placeholder ID	String!
renderer	Rendering mode (e.g. popup, slider, block)	String!
css	Custom CSS styling	String
delay	Delay before display (Popup, Lightbox)	Int
cookieLifetime	Cookie lifetime in seconds	Int
timeout	Autoplay timeout (Slider)	Int
prev	Previous button selector (Slider)	String
next	Next button selector (Slider)	String
close	Close button selector (Lightbox)	String
autoplay	Autoplay enabled (Slider)	Boolean
loop	Loop banners (Slider)	Boolean
navigation	Show navigation arrows (Slider)	Boolean
pagination	Show pagination dots (Slider)	Boolean
popupPosition	Position on screen (Popup)	String
maskColor	Overlay mask color (Lightbox)	String
banners	List of banners inside the placeholder	mstBannerBanner!

mstBannerBanner object

Represents the actual banner rendered inside a placeholder.

Attribute	Description	Data Type
banner_id	Unique ID of the banner	Int!
content	HTML content of the banner	String!

mstBannerContextInput object

Input object used to define the current page context (optional). Helps filter and personalize which banners should be displayed.

Attribute	Description	Data Type
actionName	Magento full action name	String
uri	Page URI (e.g., /product/sneakers.html)	String
categoryId	Current category ID	Int
productId	Current product ID	Int
cartId	Cart identifier (quote ID)	String

---

Mutation object

The Mutation object can contain the following attributes:

Attribute	Description	Data Type
mstBannerTrackImpression	Tracks banner impression (viewed)	Boolean!
mstBannerTrackClick	Tracks banner click	Boolean!

mstBannerTrackImpression Mutation

Tracks when a banner is displayed on the frontend.

Attribute	Description	Data Type
bannerId	ID of the viewed banner	Int!
referrer	Page where the banner was shown	String!

Example for impression tracking:

mutation {
mstBannerTrackImpression(bannerId: 101, referrer: "/product/sneakers.html")
}

mstBannerTrackClick Mutation

Tracks when a customer clicks on a banner.

Attribute	Description	Data Type
bannerId	ID of the clicked banner	Int!
referrer	Page where the banner was clicked	String!

Example for click tracking:

mutation {
  mstBannerTrackClick(bannerId: 101, referrer: "/product/sneakers.html")
}

---

GraphQL example

An example query that uses mstBannerPlaceholders to retrieve banners assigned to the popup position,
based on the context of a product page.

query GetPopupBanners {
  mstBannerPlaceholders(
    position: "popup",
    context: {
      uri: "/product/sneakers.html",
      productId: 123,
      categoryId: 7,
      cartId: "abcde12345"
    }
  ) {
    identifier
    renderer
    css
    delay
    autoplay
    popupPosition
    banners {
      banner_id
      content
    }
  }
}