wiseBanner is a high-performance, lightweight Shopify App that adds fully customizable announcement bars to the top or bottom of any Shopify online store. Built using Online Store 2.0 Theme App Extensions, it requires zero theme code modifications and has zero impact on storefront page load speeds.
🚀 Key Features
- 📍 Flexible Positioning: Top of page or sticky floating bottom footer bar.
- 📌 Sticky & Non-Sticky Modes: Choose to keep the bar fixed during scroll or allow it to scroll naturally.
- 🎯 Call-to-Action (CTA) Buttons & Links: Add action buttons or make the entire bar clickable.
- 💾 Smart Dismissal Memory: Let shoppers close the bar with an accessible
(×)button that remembers their choice per session/visitor. - 🎨 Full Color & Layout Control: Native live controls in Shopify’s Theme Customizer (background gradients, text color, font sizing, padding).
- ⚡ Built for Performance: Pure Vanilla JS (< 8 KB payload), 100% WCAG 2.1 AA accessible, zero external font dependencies.
- 🛡️ 100% Theme Safe: Uninstalls cleanly without leaving orphan script tags or broken Liquid templates behind.
🛠️ Technology Stack
| Layer | Technologies & Tools |
|---|---|
| Storefront Extension | Liquid, Vanilla CSS, Vanilla JavaScript (ES6+), Theme App Extensions (OS 2.0) |
| Embedded Admin UI | HTML5, Shopify Polaris Design Tokens, Shopify App Bridge v3 JS |
| Backend API | Java 17, Spring Boot 3.x, Spring Security, Maven |
| Database | PostgreSQL |
| Authentication | HMAC-SHA256 JWT Session Tokens (shopify.idToken()) |
| Deployment & Host | Docker (Multi-stage Alpine JRE), Dokploy VPS (https://banner.alap.pro) |
| CLI & Tools | Shopify CLI v3/v4, Git |
📁 Repository Structure
Copied!announcement-banner/ ├── backend/ # Spring Boot 3.x Backend Application │ ├── src/main/java/com/wisebanner/ │ │ ├── config/ # Database, Security, & CSP Filters │ │ │ ├── DatabaseConfig.java # JDBC URL Normalizer for Dokploy Postgres │ │ │ ├── SessionTokenFilter.java # HMAC JWT App Bridge Auth Filter │ │ │ └── ShopifyCspFilter.java # Admin iframe Content Security Policy │ │ ├── controller/ # REST APIs & Mandatory GDPR Webhooks │ │ │ ├── WebhookController.java # Customer & Shop Redact Webhooks │ │ │ └── AppController.java # Auth & Config Endpoints │ │ └── model/ # Entity Models & Data Repositories │ └── src/main/resources/ │ ├── application.yml # App Configuration │ └── static/ │ ├── index.html # Embedded Admin Home (Polaris UI) │ ├── privacy.html # Public Privacy Policy │ └── terms.html # Public Terms of Service ├── extensions/ │ └── announcement-banner-ext/ # Theme App Extension (Online Store 2.0) │ ├── blocks/ │ │ └── announcement-banner.liquid # Block schema & Liquid template │ ├── assets/ │ │ ├── announcement-banner.css # Scoped storefront styles │ │ └── announcement-banner.js # Dismiss logic & local memory │ └── locales/ # Multi-language translation files ├── docs/ # Developer Guides & Review Material │ ├── app_store_listing.md # Official Listing Copy & Metadata │ ├── app-store-requirements.md # AI Self-Review Requirements │ ├── development_rules.md # Shopify Compliance & Quality Rules │ ├── testing_guide.md # Testing Instructions & Scenarios │ └── dokploy_deployment_guide.md # VPS Deployment Manual ├── Dockerfile # Multi-stage Docker build config ├── shopify.app.toml # Shopify App Configuration Manifest └── README.md # Master Documentation (this file)
🔒 Security & Compliance
1. App Bridge Session Token Authentication
All embedded Admin requests pass through SessionTokenFilter.java. The backend retrieves the Authorization: Bearer <token> header, verifies the signed JWT against the app’s secret key (SHOPIFY_API_SECRET), and validates timestamps to prevent replay attacks.
2. Mandatory GDPR & Compliance Webhooks
Three mandatory GDPR endpoints are exposed and verified using HMAC signature matching (X-Shopify-Hmac-Sha256):
POST /api/webhooks/customers/data_requestPOST /api/webhooks/customers/redactPOST /api/webhooks/shop/redact
3. Content Security Policy (CSP)
Embedded inside the Shopify Admin via iframe, ShopifyCspFilter.java sets appropriate security headers (frame-ancestors https://*.myshopify.com https://admin.shopify.com).
🎨 Polaris UI & Built for Shopify Compliance
The embedded Admin Home (index.html) complies with Shopify’s Built for Shopify UI standards:
- Native Polaris color CSS tokens (
--p-color-bg-surface,--p-color-brand, etc.) - Official App Bridge v3 script (
https://cdn.shopify.com/shopifycloud/app-bridge.js) - Deep-linking button into Shopify Theme Customizer (
/admin/themes/current/editor?context=apps) - Fast initial page load (< 100ms) with zero heavy framework bloat
💻 Local Development Setup
Prerequisites
- Java 17 JDK or later
- Maven 3.8+
-
Node.js 18+ &
npm -
Shopify CLI (
npm install -g @shopify/cli) - A Shopify Partner account & Development Store
Steps
1. Clone Repository:
Copied!git clone https://github.com/mehadi13/announcement-banner.git cd announcement-banner
2. Run Backend Application:
Copied!cd backend mvn spring-boot:run
3. Run Shopify CLI Preview:
Copied!# From root directory shopify app dev
4. Test App Embed:
Open the generated dev URL or go to your Dev Store → Online Store → Themes → Customize → App Embeds and toggle wiseBanner to ON.
🚢 Production Deployment (Dokploy VPS)
The app is deployed to VPS via Dokploy at https://banner.alap.pro:
-
Docker Container: Built using multi-stage
Dockerfile(eclipse-temurin:17-jre-alpine). -
Database: Postgres database provisioned on Dokploy;
DatabaseConfig.javaautomatically normalizespostgres://connection URLs to JDBC format. - SSL Certificate: Managed automatically via Dokploy Traefik reverse proxy.
📝 License & Contact
- Developer: Wisemattic
-
Support Contact:
wisemattic@gmail.com