docs: aggiunta piani strategici e di test in markdown
This commit is contained in:
David Frassi
@@ -0,0 +1,184 @@
|
||||
# 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
|
||||
1. **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`).
|
||||
2. **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.
|
||||
3. **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](file:///Users/davidfrassi/SRC/agenti/canti/src/app/app-routing.module.ts).
|
||||
|
||||
È necessario definire una rotta dedicata per i singoli canti che accetti un parametro semantico (detto *slug* o *alias*), ad esempio:
|
||||
|
||||
```typescript
|
||||
// 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:
|
||||
|
||||
```html
|
||||
<!-- 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:
|
||||
|
||||
```typescript
|
||||
// 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:
|
||||
|
||||
```bash
|
||||
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:
|
||||
|
||||
1. **Creare un file delle rotte statiche** `prerender-routes.txt`:
|
||||
```txt
|
||||
/home
|
||||
/settings
|
||||
/canti/tu-sei-sorgente
|
||||
/canti/re-dei-re
|
||||
/canti/lodi-al-altissimo
|
||||
```
|
||||
2. **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`.
|
||||
3. **Configurare `angular.json`** per consumare questo file:
|
||||
```json
|
||||
"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`:
|
||||
```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.
|
||||
Reference in New Issue
Block a user