Міграція з Bitly без розриву посилань: плейбук сценаріїв відмов

Ана Ковальська - інженер з рішень в Elido, яка супроводжувала десятки проєктів міграції під час перемикання з Bitly. Вона вважає, що більшості проблем можна уникнути, якщо провести аудит до перенесення, а не після нього.

Плейбук з міграції з Bitly охоплює стратегічну частину: аудит наявних даних, їх експорт, імпорт та перемикання DNS. Цей пост - найкраще місце для старту, якщо ви раніше не займалися міграцією з Bitly.

Цей пост про інше. Він зосереджений на тому, що ламається - конкретних сценаріях відмов, які виникають після завершення концептуального планування під час реальної міграції з продуктовими даними. Сім із них повторюються найчастіше, і всім семи можна запобігти, якщо знати, куди дивитися.

TL;DR#

Слаги Bitly чутливі до регістру; багато платформ редиректів - ні. bit.ly/AbCd та bit.ly/abcd - це різні посилання в Bitly, і вони поводитимуться по-різному, якщо ваш скрипт імпорту переведе слаги в нижній регістр.
Прогалини в DNS TTL спричиняють перерву в редиректах навіть після зміни CNAME. Знизьте TTL до 60 секунд принаймні за 24 години до перемикання, а не за п'ять хвилин.
Вебхуки, що вказують на ендпоінти api-ssl.bitly.com, перестануть працювати в момент скасування або деактивації акаунта Bitly. Перепідключіть усіх споживачів нижче по ланцюжку перед тим, як змінювати статус акаунта.
Діплінки з сегментами шляху (bit.ly/app/account/settings) конфліктують з будь-якими правилами маршрутизації Elido, які також збігаються за префіксом шляху. Аудитуйте слаги діплінків окремо від стандартних слагів редиректів.

Сім речей, які насправді ламаються#

Перед обговоренням інструментів корисно мати перед очима таксономію помилок. Більшість посмертних аналізів міграцій вказують на одну з цих причин:

1. Чутливість слагів до регістру. Bitly зберігає регістр у слагах - bit.ly/SummerSale та bit.ly/summersale є різними посиланнями. Якщо ваш скрипт імпорту нормалізує слаги до нижнього регістру (поширена поведінка за замовчуванням у бібліотеках для роботи з URL), ви непомітно створите неправильний слаг, а варіант з великими літерами повертатиме 404. Це впливає на email-кампанії, де слаг був вставлений у змішаному регістрі.

2. Поведінка кінцевого слеша. bit.ly/campaign/ та bit.ly/campaign обробляються як одне й те саме посилання в роутері Bitly. Деякі платформи розглядають варіант із кінцевим слешем як окремий шлях. Якщо ваш робочий простір Elido знаходиться за реверс-проксі з увімкненою суворою нормалізацією URL, запит із кінцевим слешем може оброблятися інакше, ніж канонічний слаг.

3. Збереження рядка запиту. Якщо цільовий URL посилання Bitly вже містить параметри запиту - https://acme.example/landing?source=bitly - і клік також несе параметри UTM, додані під час поширення, вам потрібно переконатися, що об'єднання цілей в Elido працює ідентично. Поведінка Bitly за замовчуванням для доданих UTM - це їх злиття з існуючим рядком запиту. Протестуйте це окремо для кожного посилання, цільовий URL якого вже містить параметри.

4. Додавання UTM на рівні платформи. Корпоративний тариф Bitly підтримує додавання UTM на рівні робочого простору: кожен вихідний редирект отримує UTM незалежно від того, що містить оригінальний цільовий URL. Якщо ця функція була увімкнена в Bitly і ви її не задокументували, ваша аналітика може залежати від UTM, які Elido ще не додає. Перевірте налаштування вашого робочого простору в Bitly на наявність правил автоматичного додавання перед експортом. Еквівалент в Elido - це шаблони UTM на рівні робочого простору або кампанії; сторінка функції кастомних доменів пояснює, де живуть ці налаштування.

5. Прогалина в DNS TTL. Це найпоширеніша причина перерви в редиректах під час перемикання. DNS-резолвери кешують старий CNAME на час дії поточного TTL. Якщо ваш TTL протягом двох років становив 86400 секунд, зміна його на 300 секунд за п'ять хвилин до оновлення запису A означатиме, що більшість резолверів все ще зберігатимуть старий запис ще 23 години та 55 хвилин. Перемикання не є миттєвим; воно потребує часу на поширення.

