📱 ShopApp — Documentazione

App mobile white-label per PrestaShop 8. Flutter + OneSignal + Riverpod. Personalizzabile per qualsiasi negozio in 5 minuti.

ShopApp è un'applicazione mobile completa per iOS e Android che si connette a qualsiasi negozio PrestaShop 8 tramite Admin API OAuth2. Include un modulo PHP che estende PrestaShop con autenticazione cliente, gestione ordini e notifiche push OneSignal.

Funzionalità incluse

• 🛍️ Catalogo prodotti — browse per categoria, ricerca, filtri, immagini ottimizzate
• 🔐 Autenticazione cliente — login e registrazione con le stesse credenziali del sito
• 🛒 Carrello — gestione locale con sync al checkout, swipe-to-delete
• 📦 Ordini — lista ordini con timeline animata, dettaglio completo
• 🔔 Notifiche push — OneSignal per ordini e promozioni
• 🎨 White-label — colori, nome e URL configurabili via JSON
• ⚡ Performance nativa — Flutter compila in codice nativo ARM

✅ Requisiti

Ambiente di sviluppo

Backend PrestaShop

Account necessari

• OneSignal — gratuito su onesignal.com
• Google Play Console — 25$ una tantum, per pubblicare su Android
• Apple Developer Program — 99$/anno, per pubblicare su iOS

📁 Struttura del progetto

⚙️ Installazione Flutter

# macOS / Linux
cd ~/Progetti/shopapp

# Windows
cd C:\Progetti\shopapp

flutter pub get

flutter doctor -v

dart run scripts/configure.dart

dart run flutter_launcher_icons

flutter run

🎨 Configurazione white-label

Il branding (nome, logo, colori) si gestisce direttamente dal pannello PrestaShop. L'app si aggiorna al prossimo avvio, senza rebuild.

Come funziona

All'avvio, l'app carica prima i valori di fallback dal file locale app_config.json, poi chiama automaticamente l'endpoint del modulo PrestaShop e sovrascrive nome, logo e colori con i valori aggiornati dal cliente.

Cosa gestisce il cliente (da PrestaShop Admin)

Cosa resta in app_config.json

Solo le credenziali bootstrap e i dati build-time. Tutto il branding lo gestisce il modulo PS.

// assets/config/app_config.json — l'unico file che tocchi per cliente
{
  "app_name":          "Fashion Store",         // nome launcher (script configure)
  "bundle_id":         "com.fashionstore.app",  // bundle ID (script configure)
  "base_url":          "https://fashionstore.it/prestashop",
  "api_client_id":     "app-flutter2026",
  "api_client_secret": "la-tua-secret",
  "onesignal_app_id":  "xxxx-yyyy-zzzz"
}

Endpoint configurazione app

// Esempio risposta
{
  "success": true,
  "config": {
    "store_name": "Fashion Store",
    "store_tagline": "Le migliori offerte di moda",
    "logo_url": "https://negozio.it/img/mobile/app_logo.png",
    "primary_color": "#E91E8C",
    "secondary_color": "#FF6584",
    "currency_symbol": "€",
    "currency_code": "EUR",
    "language_id": 1,
    "products_per_page": 20,
    "show_ratings": true,
    "enable_wishlist": true
  }
}

Dove trovare le credenziali Admin API

🛒 Modulo PrestaShop

Il modulo mobilenotifications estende PrestaShop con API REST per clienti, OneSignal e hook per notifiche automatiche.

Installazione

Hook registrati

Permessi file

# Sul server
chown -R www-data:www-data modules/mobilenotifications/
chmod -R 755 modules/mobilenotifications/

🔔 Setup OneSignal

Creazione dell'app OneSignal

Setup Android (FCM)

Per ricevere notifiche su Android:

Setup iOS (APNs)

🏗️ Architettura app

ShopApp segue un'architettura a layer puliti con Riverpod come state manager.

Layer principali

Flusso di autenticazione

// 1. App avvia e carica token da storage sicuro
StorageService.instance.getCustomerToken()

// 2. Se il token è valido → Home Screen
// 3. Se manca il token → Login Screen

// 4. Login → modulo PS → genera HMAC token
POST /module/mobilenotifications/auth?action=login
{email, password} → {customer, token}

// 5. Token salvato in FlutterSecureStorage
// 6. OneSignal externalUserId = "customer_{id}"

🔌 API Client

Admin API (OAuth2)

Usato per: catalogo prodotti, categorie. Token rinnovato automaticamente prima della scadenza.

// lib/core/network/api_client.dart
final resp = await ApiClient.instance.get(
  '/products',
  params: {'page': 1, 'itemsPerPage': 20},
);

Module Client

Usato per: login cliente, ordini, registrazione token. Invia automaticamente X-Customer-Token.

// Login cliente
final resp = await ModuleClient.instance.post(
  '/auth/login',
  {'email': email, 'password': password},
);

📱 Schermate

🎨 Theming UI

Il tema viene costruito dinamicamente a partire dai colori in app_config.json usando Material Design 3.

