Разработка парсера (Kotlin)
Как добавить своё расписание в приложение Кампус
Мобильное приложение Кампус работает с автоматически обновляющимся расписанием. В приложении нельзя редактировать расписание или создавать полностью собственное. Но при наличии навыков программирования можно добавить расписание своего ВУЗа.Что такое "парсеры"
Расписание в мобильном приложении обновляется автоматическими программами, которые запускаются каждый день, для каждого вуза. Данные программы называются "парсеры". Их принцип работы прост - они заходят на общедоступный источник расписания (например сайт вуза, или REST API), собирают информацию о списке групп и расписании каждой группы на 2-4 недели вперед, после чего отправляют собранную информацию на сервер Кампуса.Мобильные приложения работают с данными сохраненными на сервере Кампуса, поэтому обновление расписания в приложении происходит раз в день, а не сразу после изменения на сайте ВУЗа.
Добавление своего парсера
Чтобы расписание появилось в приложении нужно сделать несколько шагов:- В панели администратора должна быть создана запись нового ВУЗа. Это делает администратор проекта Кампус. Для этого потребуется:
- Сокращенное название
- Полное название
- Логотип (круглый, 225х225, png/jpg)
- Город
- Координаты главного корпуса (долгота, широта)
- Администратор даст вам логин и пароль от тестовой среды, для реализации парсера. Данные логин и пароль потребуются для отправки на сервер Кампуса подготовленного расписания.
- Нужно разработать свой парсер, используя готовый SDK на языке Kotlin и пример парсера. Для разработки используйте шаблон.
- Зарегистрируйтесь на GitHub
- Создайте новый проект из шаблона (кнопка Use template)
- Сделайте изменения описанные в разделе Template в Readme
- Реализуйте свою логику получения расписания и передачи в сдк для отправки на сервер Кампуса
- Протестируйте свой парсер на тестовой среде
- Для этого передавайте в
parserApiBaseUrl
адрес https://parser.api.campus.dev.dewish.ru/v3/ и вCredentials
логин/пароль полученные от администратора - Запускайте парсер, чтобы он полностью отработал, после чего можете проверить какое расписание сохранилось в Кампусе на странице https://web.campus.dev.dewish.ru
- Исправьте все найденные проблемы, проверьте разные группы на соответствие оригинальному расписанию. Важно чтобы все данные соответствовали оригиналу.
- Для этого передавайте в
- Передайте парсер для проверки в Кампус.
- Отправьте на почту информацию про ваш парсер - ссылка на github проект с парсером, название вуза на тестовой среде.
- Команда Кампуса проверит корректность собранного расписания на тестовой среде, сверит с оригиналом. Также проведет проверку кода. Если что-то нужно будет доработать - сообщим ответным письмом.
- После выполнения всех необходимых доработок парсер будет принят командой Кампуса для переноса с тестовой на публичную среду
- Передайте владение GitHub проектом в организацию https://github.com/campus-mobile
- Вы останетесь в редакторах данного репозитория, но владельцем станет Кампус. Это нужно нам чтобы выполнять свои обязательства перед аудиторией Кампуса - если вы прекратите самостоятельно исправлять парсер, либо не будете успевать его обновлять под изменения в источнике расписания, то это сделает команда Кампуса.
- Команда Кампуса настроит автоматизацию для автоматического выполнения парсинга.
- Команда Кампуса заведет ваш ВУЗ на публичной среде и запустит ваш парсер работать с публичной средой.
Разработка парсера
Команда Кампуса использует Kotlin для разработки, поэтому мы предоставляем готовое SDK на этом языке. Если вы хотите реализовать парсер на другом языке - это возможно, но повышается сложность реализации (вам нужно будет работать напрямую с REST API, которое можно посмотреть здесь), а также повышается риск что команда Кампуса не согласится принять ваш код в свою поддержку, так как используемый язык недостаточно известен команде, чтобы его поддерживать.Принцип работы парсера следующий:
Сначала происходит получение списка сущностей (группа или преподаватель) - за это отвечает реализация интерфейса
EntitiesCollector
. В этой реализации вы можете прописать обращения к API или сайту вуза для сбора полного списка групп/преподавателей. Важно получать фиксированный ID сущности, чтобы изменение названия не создало дубликат расписания (расписание привязано к сущности).Далее для составления расписания нужны интервалы времени пар - за это отвечает реализация интерфейса
TimeTableIntervalCollector
. Данная реализация может быть фиксированной (возвращать просто список интервалов прописанный в коде), либо может обращаться к API/сайту ВУЗа, для надежности получения актуальных данных.Далее само расписание собирается в реализации интерфейса
ScheduleCollector
. На вход подается сущность, для которой собирается расписание, а также временные интервалы. В ответ данный компонент должен выдать список элементов расписания.Последний компонент - наследник от
BaseParser
, он соединяет все выше описанные компоненты в единую логику и именно он включается при запуске парсера.