Autenticazione

Introduzione

Nylo Website v7 fornisce un sistema di autenticazione completo attraverso la classe Auth. Gestisce lo storage sicuro delle credenziali utente, la gestione delle sessioni e supporta sessioni nominate multiple per diversi contesti di autenticazione.

I dati di autenticazione vengono memorizzati in modo sicuro e sincronizzati con Backpack (un archivio chiave-valore in memoria) per un accesso sincrono rapido in tutta la tua app.

import 'package:nylo_framework/nylo_framework.dart';

// Authenticate a user
await Auth.authenticate(data: {"token": "abc123", "userId": 1});

// Check if authenticated
bool loggedIn = await Auth.isAuthenticated(); // true

// Get auth data
dynamic token = Auth.data(field: 'token'); // "abc123"

// Logout
await Auth.logout();

Autenticazione degli Utenti

Usa Auth.authenticate() per memorizzare i dati della sessione utente:

// With a Map
await Auth.authenticate(data: {
  "token": "ey2sdm...",
  "userId": 123,
  "email": "user@example.com",
});

// With a Model class
User user = User(id: 123, email: "user@example.com", token: "ey2sdm...");
await Auth.authenticate(data: user);

// Without data (stores a timestamp)
await Auth.authenticate();

Esempio Reale

class _LoginPageState extends NyPage<LoginPage> {

  Future<void> handleLogin(String email, String password) async {
    // 1. Call your API to authenticate
    User? user = await api<AuthApiService>((request) => request.login(
      email: email,
      password: password,
    ));

    if (user == null) {
      showToastDanger(description: "Invalid credentials");
      return;
    }

    // 2. Store the authenticated user
    await Auth.authenticate(data: user);

    // 3. Navigate to home
    routeTo(HomePage.path, removeUntil: (_) => false);
  }
}

Recupero dei Dati di Autenticazione

Ottieni i dati di autenticazione memorizzati utilizzando Auth.data():

// Get all auth data
dynamic userData = Auth.data();
print(userData); // {"token": "ey2sdm...", "userId": 123}

// Get a specific field
String? token = Auth.data(field: 'token');
int? userId = Auth.data(field: 'userId');

