Ana Kowalska è una solutions engineer di Elido che ha guidato una dozzina di progetti di migrazione attraverso il cambio da Bitly. Ritiene che la maggior parte del dolore sia evitabile se si fa l'audit prima di spostarsi, non dopo.
Il migrate-from-bitly-playbook copre l'arco strategico: verifica ciò che hai, esportalo, importalo, cambia il DNS. Quel post è il punto di partenza giusto se non hai mai fatto una migrazione da Bitly prima.
Questo post è diverso. Si concentra su cosa si rompe - i modi di fallimento specifici che emergono dopo che il piano concettuale è completato e stai effettivamente eseguendo la migrazione sui dati di produzione. Sette di essi ricorrono spesso, e tutti e sette sono prevenibili se sai dove guardare.
TL;DR#
- Gli slug Bitly sono case-sensitive; molte piattaforme di redirect non lo sono.
bit.ly/AbCdebit.ly/abcdsono link diversi in Bitly e si comporteranno diversamente se il tuo script di migrazione converte gli slug in minuscolo durante l'importazione. - I gap del TTL DNS causano un gap di redirect anche dopo il cambio del CNAME. Abbassa il TTL a 60 secondi almeno 24 ore prima del cambio, non cinque minuti prima.
- I webhook che puntano agli endpoint
api-ssl.bitly.comsmettono di funzionare nel momento in cui annulli o disattivi l'account Bitly. Riconfigura tutti i consumer a valle prima di toccare lo stato dell'account. - I deeplink con segmenti di percorso (
bit.ly/app/account/settings) collidono con qualsiasi regola di routing Elido che corrisponde anche sul prefisso del percorso. Verifica gli slug dei deeplink separatamente dagli slug di redirect standard.
Le sette cose che si rompono davvero#
Prima di qualsiasi discussione sugli strumenti, è utile avere davanti la tassonomia dei fallimenti. La maggior parte delle post-mortem delle migrazioni indica uno di questi:
1. Case sensitivity degli slug. Bitly preserva il case negli slug - bit.ly/SummerSale e bit.ly/summersale sono link distinti. Se il tuo script di importazione normalizza gli slug in minuscolo (un comportamento predefinito comune nelle librerie di gestione URL), crei silenziosamente lo slug sbagliato e la variante con lettere maiuscole genera un 404. Questo riguarda le campagne email dove lo slug è stato incorporato con case misto.
2. Comportamento con la barra finale. bit.ly/campaign/ e bit.ly/campaign vengono gestiti come lo stesso link nel router di Bitly. Alcune piattaforme trattano la variante con barra finale come un percorso distinto. Se il tuo workspace Elido è frontato da un reverse proxy con la normalizzazione degli URL stretta abilitata, una richiesta con barra finale potrebbe risolversi diversamente rispetto allo slug canonico.
3. Preservazione dei parametri query. Se un URL di destinazione di un link Bitly contiene già parametri query - https://acme.example/landing?source=bitly - e il clic porta anche parametri UTM aggiunti al momento della condivisione, devi verificare che il comportamento di unione della destinazione sia identico in Elido. Il comportamento predefinito di Bitly per gli UTM aggiunti è unirli alla query string esistente. Testa questo esplicitamente per qualsiasi link il cui URL di destinazione contiene già parametri.
4. Aggiunta UTM a livello di piattaforma. Il tier enterprise di Bitly supporta l'aggiunta UTM a livello di workspace: ogni redirect in uscita ottiene un UTM aggiunto indipendentemente da cosa contiene l'URL di destinazione originale. Se lo avevi abilitato in Bitly senza documentarlo, potresti avere analytics che dipendono da UTM che Elido non sta ancora aggiungendo. Controlla le impostazioni del tuo workspace in Bitly per le regole di aggiunta automatica prima dell'export. L'equivalente di Elido sono i template UTM a livello di workspace o campagna - la pagina custom domains feature indica dove si trova quella configurazione.
5. Gap del TTL DNS. Questa è la causa più comune di un gap di redirect al cambio. I resolver DNS mettono in cache il vecchio CNAME per la durata del TTL corrente. Se il tuo TTL è rimasto a 86400 secondi per due anni, cambiarlo a 300 secondi cinque minuti prima di cambiare il record A significa che la maggior parte dei resolver mantiene ancora il vecchio record per altre 23 ore e 55 minuti. Il cambio non è immediato; si propaga.
6. Riconfigurazione dei webhook. Qualsiasi sistema che consuma eventi webhook di Bitly - pipeline di analytics, job di arricchimento CRM, attribuzione degli ordini Shopify - si attiva sull'URL dell'endpoint Bitly. Quell'endpoint va offline quando annulli o fai un downgrade dell'account Bitly al di sotto del tier che supporta i webhook. La configurazione dei webhook di Bitly si trova a livello di account e non viene esportata con i dati dei link. Ogni consumer deve essere inventariato e reindirizzato manualmente.
7. Collisioni di percorso con i deeplink. I deeplink mobile spesso usano il percorso dell'URL abbreviato per codificare lo stato di navigazione dell'app - bit.ly/app/profile/edit potrebbe mappare su una destinazione come yourapp://profile/edit. Quando migri questi slug su Elido, lo slug app/profile/edit contiene barre. Il router di Elido potrebbe trattare i percorsi delimitati da barre diversamente dal trattamento opaco degli slug di Bitly. Verifica che gli slug dei deeplink con segmenti di percorso vengano creati con l'esatta stringa dello slug, non reinterpretati come percorsi annidati.
Audit pre-migrazione: segmenta per livello di rischio#
L'API Bitly (acceduta il 2026-05-12) espone i conteggi dei clic per link tramite GET /v4/bitlink/{bitlink}/clicks/summary. Prima di esportare e importare qualsiasi cosa, usa questo per segmentare il tuo inventario.
La segmentazione pratica:
- Tier must-not-break (top 1%): link con almeno 10× il conteggio mediano dei clic negli ultimi 30 giorni. Questi sono attivi in email, materiali stampati, landing page di annunci a pagamento. Necessitano di verifica manuale dopo il cambio, non solo di controlli automatici.
- Tier monitor (successivo 9%): link con volume di clic superiore alla mediana. La verifica automatica del 301 è sufficiente, ma segnala qualsiasi link che si risolve inaspettatamente.
- Tier bulk (restante 90%): slug con traffico basso o nullo. Verifica in modo programmatico; accetta un piccolo tasso di errore e correggi su segnalazione.
Esporta un riepilogo dei clic di 30 giorni per link durante la fase di inventario. Un semplice ciclo di paginazione sull'API Bitly reference (acceduta il 2026-05-12) ti fornisce questi dati; il campo link_clicks nell'endpoint dei bitlink di gruppo è il contatore nel tempo, più grossolano ma sufficiente per il triage:
# Pagina tutti i link in un gruppo Bitly e scrivi in JSONL
NEXT_URL="https://api-ssl.bitly.com/v4/groups/${GROUP_GUID}/bitlinks?size=100"
while [ -n "$NEXT_URL" ]; do
RESP=$(curl -s -H "Authorization: Bearer ${BITLY_TOKEN}" "$NEXT_URL")
echo "$RESP" | jq -c '.links[]' >> bitly-links.jsonl
NEXT_URL=$(echo "$RESP" | jq -r '.pagination.next // empty')
done
Ordina l'output per link_clicks in ordine decrescente. Il top 1% è il tuo tier must-not-break. Esporta i loro slug in un file separato prima di eseguire l'importazione in blocco.
Preservazione degli slug: la chiamata di importazione che conta#
L'endpoint di importazione in blocco di Elido su POST /v1/links/bulk accetta un campo slug per link. Se non lo imposti esplicitamente, Elido genera un nuovo slug casuale - che è il comportamento sbagliato per una migrazione. Passa sempre lo slug sorgente.
# Importazione in blocco con preservazione dello slug - 100 link per chiamata
curl -s -X POST "https://api.elido.app/v1/links/bulk" \
-H "Authorization: Bearer ${ELIDO_API_KEY}" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: mig-batch-$(date +%s)" \
-d '{
"workspace_id": "'"${WORKSPACE_ID}"'",
"domain_id": "'"${DOMAIN_ID}"'",
"links": [
{
"slug": "SummerSale",
"destination_url": "https://acme.example/summer",
"tags": ["bitly-migrated", "campaign-summer"]
},
{
"slug": "AbCd",
"destination_url": "https://acme.example/landing",
"tags": ["bitly-migrated"]
}
]
}'
Due cose da notare in questa chiamata. Prima di tutto, i valori degli slug sono "SummerSale" e "AbCd" - il case misto è preservato esattamente come appariva in Bitly. Non convertirli in minuscolo. In secondo luogo, l'header Idempotency-Key significa che puoi rieseguire un batch parziale in modo sicuro; Elido restituisce il link esistente invece di crearne un duplicato. Questo è il pattern corretto per una migrazione che potrebbe dover riprendere.
Per il tier must-not-break, esegui l'importazione interattivamente per link invece che in batch, e verifica ciascuno prima di procedere. Per il tier bulk, invia batch da 100 per chiamata e processa l'array degli errori nella risposta per individuare eventuali slug che hanno generato conflitti o fallito.
Cambio DNS senza gap#
Il cambio DNS è il momento in cui il traffico live si sposta. Fatto correttamente, gli utenti non subiscono interruzioni. Fatto con un TTL obsoleto, c'è un gap misurato in ore, non minuti.
La sequenza è importante. Vedi il diagramma della timeline qui sotto.
La timeline in dettaglio:
T−7 giorni: Abbassa il TTL sul record CNAME o A a 60 secondi. Questo è il passaggio critico che la maggior parte dei team manca. La RFC 1034 §3.6 (IETF datatracker, sezione sul caching dei record di risorse) definisce il TTL come la durata massima della cache in cui un resolver può tenere il record. Se il tuo TTL attuale è 86400 (un giorno), cambiarlo ha effetto solo dopo che la versione attualmente in cache scade. Devi abbassare il TTL almeno un intero periodo del TTL corrente prima del cambio. Una settimana è sicura; 24 ore è il minimo.
T−1 ora: Verifica che il TTL basso si sia propagato. Usa uno strumento come dig @8.8.8.8 links.tuobrand.com +ttl da almeno tre endpoint resolver diversi. Il TTL riportato dovrebbe essere vicino a 60 secondi.
T−0: Sostituisci la destinazione CNAME dall'edge di Bitly a quello di Elido. Lato Elido, il dominio dovrebbe essere già registrato e verificato nel tuo workspace - non cambiare il DNS prima che l'edge di Elido sia pronto ad accettare il traffico. La prima richiesta dopo la propagazione attiva l'emissione del certificato tramite il TLS automatico on-demand, che si completa in circa 2-3 secondi per quella singola richiesta. Le richieste successive colpiscono la cache e si risolvono in pochi millisecondi sull'edge in regione UE.
T+5 minuti: Esegui uno spot-check da una seconda rete (usa un hotspot mobile per aggirare la cache del resolver del tuo ufficio). curl -sI https://links.tuobrand.com/uno-slug-noto dovrebbe restituire un 301 Moved Permanently che punta alla destinazione attesa, proveniente dagli header dell'edge di Elido.
T+1 ora: Ripristina il TTL al suo valore operativo normale (300 o 3600 secondi). Mantenere il TTL a 60 secondi a tempo indeterminato aggiunge carico al tuo provider DNS e all'infrastruttura dei resolver.
T+24 ore: Esegui il controllo completo degli slug (vedi la sezione successiva).
Secondo la RFC 7231 §6.4.2, una risposta 301 Moved Permanently può essere messa in cache dagli intermediari a tempo indeterminato a meno che un header cache-control esplicito non la sovrascriva. Ciò significa che qualsiasi client che ha colpito la vecchia destinazione Bitly durante il gap TTL potrebbe aver messo in cache un 301 che punta all'infrastruttura di Bitly. Questi redirect in cache si risolvono correttamente finché l'infrastruttura di Bitly è attiva, ecco perché conta la finestra di sovrapposizione di 30 giorni dell'account Bitly.
L'audit della catena 301: verifica notturna con script#
Dopo il cambio, esegui un ciclo di verifica notturno sul tuo tier must-not-break. L'obiettivo è individuare eventuali slug il cui comportamento è cambiato - che restituiscono una destinazione inattesa, un 404 o una catena di redirect più lunga di due hop.
# Verifica che gli slug principali si risolvano correttamente tramite Elido
# top-slugs.txt: uno slug per riga, senza prefisso del protocollo
DOMAIN="links.tuobrand.com"
FAIL=0
while IFS= read -r slug; do
STATUS=$(curl -s -o /dev/null -w "%{http_code}" \
--max-redirs 0 \
"https://${DOMAIN}/${slug}")
LOCATION=$(curl -s -I --max-redirs 0 \
"https://${DOMAIN}/${slug}" \
| grep -i '^location:' | tr -d '\r' | cut -d' ' -f2)
if [ "$STATUS" != "301" ]; then
echo "FAIL [$STATUS] $slug → expected 301"
FAIL=$((FAIL + 1))
else
echo "OK [301] $slug → $LOCATION"
fi
done < top-slugs.txt
echo "---"
echo "Failures: $FAIL"
exit $FAIL
Esegui questo contro il tier must-not-break (in genere 50–200 slug per la maggior parte dei team) ogni notte per le prime due settimane dopo il cambio. Inoltra l'output al tuo canale di alerting. Se FAIL è diverso da zero, vuoi che un essere umano lo esamini prima dei picchi di traffico mattutini.
Il flag --max-redirs 0 è intenzionale: vuoi il redirect di Elido, non la destinazione finale. Se lo Status è 200 invece di 301, qualcosa lato Elido sta servendo la destinazione direttamente invece di reindirizzare, il che significa che lo slug si è risolto in un link configurato come pass-through diretto. Vale la pena indagare.
Per il tier monitor, esegui una scansione settimanale più leggera. Per il tier bulk, affidati alle segnalazioni di errore dei sistemi a valle - i link rotti nelle email generano cambiamenti nel tasso di bounce che la tua piattaforma email surfacerà.
Riconfigurazione dei webhook#
I webhook di Bitly sono documentati nell'API reference Bitly (acceduta il 2026-05-12) nella sezione Webhooks. Ogni webhook si attiva sugli eventi di clic e include il bitlink, il referrer e i campi user-agent. Consumer comuni:
- Shopify: app di attribuzione che tracciano quale link abbreviato ha portato a una conversione. Configurato nel pannello di amministrazione dell'app Shopify, puntando a un endpoint di terze parti che chiama la verifica webhook di Bitly.
- Stripe: alcune pipeline di attribuzione di fatturazione taggano i nuovi trial in entrata con i dati UTM del link abbreviato di origine, ottenuti tramite il webhook Bitly.
- Slack: bot per le performance dei link che pubblicano riepiloghi dei clic in un canale
#marketing. - Pipeline ETL personalizzate: qualsiasi pipeline di data warehouse che ingerisce eventi di clic Bitly per arricchimento o join di attribuzione.
La checklist di migrazione per i webhook:
- Esporta la configurazione dei tuoi webhook Bitly prima di qualsiasi modifica all'account. L'API Bitly
GET /v4/workspaces/{workspace_guid}/webhooksrestituisce l'elenco. Salvalo in un file. - Per ogni consumer, identifica l'URL dell'endpoint che riceve gli eventi Bitly e il segreto usato per la verifica HMAC.
- Configura l'endpoint webhook Elido equivalente. I payload dei webhook di Elido hanno uno schema diverso da quello di Bitly - i campi sono simili ma non identici. Adatta il gestore del consumer per accettare il nuovo schema.
- Esegui entrambi i webhook in parallelo durante la finestra di sovrapposizione. Configura Elido per attivare i webhook a partire dal giorno del cambio, mantenendo attivo il webhook Bitly. Il tuo consumer riceverà due eventi per clic durante la sovrapposizione - deduplicali sull'URL abbreviato + timestamp, o accetta il doppio conteggio durante la finestra di sovrapposizione come artefatto noto.
- Dopo 72 ore di conferma della consegna del webhook Elido, rimuovi la configurazione del webhook Bitly da ogni consumer.
La finestra di grazia per la rotazione del segreto è il periodo di sovrapposizione. Non ruotare il segreto del webhook Elido finché ogni consumer non è stato verificato. Ruotare il segreto prima che un consumer sia aggiornato significa che quel consumer elimina silenziosamente gli eventi senza errori - il controllo HMAC fallisce e la maggior parte dei gestori di webhook scarta i payload con firma non valida senza allertare.
Piano di rollback: mantieni Bitly attivo per 30 giorni#
La procedura di rollback è semplice: ripristina il CNAME DNS alla destinazione di Bitly. Poiché hai pre-impostato il calo del TTL e il record DNS è ancora a 60 secondi (finché non lo ripristini), un rollback DNS si propaga in meno di due minuti.
Prepara il comando di rollback prima di iniziare:
# Script di rollback - esegui questo per ripristinare il DNS a Bitly (adattalo al tuo provider DNS)
# Esempio Route 53 usando AWS CLI
aws route53 change-resource-record-sets \
--hosted-zone-id "${HOSTED_ZONE_ID}" \
--change-batch '{
"Changes": [{
"Action": "UPSERT",
"ResourceRecordSet": {
"Name": "links.tuobrand.com",
"Type": "CNAME",
"TTL": 60,
"ResourceRecords": [{"Value": "cname.bitly.com"}]
}
}]
}'
Tieni questo in un file sul tuo laptop e in una posizione di runbook condivisa prima del cambio. Il momento peggiore per scrivere comandi di infrastruttura è durante un incidente attivo.
Mantieni l'account Bitly attivo e su un piano a pagamento che mantenga la risoluzione dei link per 30 giorni dopo il cambio. Il migrate-from-bitly-playbook raccomanda 90 giorni; 30 è il minimo pratico per i team che devono controllare i costi. Durante la finestra di 30 giorni, qualsiasi traffico che si risolve ancora tramite Bitly (redirect in cache, vecchi link bit.ly in materiali stampati) continua a funzionare. Dopo 30 giorni, valuta il traffico Bitly residuo nelle tue analytics e decidi se estendere.
Cosa monitorare durante la finestra di 30 giorni:
- Il tasso di errore di Elido sul tuo dominio personalizzato (cerca 404 inattesi nel log degli accessi).
- Eventuali picchi di traffico verso Bitly (la dashboard di Bitly mostra il traffico; un picco potrebbe significare che un redirect in cache si sta ancora risolvendo tramite Bitly per uno slug ad alto volume).
- Tassi di errore dei consumer webhook per qualsiasi consumer che hai riconfigurato.
Audit post-migrazione: cosa registrare#
Dopo la finestra di 30 giorni, esegui un passaggio di audit finale. Cosa appartiene al log di audit:
| Controllo | Metodo | Criterio di superamento |
|---|---|---|
| Il conteggio degli slug corrisponde | wc -l bitly-export.jsonl vs conteggio API Elido | Entro l'1% (tieni conto dei link archiviati intenzionalmente eliminati) |
| Controllo 301 del tier must-not-break | Script di audit notturno | Zero fallimenti per 7 giorni consecutivi |
| Riconciliazione del volume di clic | Confronta il totale dei clic Elido di 30 giorni con il totale Bitly di 30 giorni dello stesso periodo l'anno scorso | Entro la varianza stagionale attesa |
| Conferma del consumer webhook | Verifica che ogni consumer stia ricevendo eventi Elido e li stia elaborando correttamente | Nessun calo silenzioso per 7 giorni |
| TTL DNS ripristinato | dig +ttl links.tuobrand.com | TTL al valore operativo (300+ secondi) |
Registra questo nella tabella di audit del tuo team. Se il tuo workspace è su un piano Business o Enterprise, il log di audit di Elido registra tutte le operazioni API durante l'importazione ed è interrogabile tramite l'API. Recupera i record del batch di importazione e conserva uno snapshot insieme a questa tabella.
Errori comuni: tre pattern dal campo#
Il brand ecommerce DACH che ha perso una settimana di attribuzione email. Un retailer in Germania ha eseguito una campagna newsletter usando slug Bitly con UTM per-abbonato aggiunti al momento dell'invio. Lo script di migrazione ha normalizzato tutti gli slug in minuscolo prima di importarli in Elido. Dopo il cambio, la piattaforma email generava link con gli slug originali in case misto. Quei link restituivano 404 da Elido perché il case degli slug non corrispondeva. La correzione è stata rieseguire l'importazione con gli slug preservando il case, ma a quel punto sette giorni di traffico email erano atterrati su 404. L'attribuzione era irrecuperabile per quella coorte. La lezione: testa un link attivo da ogni canale attivo prima di dichiarare completa la migrazione.
La startup SaaS che ha fatto un triplo redirect agli utenti mobile. Un growth team aveva un dominio personalizzato Bitly frontato da Cloudflare in modalità proxy (arancione). Dopo il cambio, gli utenti mobile ricevevano tre redirect: Cloudflare → edge Elido → destinazione. Il salto extra proveniva da una Page Rule di Cloudflare che riscriveva HTTP in HTTPS prima di passare a Elido, poi Elido emetteva il proprio 301. iOS Safari ha messo in cache il redirect intermedio di Cloudflare come redirect permanente per 30 giorni. La correzione è stata impostare il record Cloudflare su grey-cloud (solo DNS) e rimuovere la Page Rule in conflitto. I redirect in cache in Safari hanno impiegato 30 giorni per scadere naturalmente. Verifica la modalità proxy CDN prima del cambio, non dopo.
L'agenzia che ha mancato un gruppo Bitly. Un'agenzia gestiva tre brand clienti sotto un singolo account Bitly, ciascuno con un gruppo Bitly diverso con il proprio dominio personalizzato. Lo script di migrazione interrogava solo il gruppo predefinito - quello sotto cui era stato creato il token dell'utente API. Due domini clienti sono stati migrati correttamente. Il terzo, sotto un gruppo secondario, non è mai stato esportato. Dopo il cambio, una campagna email di lancio di prodotto è stata inviata puntando al dominio personalizzato non migrato. Il dominio aveva ancora il CNAME di Bitly a TTL pieno, e Bitly stava servendo i link correttamente - ma la finestra di cambio per quel dominio era stata dichiarata completata. La fretta è stata una re-migrazione completa sotto scadenza. La lezione: enumera tutti i gruppi tramite GET /v4/user/groups prima di avviare qualsiasi fase di export. Verifica che il token abbia accesso a ogni gruppo.
Dove andare da qui#
Il migrate-from-bitly-playbook copre la sequenza strategica completa per i team che partono da zero nella pianificazione della migrazione. Questo post è il compagno sui modi di fallimento - usali insieme.
Per il lato prodotto di ciò verso cui stai migrando, la pagina solutions/marketers copre le funzionalità di attribuzione e tracciamento delle campagne a cui la maggior parte dei progetti di migrazione cerca di accedere. La pagina /compare/vs-bitly è il riferimento per la parità delle funzionalità se stai ancora confermando che il cambio valga la pena.
Se stai valutando Elido insieme a Rebrandly o Short.io, il confronto elido-vs-bitly copre i trade-off di prezzo e funzionalità a quattro volumi di traffico. La pagina delle funzionalità dei domini personalizzati documenta in dettaglio le meccaniche di verifica DNS e provisioning TLS - vale la pena leggerla prima della finestra di cambio DNS.
I fallimenti nelle migrazioni sono quasi sempre evitabili. Lo script di audit, la disciplina TTL e l'inventario dei webhook richiedono due ore di lavoro prima del cambio. Risparmiano giorni di risposta agli incidenti dopo.
Citazioni e fonti
- Bitly API Reference - dev.bitly.com/api-reference, acceduta il 2026-05-12
- RFC 1034 - Domain Names: Concepts and Facilities, §3.6 (resource record caching) - datatracker.ietf.org/doc/html/rfc1034
- RFC 7231 §6.4.2 - HTTP/1.1 Semantics and Content: 301 Moved Permanently - datatracker.ietf.org/doc/html/rfc7231#section-6.4.2
- Bitly API - Groups and Bitlinks endpoints - dev.bitly.com/api-reference, acceduta il 2026-05-12
Prova Elido
Incolla un URL, ottieni un link breve
Senza registrazione. Il link vive 30 giorni. Iscriviti per conservarlo.
Gratis, nessuna registrazione richiesta · 2 al giorno