6. Перепідключення вебхуків. Будь-яка система, що споживає події вебхуків Bitly - конвеєри аналітики, завдання зі збагачення CRM, атрибуція замовлень Shopify - працює через URL-ендпоінт Bitly. Цей ендпоінт перестане працювати, як тільки ви скасуєте підписку або знизите рівень акаунта Bitly нижче того, що підтримує вебхуки. Конфігурація вебхуків Bitly знаходиться на рівні акаунта і не експортується разом із даними посилань. Кожного споживача потрібно інвентаризувати та перепідключити вручну.

7. Колізії шляхів діплінків. Мобільні діплінки часто використовують шлях короткого URL для кодування стану навігації в додатку - наприклад, bit.ly/app/profile/edit може вказувати на таку ціль, як yourapp://profile/edit. Коли ви мігруєте ці слаги в Elido, слаг app/profile/edit містить слеші. Роутер Elido може обробляти шляхи, розділені слешами, інакше, ніж непрозора обробка слагів у Bitly. Переконайтеся, що слаги діплінків із сегментами шляху створюються як точний рядок слагу, а не інтерпретуються як вкладені шляхи.

Аудит перед міграцією: сегментація за рівнем ризику#

Bitly API (доступ станом на 2026-05-12) надає дані про кількість кліків на посилання через GET /v4/bitlink/{bitlink}/clicks/summary. Перед тим як щось експортувати та імпортувати, використайте це для сегментації вашого інвентарю.

Практична сегментація:

Критичний рівень (Must-not-break, топ 1%): посилання з кількістю кліків ≥10× від медіани за останні 30 днів. Вони активні в листах, друкованих матеріалах, на платних лендінгах. Вони потребують ручної верифікації після перемикання, а не лише автоматичних перевірок.
Рівень моніторингу (наступні 9%): посилання з обсягом кліків вище середнього. Автоматичної перевірки 301 достатньо, але позначайте будь-які посилання з неочікуваним результатом.
Масовий рівень (решта 90%): слаги з низьким або нульовим трафіком. Перевіряйте програмно; допускайте невелику кількість помилок і виправляйте їх за запитом.

Експортуйте звіт про кліки за 30 днів для кожного посилання під час етапу інвентаризації. Простий цикл пагінації через довідник Bitly API (доступ станом на 2026-05-12) дозволяє отримати ці дані; поле link_clicks в ендпоінті bitlinks групи є лічильником за весь час, що є менш точним, але достатнім для сортування:

# Paginate all links in a Bitly group and write to 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

Відсортуйте вихідні дані за link_clicks у порядку спадання. Топ 1% - це ваш критичний рівень. Експортуйте їхні слаги в окремий файл перед запуском масового імпорту.

Збереження слагів: імпорт, що має значення#

Ендпоінт масового імпорту Elido POST /v1/links/bulk приймає поле slug для кожного посилання. Якщо ви не встановите його явно, Elido згенерує новий випадковий слаг - що є неправильною поведінкою для міграції. Завжди передавайте вихідний слаг.

# Bulk import with slug preservation - 100 links per call
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"]
      }
    ]
  }'

Зверніть увагу на дві речі в цьому запиті. По-перше, значення слагів - "SummerSale" та "AbCd" - збережені в тому ж регістрі, в якому вони були в Bitly. Не переводьте їх у нижній регістр. По-друге, заголовок Idempotency-Key означає, що ви можете безпечно перезапустити частину пакета; Elido поверне існуюче посилання замість створення дубліката. Це правильний паттерн для міграції, яку, можливо, доведеться відновлювати.

Для критичного рівня запускайте імпорт інтерактивно для кожного посилання, а не пакетом, і перевіряйте кожне перед продовженням. Для масового рівня використовуйте пакети по 100 за запит та обробляйте масив помилок у відповіді, щоб виявити будь-які слаги, які конфліктують або не були створені.

Перемикання DNS без перерви#

Перемикання DNS - це момент, коли живий трафік перенаправляється. Якщо все зроблено правильно, користувачі не помітять перерви. Якщо ж залишити застарілий TTL, виникне прогалина, що вимірюється годинами, а не хвилинами.

Послідовність має значення. Дивіться часову шкалу нижче.

Horizontal DNS cutover timeline showing T-7d TTL drop to 60s, T-0 A record flip, T+5min 95% propagation, T+1h TTL restore, T+24h audit pass

Детальна часова шкала:

