AI MediaBoost: migra alle Content Delivery API senza perdere valore SEO – THRON Guide

Se distribuisci i tuoi Digital Asset con le vecchie API public, stai lasciando sul tavolo velocità, qualità e formati moderni. Le Content Delivery API di AI MediaBoost sono lo standard attuale di erogazione, e il meccanismo di redirect automatico ti permette di migrare conservando il posizionamento organico che hai costruito sui link esistenti.

Questa guida ti spiega cosa cambia negli URL, come convertire i link che hai già pubblicato e in che ordine eseguire i passaggi per non penalizzare i tuoi canali durante la transizione.

Public API e Content Delivery API: cosa cambia nell'URL

Le due API erogano gli stessi asset con strutture di URL diverse. Le vecchie API portano tutte le opzioni di resa nel percorso, le nuove le espongono come parametri di query.

URL legacy di un'immagine:

https://<clientId>-cdn.thron.com/delivery/public/image/<clientId>/<id>/<pkey>/<preset>/<divArea>/<prettyName>

URL con le Content Delivery API:

https://<clientId>-cdn.thron.com/api/v1/content-delivery/shares/<pkey>/contents/<id>/image/<dynamicSeoSuffix>

Tre differenze strutturali da tenere presenti prima di iniziare la conversione:

La pKey passa dal fondo del percorso al segmento shares/, subito dopo la radice dell'API.
Il formato di delivery non si specifica più: THRON eroga sempre il formato migliore per il browser che effettua la richiesta.
Il segmento che segue contents/<id> dichiara il tipo di risorsa che vuoi ottenere: image, video/source, pdf, audio/source, pagelet, thumbnail oppure original.

Perché migrare: performance, qualità, sicurezza e formati

Il passaggio alle nuove API non è un cambio di facciata. Le Content Delivery API sono tecnicamente superiori su quattro fronti:

Performance: erogazione più veloce e adeguata al browser che effettua la richiesta.
Qualità: gestione ottimizzata degli asset, con qualità superiore a parità di peso del file.
Sicurezza: meccanismi di delivery più sicuri.
Formati: supporto a tutti i nuovi formati, che le API legacy non gestiscono.

Questi quattro vantaggi da soli giustificano la migrazione. Se temi che cambiare gli URL ti faccia perdere il ranking che hai costruito nel tempo, THRON mette a disposizione un meccanismo dedicato per trasferire il Link Equity dai vecchi link THRON ai nuovi.

Link Juice: cos'è e perché non lo perdi migrando

Il Link Juice, o Link Equity, è il valore di autorevolezza che un link trasferisce da una pagina all'altra. Quando un utente clicca su un'immagine o su un link e viene reindirizzato a un sito, i motori di ricerca riconoscono quel link come prezioso: più interazioni riceve nel tempo, più ranking acquisisce, e più in alto compare nei risultati di ricerca.

Un esempio concreto: un utente cerca un prodotto su Google Immagini, clicca sulla foto che hai pubblicato e arriva sul tuo sito. Ripetuta nel tempo, questa interazione aumenta il ranking di quello specifico link.

Il meccanismo di redirect automatico trasferisce alle nuove URL il Link Juice accumulato dalle vecchie, senza perdita di ranking. Non è un passaggio obbligatorio della migrazione: richiedilo se il posizionamento organico dei tuoi link è un patrimonio che vuoi conservare.

Redirect automatico: come funziona e quando attivarlo

Il meccanismo di reindirizzamento automatico collega i vecchi URL pubblici alla nuova Content Delivery API. I crawler riconoscono i nuovi URL come equivalenti ai vecchi, trasferiscono la fiducia accumulata e mantengono il ranking.

Tre condizioni determinano il risultato:

Stessa pKey: il redirect funziona solo se continui a usare la stessa pKey nella nuova API. Non è possibile reindirizzare una vecchia pKey verso più pKey diverse. Se hai bisogno di cambiare pKey, parlane con il tuo account di riferimento THRON prima di avviare la migrazione.
Rimappatura automatica dei parametri: la corrispondenza tra vecchi e nuovi parametri è gestita automaticamente dal meccanismo di redirect.

Attenzione: il redirect va attivato mentre i vecchi link sono ancora in uso, quei link subiranno rallentamenti dovuti al passaggio attraverso il reindirizzamento.

Quali link THRON può coprire e quali no

