Banners

Access prerequisites

• Permission (module): viewBanners OR manageBanners (either module is sufficient to view the screen). The create, edit, and delete actions specifically require manageBanners (buttons protected by *appHasPermission="'manageBanners'").
• License/Feature: None.
• Menu container: GENERAL → Communication group (icon campaign) → Banners.

What it is / when to use

Screen for managing the banners on the Midas-Web home screen (/home): promotional campaigns, contextual messages, and onboarding cards. The customer configures everything (text, image, validity period, order, CTA) without depending on a deploy. Banners are persisted in the CustomerProfileService (CPM) and served to the app already filtered by validity and sorted. Use it to run campaigns, display notices, and guide new users autonomously.

Prerequisites

• Permission: viewBanners or manageBanners registered for the role. Permission in Axia is dual — CPM enum on the backend (manageBanners/viewBanners) and a dynamic module in the DB; both must exist for the action to appear and work. Mutations (create/edit/delete/activate) require manageBanners.
• License/Feature: none.
• Dependencies on other screens: image upload uses the files API (POST /api/v1/files, image storage). No other screen needs to exist beforehand.

Step by step

1. Access the Communication → Banners menu.
2. The table lists banners sorted by display order (display_order). Use the Type filter to restrict to PROMOTIONAL, CONTEXTUAL, ONBOARDING, or All.
3. Click Add (requires manageBanners) to open the form.
4. Choose the Type — the form shows/hides fields according to the type.
5. Fill in texts, images (for promotional), CTA, validity period, and flags.
6. Click Save.
7. In the table, use the status toggle to activate/deactivate, the chart icon to view click metrics, the pencil to edit, and the trash to delete.

Fields

Listing

Column	What it shows	Data source
Name (name)	Internal banner name	banner.name
Type (type)	PROMOTIONAL / CONTEXTUAL / ONBOARDING (colored chip)	banner.type
Title (title)	Displayed title (or —)	banner.title
Period (period)	Validity start → end (dd/MM/yy)	start_date / end_date
Order (order)	Display position	display_order
Status (status)	Active/inactive toggle	is_active
Actions	Metrics / Edit / Delete	—

Form (modal)