T−7 днів: Знизьте TTL для запису CNAME або A до 60 секунд. Це критичний крок, який пропускає більшість команд. RFC 1034 §3.6 (IETF datatracker, розділ про кешування записів ресурсів) визначає TTL як максимальну тривалість кешування, протягом якої резолвер може зберігати запис. Якщо ваш поточний TTL становить 86400 (одна доба), зміна набуде чинності лише після завершення терміну дії поточної кешованої версії. Вам потрібно знизити TTL принаймні за один повний період поточного TTL до моменту перемикання. Один тиждень - це безпечно; 24 години - мінімум.

T−1 година: Переконайтеся, що низький TTL поширився. Використовуйте такий інструмент, як dig @8.8.8.8 links.yourbrand.com +ttl, принаймні з трьох різних ендпоінтів резолверів. Повідомлений TTL має бути близьким до 60 секунд.

T−0: Змініть ціль CNAME з Bitly на Elido. На стороні Elido домен уже має бути зареєстрований та верифікований у вашому робочому просторі - не перемикайте DNS до того, як вузол Elido буде готовий приймати трафік. Перший запит після поширення ініціює випуск TLS-сертифіката за запитом від наш edge, що триває приблизно 2-3 секунди для цього одного запиту. Наступні запити потрапляють у кеш і обробляються за лічені мілісекунди на вузлі (edge) у регіоні ЄС.

T+5 хвилин: Проведіть вибіркову перевірку з іншої мережі (використовуйте мобільну точку доступу, щоб обійти кеш резолвера вашого офісу). curl -sI https://links.yourbrand.com/any-known-slug має повернути 301 Moved Permanently, що вказує на очікувану ціль і походить із заголовків вузла Elido.

T+1 година: Відновіть TTL до його нормального робочого значення (300 або 3600 секунд). Тривале утримання TTL на рівні 60 секунд створює додаткове навантаження на ваш DNS-провайдер та інфраструктуру резолверів.

T+24 години: Проведіть повний аудит слагів (дивіться наступний розділ).

Згідно з RFC 7231 §6.4.2, відповідь 301 Moved Permanently може кешуватися посередниками нескінченно довго, якщо тільки явний заголовок cache-control не перевизначає це. Це означає, що будь-який клієнт, який перейшов за старим посиланням Bitly під час прогалини в TTL, міг закешувати 301, що вказує на інфраструктуру Bitly. Ці кешовані редиректи працюватимуть коректно, поки інфраструктура Bitly активна, саме тому 30-денне вікно перекриття акаунтів Bitly має значення.

Аудит ланцюжка 301: щонічна верифікація скриптом#

Після перемикання запустіть цикл щонічної верифікації для вашого критичного рівня. Мета - виявити будь-який слаг, поведінка якого змінилася: або він повертає неочікувану ціль, або 404, або ланцюжок редиректів стає довшим за два переходи.

# Verify top slugs resolve correctly via Elido
# top-slugs.txt: one slug per line, no protocol prefix
DOMAIN="links.yourbrand.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

Запускайте це для критичного рівня (зазвичай 50–200 слагів для більшості команд) щоночі протягом перших двох тижнів після перемикання. Спрямуйте вихідні дані у ваш канал сповіщень. Якщо FAIL не дорівнює нулю, ви захочете, щоб людина перевірила це до піку ранкового трафіку.

Прапорець --max-redirs 0 є навмисним: вам потрібен редирект Elido, а не кінцева ціль. Якщо Status дорівнює 200 замість 301, щось на стороні Elido обслуговує ціль безпосередньо, а не перенаправляє, що означає, що слаг розпізнано як посилання, налаштоване для прямого проходження. Це варто розслідувати.

Для рівня моніторингу запускайте легше щотижневе сканування. Для масового рівня покладайтеся на звіти про помилки від систем нижче по ланцюжку - непрацюючі посилання в листах спричиняють зміни у відсотках відмов, які ваша email-платформа відобразить.

Перепідключення вебхуків#

Вебхуки Bitly описані в довіднику Bitly API (доступ станом на 2026-05-12) у розділі Webhooks. Кожен вебхук спрацьовує на події кліків і включає поля bitlink, referrer та user-agent. Типові споживачі:

Shopify: додатки для атрибуції, які відстежують, яке коротке посилання привело до конверсії. Налаштовується в адмін-панелі додатка Shopify, вказуючи на сторонній ендпоінт, який викликає верифікацію вебхука Bitly.
Stripe: деякі конвеєри атрибуції платежів позначають вхідні реєстрації на пробний період даними UTM із вихідного короткого посилання, отриманими через вебхук Bitly.
Slack: боти продуктивності посилань, які публікують підсумки кліків у канал #marketing.
Власні ETL-конвеєри: будь-який конвеєр сховища даних, який отримує події кліків Bitly для збагачення або об'єднання атрибуції.