// lib/core/theme/app_theme.dart
ThemeData buildTheme() {
  final primary = AppConfig.instance.primaryColor;
  final colorScheme = ColorScheme.fromSeed(
    seedColor: primary,
    secondary: AppConfig.instance.secondaryColor,
  );
  return ThemeData(useMaterial3: true, colorScheme: colorScheme);
}

Per cambiare il tema basta aggiornare primary_color e secondary_color nel JSON e ricompilare.

Font

L'app usa Poppins (Google Fonts) via pubspec.yaml. Per cambiare font: aggiungi i file TTF in assets/fonts/ e aggiorna pubspec.yaml.

🗺️ Navigazione

Usa go_router con ShellRoute per la bottom navigation bar.

Route disponibili

🔗 Endpoint API modulo

Tutti gli endpoint sono accessibili via HTTPS su:

https://tuonegozio.it/module/mobilenotifications/{controller}?action={action}

Autenticazione

OneSignal Token

Ordini

📤 Notifiche push

Automatiche (hook ordine)

Il modulo invia notifiche push automaticamente quando:

• Un nuovo ordine viene creato (actionObjectOrderAddAfter)
• Lo stato di un ordine cambia (actionOrderStatusUpdate)

Non serve nessuna configurazione aggiuntiva: funziona appena il modulo è installato e le chiavi OneSignal sono inserite.

Promozionali (da admin)

Dal pannello PrestaShop → Moduli → Mobile App Notifications:

• Compila titolo e messaggio nella sezione "Invia notifica promozionale"
• Clicca "Invia a tutti"
• La notifica viene consegnata a tutti gli utenti con l'app installata

Payload notifica

// Struttura dati notifica OneSignal
{
  "type": "order_update",  // new_order | order_update | promo
  "order_id": "123",
  "reference": "ORD-2468"
}

🖥️ Pannello admin modulo

Accessibile da Moduli → Mobile App — White Label → Configura. Il pannello è diviso in 4 sezioni:

1 — Configurazione App White-Label

La sezione principale. Tutto ciò che il cliente imposta qui viene inviato all'app al prossimo avvio, senza rebuild.

2 — Configurazione OneSignal

OneSignal App ID e REST API Key per abilitare le notifiche push.

3 — Invia notifica promozionale

Invio diretto a tutti gli utenti con l'app installata. Titolo + messaggio liberi.

4 — Statistiche

Contatori in tempo reale: utenti con notifiche attive, notifiche inviate, notifiche fallite.

🆔 Bundle ID / Package Name

Il Bundle ID (iOS) e il Package Name (Android) sono l'identità unica della tua app nel mondo. Va scelto e impostato prima di qualsiasi altra operazione di deploy.

Cos'è e perché è critico

È una stringa in formato reverse-domain che identifica la tua app in modo univoco su tutti i sistemi. Non può essere cambiata dopo la pubblicazione senza perdere l'app sullo store. Viene usata da:

Un file solo — uno script solo

Non serve toccare AndroidManifest, build.gradle, Info.plist e project.pbxproj separatamente. Imposti due campi in app_config.json e lanci un unico comando:

# 1. Modifica assets/config/app_config.json
{
  "app_name":  "Fashion Store",
  "bundle_id": "com.fashionstore.app",
  ...
}

# 2. Lancia lo script — patcha i 4 file e scarica l'icona
dart run scripts/configure.dart

# Output
  → App name : Fashion Store
  → Bundle ID: com.fashionstore.app
  → Recupero logo da: https://fashionstore.it/.../config

  ✓ assets/images/launcher_icon.png (42 KB)

  ✓ android/app/src/main/AndroidManifest.xml → android:label
  ✓ android/app/build.gradle.kts → applicationId
  ✓ android/app/build.gradle.kts → namespace
  ✓ ios/Runner/Info.plist → CFBundleDisplayName
  ✓ ios/Runner/Info.plist → CFBundleName
  ✓ ios/Runner.xcodeproj/project.pbxproj → PRODUCT_BUNDLE_IDENTIFIER (3 occorrenze)

  ✅ Configurazione completata!

# 3. Genera tutte le risoluzioni icona da launcher_icon.png
dart run flutter_launcher_icons

Lo script si trova in scripts/configure.dart ed è già incluso nel progetto. Non ha dipendenze esterne — usa solo il Dart SDK già installato con Flutter.

Come sceglierlo

La convenzione è com.nomeditta.nomenegozio. Usa solo lettere minuscole, numeri e punti. Esempi:

# Formato consigliato
com.acmesrl.fashionstore
it.miodominio.shopapp
com.clientenome.appnome

File patchati dallo script

Ordine operativo corretto

🤖 Build Android

Prerequisiti

• Android Studio installato con SDK
• File android/app/google-services.json da Firebase Console
• Account Google Play Console (25$ una tantum)

Build APK debug (test)

flutter build apk --debug

Sequenza completa per un nuovo cliente

# 1. Configura nome, bundle ID, scarica icona
dart run scripts/configure.dart

# 2. Genera tutte le risoluzioni icona
dart run flutter_launcher_icons

