CitadelTracker · Routing · Domains · Ops

Integration guide

Запуск нового traffic flow без contract drift між шарами.

Новий Citadel треба інтегрувати не як “просто tracking link”, а як зв’язку з кількох runtime surfaces: tracking entrypoint, routing policy, branded domain, landing instrumentation, stats payloads і operational checks між Django, FastAPI та edge layer.

Routing contracts Branded delivery Submit-level events
What this page does Переводить запуск flow з набору ручних дій у зрозумілий operational сценарій.
Main risk Не окремі поля, а розриви між request, policy, events і stats layers.
Operating model

Citadel працює як traffic operations layer, а не як окремий redirect script.

Entry layer

Ads ведуть на tracking URL або branded path, де система знаходить link, domain binding і routing policy.

Decision layer

Policy engine вирішує secure або public route, зберігає reason, revision і decision trail.

Read layer

Landing events, stats cards, share reports і admin surfaces читають той самий operational state.

Ключова ідея:

Найбільший ризик тут не в окремих моделях, а в переходах між шарами: worker → FastAPI, FastAPI → Django policy API, stats UI → event payload schema. Саме тому гайд нижче будується навколо інтеграційних контрактів, а не лише навколо полів форми.

Крок 1

Підготуйте runtime objects, з яких складається один flow

Routing Policy

Назва policy, public fallback, secure destination, GEO/ASN/IP правила, duplicate window, automation controls, rollout percentage і path prefix.

Tracking Link

Slug, labels для source/vertical/funnel, пов’язана policy, success mode і generated landing script.

Tracking Domain

DNS verify, SSL/nginx provisioning, branded URL preview і прив’язка до links або policies.

Checkpoint: перед запуском у вас має бути не просто link, а цілісний runtime path: policy, domain binding і landing instrumentation strategy.

Setup first

Поки ці базові objects не узгоджені між собою, усі наступні кроки лише маскують structural drift.

Крок 2

У рекламу ставиться entry URL, який Citadel реально може резолвити як flow

  1. Відкрийте Admin → Tracking links і знайдіть потрібний link.
  2. Скопіюйте canonical path /r/<slug>/ або branded path з custom domain.
  3. Не використовуйте старі ручні redirect URLs, якщо link уже має generated URL в Admin.
  4. Для одного джерела трафіку тримайте один явний entrypoint, щоб не плодити паралельні схеми атрибуції.
https://citadeltracker.pro/r/pl-finance-main/?source=facebook
https://offer-domain.com/onlyaff/pl-finance-main/?source=tiktok
Не змішуйте терміни:

Tracking Link у Citadel це entry object для flow. Campaign і Funnel тут радше організаційні або аналітичні контексти, а не сам runtime-маршрут.

Крок 3

Підключіть branded domain як частину route design, а не як косметичний alias

  1. Створіть домен в Admin → Tracking domains.
  2. Скопіюйте Server IP і додайте DNS A record.
  3. Натисніть Verify DNS, потім Provision SSL + nginx.
  4. Прив’яжіть домен до потрібних tracking links.
  5. Якщо policy використовує path_prefix, переконайтеся, що branded preview збігається з реальною route structure.
Branded domain тут функціональний.

Він впливає не тільки на зовнішній вигляд URL, а й на узгодженість між policy routing, click resolution, preview paths і landing expectations.

Крок 4

Landing instrumentation має замикати attribution loop тим самим click_id

  1. Відкрийте потрібний Tracking Link і візьміть готовий Landing script.
  2. Вставте його на landing page один раз.
  3. Переконайтеся, що landing зчитує click_id з URL і не перетирає його власною логікою.
  4. Після успішної форми викликайте helper або налаштуйте success URL match.

JSБазовий submit hook

window.CitadelTracker.markSubmitted({
  status: "ok",
  crm: "external",
  step: "lead-form"
});
Landed event Спрацьовує при відкритті landing і закриває зв’язок між entry request та page view.
Submitted event Фіксує бізнес-подію і піднімає метрики в stats/reporting surfaces без ручного добору click rows.
One identifier

У цьому гайді все крутиться навколо одного click_id: якщо він не проходить шлях цілісно, решта аналітики вже не врятує flow.

Крок 5

Перевірте міжшарові контракти до запуску, інакше drift проявиться вже в проді

worker → FastAPI

Перевірте, що edge/request layer передає ті самі поля, які routing resolver очікує для country, ip, ua, bot/risk signals і request identifiers.

FastAPI → Django

Policy API має повертати стабільну decision schema: destination, reason, revision, served route і fallback semantics без умовної двозначності.

stats UI → events

Назви подій, статуси submit і часові поля повинні бути ті самі, які використовують admin cards, report tables і share links.

Що звірити руками перед rollout
  1. Чи один і той самий click_id видно в URL, click row і event payload.
  2. Чи branded path реально мапиться на потрібний tracking link та policy.
  3. Чи stats поверхня читає саме ті event names, які landing script зараз відправляє.
  4. Чи policy reason у логах відповідає фактичному маршруту, який отримав користувач.
Крок 6

Проженіть end-to-end launch check до першого реального бюджету

  1. Відкрийте рекламний entry URL.
  2. Перевірте, що після резолву landing відкрився з валідним click_id.
  3. Упевніться, що в Admin → Clicks з’явився новий click із правильною policy context.
  4. Відправте форму або симулюйте успішний submit.
  5. Перевірте landed_at, submitted_at і відповідні події.
  6. Звірте admin stats або share report: request, landed, submitted і CR мають вирости синхронно.

Ready for traffic: flow вважається готовим лише тоді, коли збігаються routing decision, click audit trail, landing events і stats read model.

Operational launch

Новий Citadel виглядає переконливо тоді, коли лендинг і гайд говорять про одну й ту саму систему: routing, tracking, domains і platform operations.

Ця сторінка має завершувати продаж ідеї: Citadel не просто редіректить трафік, а збирає весь launch path в одну контрольовану surface.

Відкрити Admin Повернутись на landing
Routepolicy resolved
Clickattribution preserved
Statsreporting aligned