Strategia SEO e Indicizzazione per la PWA dei Canti

Questo documento definisce la strategia tecnica per consentire l'indicizzazione dei testi dei canti da parte dei motori di ricerca (in particolare Googlebot) e la corretta generazione delle anteprime (social cards) su piattaforme di messaggistica e social media (WhatsApp, Telegram, Facebook, ecc.), mantenendo intatta l'architettura PWA (Progressive Web App) offline-ready.

1. Il Contesto Tecnologico

L'applicazione è sviluppata con:

Angular 20 (Framework Core)
Ionic 8 (UI & Routing integration)
Angular Service Worker (@angular/service-worker) per le funzionalità offline della PWA.

2. La Strategia Selezionata: Prerendering / Static Site Generation (SSG)

Dato che i testi dei canti sono dati statici (non cambiano in base all'utente connesso e variano molto raramente), la soluzione ottimale è la Static Site Generation (SSG), nota anche come Prerendering.

Come Funziona la Sinergia SSG + PWA

Fase di Build: Durante la compilazione dell'app (ng build), Angular genera un file index.html statico e pre-renderizzato per ogni singolo canto (es. /canti/tu-sei-sorgente/index.html).
Scansione dello Spider (SEO): Quando Googlebot o i crawler dei social richiedono l'URL di un canto, il server o la CDN distribuiscono immediatamente il file HTML statico già popolato con il testo del canto e con i meta tag corretti.
Idratazione e PWA (Client): Quando un utente apre la pagina sul browser, Angular scarica i bundle JavaScript ed esegue l'hydration in background. L'applicazione "prende vita" come Single Page Application (SPA), attiva il Service Worker e abilita la navigazione offline e l'installabilità come PWA.

3. Fasi e Dettagli di Implementazione

Fase 1: Struttura degli URL e Routing Semantico

Per facilitare la SEO, gli URL devono essere parlanti e privi di simboli di hash (#). Attualmente, l'applicazione utilizza già il routing basato su percorsi standard (PathLocationStrategy) in app-routing.module.ts.

È necessario definire una rotta dedicata per i singoli canti che accetti un parametro semantico (detto slug o alias), ad esempio:

// src/app/app-routing.module.ts
const routes: Routes = [
  // ... altre rotte
  {
    path: 'canti/:slug',
    loadChildren: () => import('./pages/canto-detail/canto-detail.module').then(m => m.CantoDetailPageModule)
  }
];

I collegamenti all'interno dell'applicazione per navigare verso i canti devono utilizzare il tag semantico <a> con la direttiva routerLink, per consentire a Googlebot di scoprire autonomamente tutte le pagine:

<!-- EVITARE: pulsanti generici con eventi click gestiti in JS -->
<ion-item (click)="navigaAlCanto(canto.slug)">...</ion-item>

<!-- CONSIGLIATO: vero tag link HTML -->
<a [routerLink]="['/canti', canto.slug]" class="canto-link">
  <ion-label>{{ canto.titolo }}</ion-label>
</a>

Fase 2: Gestione dei Meta Tag Dinamici

Ogni canto deve avere un titolo e una descrizione univoci e ottimizzati per la SEO. In Angular si utilizzano i servizi Title e Meta di @angular/platform-browser per aggiornare i metadati all'inizializzazione del componente:

// src/app/pages/canto-detail/canto-detail.page.ts
import { Component, OnInit } from '@angular/core';
import { ActivatedRoute } from '@angular/router';
import { Title, Meta } from '@angular/platform-browser';
import { CantiService } from '../../services/canti.service';

@Component({
  selector: 'app-canto-detail',
  templateUrl: './canto-detail.page.html',
  styleUrls: ['./canto-detail.page.scss'],
})
export class CantoDetailPage implements OnInit {
  canto: any;

  constructor(
    private route: ActivatedRoute,
    private cantiService: CantiService,
    private titleService: Title,
    private metaService: Meta
  ) {}

  ngOnInit() {
    const slug = this.route.snapshot.paramMap.get('slug');
    if (slug) {
      this.canto = this.cantiService.getCantoBySlug(slug);
      this.updateSEOMetadata();
    }
  }

  updateSEOMetadata() {
    const titoloCompleto = `${this.canto.titolo} - Canti Cristiani`;
    const descrizione = `Testo e accordi del canto "${this.canto.titolo}". ${this.canto.testo.substring(0, 150)}...`;

    // Imposta il titolo della pagina
    this.titleService.setTitle(titoloCompleto);

    // Imposta i meta tag standard per la SEO
    this.metaService.updateTag({ name: 'description', content: descrizione });

    // Imposta i tag OpenGraph per la condivisione sui social (Facebook, WhatsApp, Telegram)
    this.metaService.updateTag({ property: 'og:title', content: titoloCompleto });
    this.metaService.updateTag({ property: 'og:description', content: descrizione });
    this.metaService.updateTag({ property: 'og:type', content: 'article' });
    this.metaService.updateTag({ property: 'og:url', content: `https://canti.cristiani.it/canti/${this.canto.slug}` });
    
    // Se c'è un'immagine associata o una copertina di default
    this.metaService.updateTag({ property: 'og:image', content: 'https://canti.cristiani.it/assets/og-cover.png' });
  }
}

Fase 3: Configurazione del Prerendering (SSG) in Angular 20

In Angular 20, l'abilitazione del server-side rendering e del prerendering statico durante la compilazione avviene aggiungendo il pacchetto SSR ufficiale:

ng add @angular/ssr

Questo comando configura automaticamente l'applicazione modificando angular.json e creando i file necessari per la compilazione lato server.

Configurazione delle rotte da pre-renderizzare

Poiché l'elenco dei canti è dinamico (es. risiede in file JSON o database), dobbiamo indicare ad Angular quali rotte generare staticamente durante il comando ng build.

Si crea un file di configurazione per definire le rotte o si utilizza uno script per estrarle dinamicamente:

Creare un file delle rotte statiche prerender-routes.txt:

/home
/settings
/canti/tu-sei-sorgente
/canti/re-dei-re
/canti/lodi-al-altissimo

Automatizzare la generazione di questo file inserendo uno script (es. generate-routes.js) da eseguire prima della build che legge l'elenco dei canti dal file JSON locale e scrive l'elenco dei percorsi in prerender-routes.txt.

Configurare angular.json per consumare questo file:

"prerender": {
  "discoverRoutes": false,
  "routesFile": "prerender-routes.txt"
}


Al termine della build (`npm run build`), nella cartella di distribuzione (es. `dist/canticristiani/browser`) verranno generate cartelle fisiche con i file `index.html` pronti all'uso per ciascuna rotta definita.

---

### Fase 4: Sitemap.xml e Robots.txt
Per garantire che Googlebot trovi tempestivamente tutti i canti, è fondamentale generare un file `sitemap.xml` da posizionare nella radice del server web.

#### Esempio di `sitemap.xml`:
```xml
<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
  <url>
    <loc>https://canti.cristiani.it/home</loc>
    <changefreq>weekly</changefreq>
    <priority>1.0</priority>
  </url>
  <!-- Generato dinamicamente per ogni canto -->
  <url>
    <loc>https://canti.cristiani.it/canti/tu-sei-sorgente</loc>
    <changefreq>monthly</changefreq>
    <priority>0.8</priority>
  </url>
</urlset>

Esempio di `robots.txt`:

User-agent: *
Allow: /

Sitemap: https://canti.cristiani.it/sitemap.xml

4. Vantaggi e Risultati Attesi

Indicizzazione immediata: Googlebot indicizzerà i testi dei canti all'istante, consentendo agli utenti di trovare la PWA cercando frammenti di testo o il titolo del canto direttamente su Google.
Anteprime nei Social Perfette: La condivisione dei link sui canali di comunicazione mostrerà anteprime ricche (titolo corretto, frammento del testo del canto e logo dell'app).
Integrità PWA: L'utente beneficerà di un caricamento iniziale ultra-veloce (grazie all'HTML pre-renderizzato) seguito dall'installazione offline e dall'esperienza fluida tipica dell'applicazione mobile.

8.0 KiB Raw Blame History