# 3. Genera keystore (una volta sola per cliente)
keytool -genkey -v -keystore ~/nomeapp.jks \
  -keyalg RSA -keysize 2048 -validity 10000 \
  -alias nomeapp

# 4. Aggiungi in android/key.properties
storePassword=TUA_PASSWORD
keyPassword=TUA_PASSWORD
keyAlias=nomeapp
storeFile=/percorso/nomeapp.jks

# 5. Build finale
flutter build appbundle --release

🍎 Build iOS

Prerequisiti

• macOS con Xcode ≥ 15.0
• CocoaPods: sudo gem install cocoapods
• Account Apple Developer con App ID registrato

Setup

# Installa pod
cd ios && pod install && cd ..

# Apri in Xcode
open ios/Runner.xcworkspace

In Xcode

• Verifica che il Bundle Identifier corrisponda a quello registrato su Apple Developer
• Seleziona il tuo Team (Apple Developer)
• Aggiungi capability Push Notifications
• Aggiungi Background Modes → Remote Notifications

Sequenza completa per un nuovo cliente

# 1. Configura nome, bundle ID, scarica icona
dart run scripts/configure.dart

# 2. Genera tutte le risoluzioni icona
dart run flutter_launcher_icons

# 3. Installa pod e apri Xcode
cd ios && pod install && cd ..
open ios/Runner.xcworkspace

# 4. In Xcode: seleziona Team, verifica Bundle ID, aggiungi Push Notifications

# 5. Build finale
flutter build ipa --release

Da Xcode: Product → Archive e carica su App Store Connect.

🔄 Aggiungere un nuovo cliente

Checklist completa dal primo contatto alla pubblicazione sugli store.

dart run scripts/configure.dart
dart run flutter_launcher_icons
flutter build appbundle --release  # Android
flutter build ipa --release         # iOS

📋 Config reference

app_config.json — campi build-time

Questi 6 campi si trovano in assets/config/app_config.json. Vengono letti una volta sola all'avvio dell'app e non vengono mai sovrascritti dal server. Modificarli richiede un rebuild e una nuova pubblicazione sugli store.

Modulo PrestaShop — campi runtime

Questi campi vengono gestiti dal pannello admin del modulo Mobile Notifications e restituiti dall'endpoint pubblico GET /module/mobilenotifications/config. L'app li legge ad ogni avvio: nessun rebuild necessario.

🔧 Troubleshooting

Errore 401 al login cliente

Admin API restituisce 401

Le credenziali api_client_id / api_client_secret nel JSON non corrispondono a quelle in PrestaShop. Ricrea il client API e aggiorna il JSON.

Notifiche push non arrivano

• Verifica che OneSignal App ID e REST Key siano corretti nel modulo PS
• Controlla che il player ID sia stato registrato (vedi tabella mobile_tokens)
• Su iOS verifica che Push Notification capability sia abilitata in Xcode
• Testa l'invio direttamente dalla dashboard OneSignal

Immagini prodotti non caricate

Se le immagini non si vedono, verifica che l'URL costruito sia corretto. Il percorso delle immagini PS8 è: {base_url}/img/p/{n1}/{n2}/{id}.jpg dove le sottocartelle corrispondono alle cifre dell'ID immagine.

configure.dart: "File non trovato, saltato: android/..."

Le cartelle android/ e ios/ non contengono ancora i file di piattaforma. Succede solo se si parte da una copia del progetto con le directory vuote. Soluzione: rigenera i file con:

flutter create . --org com.tuaorg --project-name nome_progetto

Il comando preserva lib/, assets/ e pubspec.yaml. Poi rilancia dart run scripts/configure.dart.

Errore durante flutter pub get

# Pulisci e reinstalla
flutter clean
flutter pub get

❓ FAQ

Posso aggiungere un modulo di pagamento nell'app?

Sì, il modulo orders.php accetta il nome del modulo di pagamento nel campo payment. Puoi integrare Stripe, PayPal, o qualsiasi gateway PS estendendo il controller orders.php.

Come aggiorno l'app dopo modifiche al negozio?

Dipende da cosa cambi:

• Prodotti, categorie, prezzi — l'app li vede in tempo reale, nessun aggiornamento necessario.
• Nome negozio, logo, colori, valuta — si aggiornano dal pannello PS senza rebuild. L'app carica i nuovi valori al prossimo avvio.
• Icona launcher — riesegui dart run scripts/configure.dart + dart run flutter_launcher_icons + rebuild + pubblica un nuovo aggiornamento sugli store.
• Credenziali API / OneSignal / Bundle ID — modifica app_config.json, ricompila e pubblica un aggiornamento.

L'app supporta più lingue?

Attualmente la UI è in italiano. Puoi aggiungere l18n con il pacchetto flutter_localizations e definire le traduzioni in file ARB.

Come gestire la cache delle immagini?

L'app usa cached_network_image che gestisce automaticamente la cache locale. La durata di default è fino a 7 giorni. Modificabile via CacheManager custom.

Posso usare il codice per altri CMS oltre a PrestaShop?

Sì. L'architettura separa nettamente l'API layer dalla UI. Sostituendo api_client.dart e i modelli Product/Order puoi connettere qualsiasi backend REST.