Il metodo Auth.data() legge dal Backpack (l'archivio chiave-valore in memoria di Nylo Website) per un accesso sincrono rapido. I dati vengono sincronizzati automaticamente nel Backpack quando effettui l'autenticazione.

Aggiornamento dei Dati di Autenticazione

Nylo Website v7 introduce Auth.set() per aggiornare i dati di autenticazione:

// Update a specific field
await Auth.set((data) {
  data['token'] = 'new_token_value';
  return data;
});

// Add new fields
await Auth.set((data) {
  data['refreshToken'] = 'refresh_abc123';
  data['lastLogin'] = DateTime.now().toIso8601String();
  return data;
});

// Replace entire data
await Auth.set((data) => {
  'token': newToken,
  'userId': userId,
});

Logout

Rimuovi l'utente autenticato con Auth.logout():

Future<void> handleLogout() async {
  await Auth.logout();

  // Navigate to login page
  routeTo(LoginPage.path, removeUntil: (_) => false);
}

Logout da Tutte le Sessioni

Quando utilizzi sessioni multiple, cancellale tutte:

// Logout from default and all named sessions
await Auth.logoutAll(sessions: ['device', 'admin']);

Verifica dell'Autenticazione

Verifica se un utente e' attualmente autenticato:

bool isLoggedIn = await Auth.isAuthenticated();

if (isLoggedIn) {
  // User is authenticated
  routeTo(HomePage.path);
} else {
  // User needs to login
  routeTo(LoginPage.path);
}

Sessioni Multiple

Nylo Website v7 supporta sessioni di autenticazione nominate multiple per diversi contesti. Questo e' utile quando devi tracciare diversi tipi di autenticazione separatamente (es., login utente vs registrazione dispositivo vs accesso admin).

// Default user session
await Auth.authenticate(data: user);

// Device authentication session
await Auth.authenticate(
  data: {"deviceToken": "abc123"},
  session: 'device',
);

// Admin session
await Auth.authenticate(
  data: adminUser,
  session: 'admin',
);

Lettura da Sessioni Nominate

// Default session
dynamic userData = Auth.data();
String? userToken = Auth.data(field: 'token');

// Device session
dynamic deviceData = Auth.data(session: 'device');
String? deviceToken = Auth.data(field: 'deviceToken', session: 'device');

// Admin session
dynamic adminData = Auth.data(session: 'admin');

Logout Specifico per Sessione

// Logout from default session only
await Auth.logout();

// Logout from device session only
await Auth.logout(session: 'device');

// Logout from all sessions
await Auth.logoutAll(sessions: ['device', 'admin']);

Verifica Autenticazione per Sessione

bool userLoggedIn = await Auth.isAuthenticated();
bool deviceRegistered = await Auth.isAuthenticated(session: 'device');
bool isAdmin = await Auth.isAuthenticated(session: 'admin');

ID Dispositivo

Nylo Website v7 fornisce un identificativo univoco del dispositivo che persiste tra le sessioni dell'app:

String deviceId = await Auth.deviceId();
// Example: "550e8400-e29b-41d4-a716-446655440000-1704067200000"

L'ID dispositivo:

• Viene generato una volta e memorizzato permanentemente
• E' univoco per ogni dispositivo/installazione
• E' utile per la registrazione del dispositivo, analytics o notifiche push

// Example: Register device with backend
Future<void> registerDevice() async {
  String deviceId = await Auth.deviceId();
  String? pushToken = await FirebaseMessaging.instance.getToken();

  await api<DeviceApiService>((request) => request.register(
    deviceId: deviceId,
    pushToken: pushToken,
  ));

  // Store device auth
  await Auth.authenticate(
    data: {"deviceId": deviceId, "pushToken": pushToken},
    session: 'device',
  );
}

Sincronizzazione con Backpack

I dati di autenticazione vengono sincronizzati automaticamente nel Backpack quando effettui l'autenticazione. Per sincronizzare manualmente (es. all'avvio dell'app):

// Sync default session
await Auth.syncToBackpack();

// Sync specific session
await Auth.syncToBackpack(session: 'device');

// Sync all sessions
await Auth.syncAllToBackpack(sessions: ['device', 'admin']);

Questo e' utile nella sequenza di avvio della tua app per assicurare che i dati di autenticazione siano disponibili nel Backpack per un accesso sincrono rapido.

Rotta Iniziale

La rotta iniziale e' la prima pagina che gli utenti vedono quando aprono la tua app. Impostala utilizzando .initialRoute() nel tuo router:

// routes/router.dart
appRouter() => nyRoutes((router) {
  router.add(LoginPage.path).initialRoute();

  router.add(HomePage.path);
});

Puoi anche impostare una rotta iniziale condizionale utilizzando il parametro when:

appRouter() => nyRoutes((router) {
  router.add(OnboardingPage.path).initialRoute(
    when: () => !hasCompletedOnboarding()
  );

  router.add(HomePage.path).initialRoute(
    when: () => hasCompletedOnboarding()
  );
});

Naviga alla rotta iniziale da qualsiasi punto utilizzando routeToInitial():

void _goHome() {
  routeToInitial();
}

Rotta Autenticata

La rotta autenticata sovrascrive la rotta iniziale quando un utente e' autenticato. Impostala utilizzando .authenticatedRoute():

appRouter() => nyRoutes((router) {
  router.add(LoginPage.path).initialRoute();

  router.add(HomePage.path).authenticatedRoute();

  router.add(ProfilePage.path);
  router.add(SettingsPage.path);
});

Quando l'app si avvia:

• Auth.isAuthenticated() restituisce true → l'utente vede la rotta autenticata (HomePage)
• Auth.isAuthenticated() restituisce false → l'utente vede la rotta iniziale (LoginPage)

Puoi anche impostare una rotta autenticata condizionale:

router.add(HomePage.path).authenticatedRoute(
  when: () => hasCompletedSetup()
);

Naviga alla rotta autenticata programmaticamente utilizzando routeToAuthenticatedRoute():

// After login
await Auth.authenticate(data: user);
routeToAuthenticatedRoute();

Vedi anche: Router per la documentazione completa sul routing, inclusi guard e deep linking.

Rotta di Anteprima

Durante lo sviluppo, potresti voler visualizzare rapidamente una pagina specifica senza cambiare la tua rotta iniziale o autenticata. Usa .previewRoute():

appRouter() => nyRoutes((router) {
  router.add(LoginPage.path).initialRoute();

  router.add(HomePage.path).authenticatedRoute();

  router.add(SettingsPage.path).previewRoute(); // Opens first during development
});

previewRoute() sovrascrive sia initialRoute() che authenticatedRoute(), rendendo la rotta specificata la prima pagina mostrata indipendentemente dallo stato di autenticazione.

Attenzione: Rimuovi .previewRoute() prima di rilasciare la tua app.

Rotta Sconosciuta

Definisci una pagina di fallback per quando un utente naviga verso una rotta che non esiste. Impostala utilizzando .unknownRoute():

appRouter() => nyRoutes((router) {
  router.add(HomePage.path).initialRoute();

  router.add(NotFoundPage.path).unknownRoute();
});

Tutto Insieme

Ecco una configurazione completa del router con tutti i tipi di rotta:

appRouter() => nyRoutes((router) {
  // First page for unauthenticated users
  router.add(LoginPage.path).initialRoute();

  // First page for authenticated users
  router.add(HomePage.path).authenticatedRoute();

  // 404 page
  router.add(NotFoundPage.path).unknownRoute();

  // Regular routes
  router.add(ProfilePage.path);
  router.add(SettingsPage.path);
});

Funzioni Helper

Nylo Website v7 fornisce funzioni helper che rispecchiano i metodi della classe Auth:

Tutti gli helper accettano gli stessi parametri delle loro controparti nella classe Auth, incluso il parametro opzionale session:

// Authenticate with a named session
await authAuthenticate(data: device, session: 'device');

// Read from a named session
dynamic deviceData = authData(session: 'device');

// Check a named session
bool deviceAuth = await authIsAuthenticated(session: 'device');