Gift Collector — Обзор проекта и руководство (Help)

Навигация: Встраивание · Быстрый старт деплоя · Полные инструкции · Сводка

Это единый документ о проекте Gift Collector: назначение, архитектура, логика встраивания, сборка/деплой, диагностика, FAQ и дорожная карта.

Назначение

Интерактивный виджет «Сбор подарков» для сайтов (Tilda, WordPress, любые лендинги). Конструктор генерирует короткий сниппет из двух тегов: загрузчик инициализатор.

Структура проекта

  • Плагин WordPress: wp-content/plugins/gift-collector/
    • Standalone пакет (демо/конструктор/бандлы): wp-content/plugins/gift-collector/standalone/deploy-package/
    • Основные бандлы: deploy-package/dist/gc-standalone.min.js (канонический) и gc-standalone.js (неминифицированный)
  • Короткий алиас (зеркало): gc/
    • gc/index.html — iframe-зеркало длинной страницы (авто‑ресайз высоты)
    • gc/dist/ — короткие пути к бандлам (CDN-алиас)
  • Сервис (опционально): gc-service/ — вспомогательные роуты/здоровье, билд TypeScript.
  • Скрипты: scripts/*.ps1 — упаковка, релизы, деплой по FTP.
  • Релизы: releases/gift-collector/ — заметки, инструкции по откату.

Встраивание (streamer-first)

Конструктор генерирует короткий сниппет из 2 тегов:

  • Загрузчик (умный стример): serve.php?mode=boot
  • Инициализация: GiftCollector.init({...})

Пример:

<div id="gift-collector-app"></div>
<script src="https://word-pres.ru/gc/dist/serve.php?mode=boot"></script>
<script>
  GiftCollector.init({ target:'#gift-collector-app', /* ваши настройки */ });
  // При необходимости: window.GC_BASE для смены CDN-базы
</script>

Длинная страница и короткий алиас

  • Длинная: wp-content/plugins/gift-collector/standalone/deploy-package/index.html
  • Короткий алиас: gc/index.html — тонкое зеркало через <iframe> с авто‑ресайзом. Это исключает расхождения UI между страницами.

Сборка и запуск

  • TypeScript сборка корня:
    • VS Code Task: Build TypeScript
    • Команда PowerShell:
      node ./node_modules/typescript/bin/tsc
  • GC Service (dev):
    • Task: GC Service: Dev (ts-node-dev) — фоновой режим
    • Prod: GC Service: Start (prod) (зависит от GC Service: Build)

Деплой

  • FTP загрузка (плагин, deploy-package, gc-алиас и др.):
    • Скрипт: scripts/upload-gc-ftp.ps1
    • Запуск:
      powershell.exe -NoProfile -ExecutionPolicy Bypass -File "c:\Users\bilar\Downloads\Тест\scripts\upload-gc-ftp.ps1"
    • Рекомендация безопасности: хранить доступы вне репозитория (секреты/переменные окружения). В текущем скрипте креды заданы параметрами — замените на безопасный источник при проде.

Версионирование и релизы

  • Видимая метка версии в конструкторе (напр., v0.2.3.1).
  • Release notes: releases/gift-collector/RELEASE-<ver>.md (изменения, файлы, откат).
  • Пакетирование ZIP (для других проектов в монорепо) — см. задачи Package * (zip).

Диагностика и здоровье

  • Health check сервиса: Task GC Service: Health (проверяет http://localhost:3400/embed/health).
  • Внешний embed тест: gc-embed-test.html (если присутствует на проде — для проверки CORS/доступности бандлов).
  • Логи загрузчика: ошибки в консоли при невозможности загрузить ни один из источников.

Кодировка и надёжность

  • Везде UTF-8 без BOM, русские строки экранированы при сборке, чтобы избежать мохжибake.
  • Без querystring в путях скриптов — минимизирует блокировки кэшем/CDN и строгими CSP.
  • Фолбек-цепочка путей и проверка API перед стартом виджета.

Частые проблемы и решения (Troubleshooting)

  • 404/Script error при встраивании на внешний сайт:
    • Проверьте доступность всех путей из цепочки (min, версионированный, unmin) и отсутствие блокировок по домену.
    • Убедитесь, что вставка происходит перед </body>.
  • Иконки подарков не видны в галерее демо:
    • Проверьте стили обёртки SVG (.icon-svg-wrapper) и размеры svg.
  • Устаревший UI на коротком алиасе:
    • Алиас — зеркало длинной страницы через iframe. Если видите расхождения — обновите кэш (Ctrl+F5) и проверьте, что на проде загружен актуальный gc/index.html.
  • Высота iframe обрезается:
    • В gc/index.html используется ResizeObserver с таймер‑фолбеком. При жёстких CSP убедитесь, что изменения DOM не блокируются.

Расширение логики (хуки/монетизация)

  • Планируемые хуки виджета: onCollect, onClaim, onComplete (вызов коллбеков клиента, события для аналитики).
  • Монетизация: интеграция с провайдером платежей (например, YooKassa) и настройками в конструкторе (раздел «Монетизация»).

Полезные пути

  • Длинная страница: wp-content/plugins/gift-collector/standalone/deploy-package/index.html
  • Конструктор (ресурсы): deploy-package/constructor.{html,css,js}
  • Алиас-зеркало: gc/index.html
  • Бандлы (короткий путь): gc/dist/*
  • Скрипт деплоя: scripts/upload-gc-ftp.ps1
  • Релизы: releases/gift-collector/
  • Сервис (опционально): gc-service/ — вспомогательные роуты/здоровье, билд TypeScript.
    • Публичная проверка оплаты: POST /embed/verify-email

Разблокировка финального попапа

Финальный попап относится к премиум-настройкам конструктора.

  • Разблокировать: нажмите «Разблокировать за 299 ₽» в разделе «Финальный попап». После оплаты вернёт обратно с параметром final_popup_paid=true → доступ сохранится локально (cookie + localStorage).
  • Я уже оплатил: нажмите одноимённую кнопку и укажите email. Сервис проверит оплату и вернёт { ok: true } → раздел откроется.
  • Dev-подсказка: переменная окружения DEV_UNLOCK_ANY_EMAIL=1 для gc-service включает универсальный успех для любых email.

Автор и поддержка

Дорожная карта (next)

  • Добавить раздел «Монетизация» в конструктор и события хуков.
  • Единая схема конфигурации с экспортом/импортом JSON.
  • Улучшенный отчёт по установкам (анонимная телеметрия, опционально).
  • Расшарить виджет как NPM/UMD пакет для внешних интеграций.