Контрольний список міграції для вебхуків:

Експортуйте конфігурацію вебхуків Bitly перед будь-якими змінами в акаунті. Bitly API GET /v4/workspaces/{workspace_guid}/webhooks повертає список. Збережіть його у файл.
Для кожного споживача визначте URL-ендпоінт, що отримує події Bitly, та секрет, що використовується для верифікації HMAC.
Налаштуйте еквівалентний ендпоінт вебхука Elido. Структури корисного навантаження Elido відрізняються від Bitly - поля схожі, але не ідентичні. Налаштуйте обробник споживача для прийняття нової схеми.
Запустіть обидва вебхуки паралельно під час вікна перекриття. Налаштуйте Elido на надсилання вебхуків з дня перемикання, зберігаючи вебхук Bitly активним. Ваш споживач отримуватиме дві події на клік під час перекриття - дедуплікуйте за коротким URL + міткою часу або прийміть подвійний підрахунок під час вікна перекриття як відомий артефакт.
Після 72 годин підтвердженої доставки вебхуків Elido видаліть конфігурацію вебхуків Bitly у кожного споживача.

Період ротації секретів - це вікно перекриття. Не ротуйте секрет вебхука Elido, поки кожен споживач не буде перевірений. Ротація секрету до оновлення споживача означатиме, що він непомітно втрачатиме події без помилок - перевірка HMAC не пройде, і більшість обробників вебхуків відкидають навантаження з недійсним підписом без сповіщення.

План відкату: тримайте Bitly активним протягом 30 днів#

Процедура відкату проста: поверніть CNAME DNS до цілі Bitly. Оскільки ви заздалегідь знизили TTL і запис DNS все ще становить 60 секунд (поки ви його не відновите), повернення DNS пошириться менш ніж за дві хвилини.

Підготуйте команду відкату до початку:

# Rollback script - run this to revert DNS to Bitly (adapt for your DNS provider)
# Route 53 example using AWS CLI
aws route53 change-resource-record-sets \
  --hosted-zone-id "${HOSTED_ZONE_ID}" \
  --change-batch '{
    "Changes": [{
      "Action": "UPSERT",
      "ResourceRecordSet": {
        "Name": "links.yourbrand.com",
        "Type": "CNAME",
        "TTL": 60,
        "ResourceRecords": [{"Value": "cname.bitly.com"}]
      }
    }]
  }'

Тримайте цей файл на своєму ноутбуці та в спільному сховищі інструкцій перед перемиканням. Найгірший момент для написання інфраструктурних команд - це активний інцидент.

Тримайте акаунт Bitly активним на платному тарифі, що забезпечує роботу посилань, протягом 30 днів після перемикання. Плейбук з міграції з Bitly рекомендує 90 днів; 30 - це практичний мінімум для команд, яким потрібно контролювати витрати. Протягом 30-денного вікна будь-який трафік, який все ще проходить через Bitly (кешовані редиректи, старі посилання bit.ly у друкованих матеріалах), продовжуватиме працювати. Через 30 днів оцініть залишковий трафік Bitly у вашій аналітиці та вирішіть, чи варто продовжувати.

Що контролювати протягом 30-денного вікна:

Рівень помилок Elido на вашому кастомному домені (стежте за неочікуваними 404 у логах доступу).
Будь-які сплески трафіку в Bitly (панель керування Bitly показує трафік; сплеск може означати, що кешований редирект все ще проходить через Bitly для високонавантаженого слагу).
Рівень помилок споживачів вебхуків для тих споживачів, яких ви перепідключили.

Аудит після міграції: що логувати#

Після 30-денного вікна проведіть фінальний аудит. Що має бути в лозі аудиту:

Перевірка	Метод	Критерій успіху
Кількість слагів збігається	`wc -l bitly-export.jsonl` проти лічильника в Elido API	У межах 1% (враховуючи навмисно видалені архівовані посилання)
Перевірка 301 для критичного рівня	Скрипт щонічного аудиту	Нуль помилок протягом 7 днів поспіль
Звірка обсягу кліків	Порівняння загальної кількості кліків Elido за 30 днів із показниками Bitly за аналогічний період минулого року	У межах очікуваних сезонних коливань
Підтвердження споживачів вебхуків	Переконайтеся, що кожен споживач отримує події Elido та коректно їх обробляє	Без втрат протягом 7 днів
DNS TTL відновлено	`dig +ttl links.yourbrand.com`	TTL на робочому рівні (300+ секунд)