Il meccanismo di trasferimento agisce sui link erogati dal dominio THRON: è lì che THRON può collegare vecchio e nuovo URL e trasferire il ranking accumulato.

Se oggi distribuisci i tuoi asset da un'altra piattaforma, quei link non sono sotto il controllo di THRON e il trasferimento non può partire da qui. In quel caso il reindirizzamento va impostato da chi governa quei domini oggi, cioè il tuo fornitore attuale.

Chi fa cosa nella migrazione

Attività	Responsabile
Mappatura delle pkey che si vogliono migrare e individuazione delle url coinvolte	Tu
Aggiornamento dei link interni ai canali diretti con le nuove URL	Tu
Attivazione e gestione del meccanismo di redirect automatico tra vecchie e nuove pKey	THRON
Rimappatura automatica dei parametri lato redirect	THRON

In sintesi: la scelta di cosa migrare è a carico tuo o del tuo integratore. Una volta completata, THRON mantiene il collegamento SEO tra vecchio e nuovo tramite il meccanismo di redirect. Poi toccherà di nuovo a te migrare dalle vecchie alle nuove API.
Se hai bisogno di aiuto puoi sempre contattare support@thron.com

Ri-mappatura degli URL: come avviene la conversione dei link esistenti

La conversione dal sistema legacy delivery/public alla nuova api/v1/content-delivery segue regole diverse per ogni tipo di asset. Le tabelle che seguono riportano la corrispondenza tra i parametri.

Immagini

Parametro legacy	Nuovo parametro	Nota
`prettyName`	`dynamicSeoSuffix`	Resta nel percorso, in coda all'URL
`preset`, `divArea`	`w`, `h`	Le dimensioni diventano parametri di query
`scalemode`	`crop`	Cambia solo il nome, i valori restano gli stessi
`cropx`, `cropy`, `cropw`, `croph`	`cx`, `cy`, `cw`, `ch`	Accettano solo valori assoluti in pixel
`quality`	`q` oppure `q_auto`	`q` per un valore numerico da 5 a 95; `q_auto` per i valori `high`, `medium`, `low`
`fill`	`zoom`	Imposta `zoom=true` quando ti serve
`fillcolor`	`fillColor`	Formato HEX invece di rgba
`enhance`, `sharpness`	`brightness`, `contrast`, `sharpness`	Il prefisso `enhance` è stato rimosso. Le nuove API aggiungono `saturation` e `blur`
`dpr`	`dpr`	Valori ammessi: 1, 2, 3, 4
`format`	`format`	THRON eroga automaticamente il formato migliore per il browser, con default AVIF

Nota: le modalità di ritaglio automatico crop=auto e crop=product fanno parte delle funzioni di AI Media Adapting incluse nel profilo ULTRA. Con il profilo PRO converti usando il crop manuale, con cx, cy, cw e ch.

Se i tuoi URL legacy usano valori percentuali per il crop, convertili in pixel con questa formula:

cx = int(round(w * (cropX / 100)))
cy = int(round(h * (cropY / 100)))
cw = int(round(w * (cropW / 100)))
ch = int(round(h * (cropH / 100)))

Esempio di conversione:

URL legacy: https://lago-cdn.thron.com/delivery/public/image/lago/5aa99e51-75a7-4c04-9801-094ac1de88f2/sqVrcnw/std/640x0/image.webp?quality=70
Nuovo URL: https://lago-cdn.thron.com/api/v1/content-delivery/shares/sqVrcnw/contents/5aa99e51-75a7-4c04-9801-094ac1de88f2/image/image.webp?w=640&q=70

Video

Le nuove API sostituiscono i canali fissi del parametro channelType con maxH, che definisce l'altezza massima di erogazione. Per convertire un URL video, recupera l'altezza dal dettaglio dell'asset legacy e abbinala al valore corrispondente di maxH.

URL legacy: https://lago-cdn.thron.com/delivery/public/video/lago/eb50098e-a5da-433d-8b72-970f8a0deefa/wddU3re/WEBHD/qvideo1
Nuovo URL: https://lago-cdn.thron.com/api/v1/content-delivery/shares/wddU3re/contents/eb50098e-a5da-433d-8b72-970f8a0deefa/video/source/video?maxH=1080

Il valore che puoi chiedere con maxH e i codec disponibili dipendono dal profilo di AI MediaBoost attivo sul tuo contratto.