Field	What it is	Required?	System/backend effect
Name (name)	Internal banner identifier	Yes	Validated on submit; used to identify/delete.
Type (type)	PROMOTIONAL, CONTEXTUAL, or ONBOARDING	Yes	Defines the component rendered in the app: image+CTA carousel (promotional), icon alert (contextual), dismissable card (onboarding). Controls which fields appear in the form.
Display order (display_order)	Relative position on the home screen	No (default 0)	Banners are sorted by display_order ascending, in the table and in the app.
Title (title)	Main text	No	Displayed on the banner.
Icon (icon_name)	Material icon name (e.g.: warning, info, verified)	No	Only appears for CONTEXTUAL/ONBOARDING; defines the alert/card icon.
Subtitle (subtitle)	Secondary text	No	Displayed below the title.
Main image (image_url)	Banner image	No	Only appears for PROMOTIONAL. Upload (≤ 5 MB) via files API; stores the returned URL, not the binary.
Responsive image (image_url_responsive)	Mobile version of the image	No	PROMOTIONAL only; same upload flow, used on smaller screens.
CTA label (cta_label)	Action button text	No	Defines the button; without a label, no CTA is visible.
Internal route (cta_internal_route)	Internal destination (e.g.: /wallet, /exchange)	No	In-app navigation when the CTA is clicked.
External URL (cta_external_url)	External link (https://...)	No	Alternative to the internal route; opens an external URL.
Open in new tab (cta_new_tab)	External CTA flag	No	If checked, the external link opens in a new tab.
Start date (start_date)	Validity start	No	Defines when the banner starts appearing. Validated: start cannot be greater than end.
End date (end_date)	Validity end	No	Defines when the banner stops appearing.
Active (is_active)	Enables/disables the banner	No (default on)	An inactive banner is not served to the app regardless of the validity period.
Dismissable (is_dismissable)	Allows the user to close the banner	No	Typically for ONBOARDING; the dismiss is remembered in the user's localStorage.
Tenant (tenant_id)	Restricts the banner to a tenant	No	Optional; used in multi-tenant environments to segment display.
Background color (background_color)	Background color (e.g.: #1f2937)	No	Visual customization of the banner.
Text color (text_color)	Text color (e.g.: #ffffff)	No	Visual customization.
Legacy group (legacy_group)	Compatibility with the old system (bankingBanners, eniatoBanners, midasWebBanners, crowdfundingBanners, digitalBankingBanners, exchangeBanners, …)	No	Makes the compatibility layer also serve this banner via the legacy getters for that target screen. Leave empty for banners exclusive to the new home.

Actions and modals

• Add / Edit: opens the BannerFormDialog. On save, validates (name and type required; start ≤ end) and calls create or update. On error, displays the backend message.
• Status toggle: switches is_active directly in the table (update with the inverted payload).
• Delete: asks for confirmation (Delete banner "<name>"?) and removes via delete.
• Metrics: opens a summary with total clicks and date of last click (metrics). Tracking records clicks only (no impressions).
• Image upload: client-side file selection; rejects files larger than 5 MB; on completion, stores the URL in the corresponding field.
• Step-up / MFA: no re-authentication by default on this screen.

Business rules / caveats

Attention

• Image (PROMOTIONAL): limit of 5 MB per file; the banner stores only the URL (S3/MinIO), not the binary. Provide both the main image and the responsive image for proper display on mobile.
• Validity: start_date cannot be greater than end_date (blocked at validation). An inactive banner (is_active = false) does not appear even within the validity period.
• Icon only makes sense for CONTEXTUAL/ONBOARDING; for PROMOTIONAL the field does not even appear. Conversely, images only appear for PROMOTIONAL.
• CTA: if you fill in both an internal route and an external URL, prioritize one clear destination; "open in new tab" only applies to the external link.
• Legacy group changes the scope: filling it in causes the banner to also be delivered via the old system's getters for that target screen. Use intentionally.
• Metrics: only clicks are tracked; there is no impression count.

• Deletion is permanent: removing the banner deletes the record; prefer deactivating (toggle) if you only want to remove it from display while keeping the history.

Examples

Scenario 1 — Promotional campaign with carousel and internal CTA

1. Add → Type PROMOTIONAL.
2. Name: campanha-cartao-junho; Order: 1.
3. Upload the main image (≤ 5 MB) and the responsive image.
4. CTA: label Get my card, internal route /wallet.
5. Validity: start today, end on the last day of the month; Active checked.
6. Save. The banner appears at the top of the home carousel (order 1) while within the validity period. CTA clicks are recorded in Metrics.

Scenario 2 — Contextual notice (icon alert)

1. Add → Type CONTEXTUAL.
2. Name: aviso-manutencao; Icon: warning.
3. Title: Scheduled maintenance; Subtitle: Saturday, from 2am to 5am, some services will be unavailable.
4. Optional colors: background #1f2937, text #ffffff.
5. Short validity (only the notice days); Active.
6. Save. The app displays an alert with the warning icon; the admin writes the text (there is no automatic condition — it is a manual display during the validity period).

Scenario 3 — Dismissable onboarding card

1. Add → Type ONBOARDING.
2. Name: onboarding-kyc; Icon: verified.
3. Title: Complete your verification; CTA internal route /account/kyc.
4. Check Dismissable so the user can close the card (the dismiss is stored in their localStorage).
5. Save. New users see the card until they complete the action or dismiss it.

Scenario 4 — Reuse in the legacy system (legacy group)

For a banner to also appear where the app still reads from the old system (e.g.: the banking screen), set the Legacy group to bankingBanners (or crowdfundingBanners, exchangeBanners, etc.). The compatibility layer then serves this banner via the legacy getter for that group, in the old format { name, url, link }. Leave empty when the banner is exclusive to the new home.

Related screens

• Email sending
• Bulk action (overview)