Запишіть це в таблицю аудиту вашої команди. Якщо ваш робочий простір знаходиться на тарифі Business або Enterprise, лог аудиту Elido фіксує всі API-операції під час імпорту і доступний через API. Витягніть записи про пакети імпорту та збережіть копію поруч із цією таблицею.

Типові підвохи: три приклади з практики#

E-commerce бренд з регіону DACH, який втратив тиждень email-атрибуції. Ритейлер у Німеччині запустив розсилку новин, використовуючи слаги Bitly з UTM для кожного підписника, доданими під час відправлення. Скрипт міграції нормалізував усі слаги до нижнього регістру перед їх імпортом в Elido. Після перемикання email-платформа генерувала посилання з оригінальними слагами в змішаному регістрі. Ці посилання повертали 404 в Elido, оскільки регістр слагу не збігався. Виправленням став повторний імпорт зі збереженням регістру слагів, але на той час трафік з листів за сім днів потрапляв на 404. Атрибуція для цієї когорти була безповоротно втрачена. Урок: протестуйте одне живе посилання з кожного активного каналу перед оголошенням про завершення міграції.

SaaS стартап із потрійним редиректом для мобільних користувачів. Команда зростання мала кастомний домен Bitly за Cloudflare у режимі проксі (помаранчева хмара). Після перемикання мобільні користувачі отримували три редиректи: Cloudflare → вузол Elido → ціль. Зайвий крок з'явився через Cloudflare Page Rule, яке переписувало HTTP на HTTPS перед передачею в Elido, потім Elido видавав свій власний 301. iOS Safari закешував проміжний редирект Cloudflare як постійний редирект на 30 днів. Рішенням було переведення запису Cloudflare у режим сірої хмари (лише DNS) та видалення конфліктного Page Rule. Кешованим редиректам у Safari знадобилося 30 днів, щоб термін їх дії закінчився природним шляхом. Перевірте режим проксі вашого CDN до перемикання, а не після.

Агенція, яка пропустила групу Bitly. Агенція керувала трьома брендами клієнтів під одним акаунтом Bitly, кожен у своїй групі Bitly з власним кастомним доменом. Скрипт міграції запитував лише групу за замовчуванням - ту, для якої було створено токен користувача API. Домени двох клієнтів мігрували чисто. Третій, що знаходився в додатковій групі, ніколи не був експортований. Після перемикання була розіслана email-кампанія до запуску продукту, що вказувала на немігрований кастомний домен. Домен все ще мав CNAME Bitly з повним TTL, і Bitly обслуговував посилання коректно - але вікно перемикання для цього домену було оголошено завершеним. Результатом стала термінова повна переміграція в умовах дедлайну. Урок: перелічіть усі групи через GET /v4/user/groups перед початком будь-якого етапу експорту. Переконайтеся, що токен має доступ до кожної групи.

Куди рухатися далі#

Плейбук з міграції з Bitly охоплює повну стратегічну послідовність для команд, що починають планування міграції з нуля. Цей пост є доповненням щодо сценаріїв відмов - використовуйте їх разом.

Щодо продуктової частини того, куди ви мігруєте, сторінка рішення для маркетологів описує функції атрибуції та відстеження кампаній, до яких прагне отримати доступ більшість проєктів міграції. Сторінка /compare/vs-bitly є довідником паритету функцій, якщо ви все ще переконуєтеся, що перехід того вартий.

Якщо ви оцінюєте Elido разом із Rebrandly або Short.io, порівняння Elido проти Bitly охоплює ціноутворення та компроміси функцій при чотирьох різних обсягах трафіку. Сторінка функції кастомних доменів детально описує механіку верифікації DNS та надання TLS - варто прочитати перед вікном перемикання DNS.

Невдачі при міграції майже завжди можна попередити. Скрипт аудиту, дисципліна TTL та інвентаризація вебхуків займають дві години роботи перед перемиканням. Вони економлять дні реагування на інциденти після нього.

Цитати та джерела

Довідник Bitly API - dev.bitly.com/api-reference, доступ станом на 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 - Ендпоінти груп та бітлінків - dev.bitly.com/api-reference, доступ станом на 2026-05-12

Спробуйте Elido

Вставте URL - отримайте коротке посилання

Без реєстрації. Посилання живе 30 днів. Зареєструйтесь, щоб зберегти назавжди.

Безкоштовно, без реєстрації · 2 на день