Profilo	Risoluzione massima	Codec
PRO	Full HD	H264
ULTRA	4K	H264, H265, AV1

Entrambi i profili erogano in progressive download e in HTTP streaming. Con il profilo PRO l'erogazione si ferma a Full HD: un valore di maxH superiore non produce un video in 4K.

Documenti e file originali

I documenti vengono serviti come PDF tramite il segmento pdf. Per scaricare il file originale, qualunque sia il suo tipo, usa il segmento original con il parametro download=true.

URL legacy: https://lago-cdn.thron.com/delivery/public/document/lago/f409aaac-d4e0-41f9-9b97-c9178f6e2da4/hiz3eq/WEB/regolamento.pdf
Nuovo URL: https://lago-cdn.thron.com/api/v1/content-delivery/shares/hiz3eq/contents/f409aaac-d4e0-41f9-9b97-c9178f6e2da4/pdf/regolamento.pdf

Nota: il parametro download=true su un'immagine scarica il file nel formato di delivery, ad esempio AVIF, non nel formato originale. Se ti serve il file sorgente, usa il segmento original.

Audio, pagelet e thumbnail

Per audio e pagelet la conversione è diretta: i segmenti diventano audio/source e pagelet, mentre i parametri di percorso channelType e lcid sono stati rimossi.

Le thumbnail hanno invece un comportamento dedicato: accettano solo w, h e maxAge, e non accettano più i parametri di image editing. L'immagine viene erogata nel formato migliore disponibile, ridimensionata e, quando necessario, ritagliata con crop centrato.

Configurazione consigliata

Esegui i passaggi in questo ordine per non penalizzare i canali durante la transizione:

Attiva il Custom Domain.
Fai un’anagrafica delle pkey coinvolte e comunicale a THRON.
Per le vecchie public URL, chiedi a THRON di far tornare sempre la nuova delivery, tramite il Link Juice applicato alle tue pkey, iniettando un comportamento di redirect che non ti farà perdere il ranking.
Imposta i redirect 301 delle URL legacy verso le nuove, in automatico le vecchie rotte restituiranno un 301, indirizzando verso la nuova rotta che eroga i contenuti; i parametri vengono mappati automaticamente tra le vecchie e le nuove API.

Esempio di redirect 301:

Da: https://lago-cdn.thron.com/delivery/public/image/lago/20212d26-2f05-4ec1-8e09-87892e2572a3/sqVrcnw/std/520x568/fauteuil.webp?quality=70
A: https://lago-cdn.thron.com/api/v1/content-delivery/shares/sqVrcnw/contents/20212d26-2f05-4ec1-8e09-87892e2572a3/image/fauteuil.webp?ch=2915&cw=2670&q=70

Per 2/3 mesi lascia le tue URL public attive, in modo che Google possa gestire correttamente il trasferimento del Link Juice.
Quando sei sicuro che il Link Juice sia stato trasferito sulle nuove rotte, aggiorna le vecchie URL presenti sui tuo canali con le nuove content-delivery API.

Limiti attuali del trasferimento di Link Juice

Il trasferimento del Link Juice è già disponibile per tutti i tipi di asset, con due eccezioni:

Thumbnail: sono in corso approfondimenti per garantire un'integrazione ottimale con le Content Delivery API.
Audio: la lavorazione può essere avviata su richiesta, parlane con il tuo account di riferimento THRON.

Custom Domain: il vantaggio che si sblocca con la migrazione

Durante la fase di migrazione o dopo averla completata, attiva un Custom Domain: i tuoi asset vengono serviti da un sottodominio tuo, ad esempio assets.miodominio.com, invece che dal dominio THRON. Il vantaggio è sia SEO, perché consolidi traffico e backlink su un unico dominio, sia di brand, perché gli URL restano coerenti con la tua identità ovunque vengano condivisi.

Il Custom Domain è disponibile solo sulle Content Delivery API e non è supportato sulle vecchie API public. Per attivarlo, contatta il tuo account di riferimento THRON.

## Articoli di approfondimento
- Custom Domain di AI MediaBoost: cos'è e come attivarlo
- La pKey: cos'è e come gestirla
- Integra THRON su un canale esterno: guida per sviluppatori
- Image editing di AI MediaBoost: cosa fa e come usarlo
- Embeddare un Digital Asset in un sito o pagina web esterna

Serve aiuto?

Per problemi tecnici, scrivi a support@thron.com

Channel Activation