QRLock.ME documentation
I apologize to English-speaking users, but the documentation is only available in Russian so far.
Установка
Что требуется для установки/подключения сервиса QRLock.ME
- Хостинг: практически любой, включая VPS/VDS/Shared, важно только чтобы поддерживалась работа скриптов.
- Язык скриптов: любой (PHP если не хочется переписывать код или практически любой другой скриптовый язык).
- База данных: не требуется.
- Доп. требования: нет
Мы подготовили для вас набор файлов, в которых расположены примеры с этого сайта. Эти файл можно скачать по следующим линкам:
На сегоднашний день примеры реализованы на языке PHP с использованием Javascript и Twitter Bootstrap. Однако нет никаких привязок ни к языку программирования, ни к используемому языку разметки. Просто с PHP будет проще начать. Однако если вы программист и разбираетесь (хотя бы минимально) в WEB-технологиях, вам не составит труда написать все эти примеры на своем языке. Система построена на API (собственном) и не имеет жостких привязок к языку программирования и технологиям. Так же система подразумевает последующее развитие и мы не даем гарантии что в будщем она будет работать точно так же как сегодня, однако мы планируем поддержать версионность изменений протокола по принципу "обратной совместимости", т.е. новые версии протокола будут поддерживать старые (мы надеемся на это :) ). Итак, мы подразумеваем что вы скачали и распаковали архив с файлами примеров и готовы их размещать на своем сервере (сайте). Кратко по назначению файлов из архива:
- qrlock.api\qrlock.php - "библиотека" qrlock. Собственно это не библиотека, а набор параметров и функций, которые нет нужды менять для запуска примеров и они вынесены в отдельный файл для удобства. Может располагаться где угодно (даже вне пределов document root вебсервера, впрочем как и все остальные файлы из данного каталога), во всех других файлах надо будет просто указать к нему путь.
- qrlock.api\qrlock.cfg.php - главный файл, который нужно менять. В нем расположены основные параметры для вашего аккаунта. См. комментарии внутри файла.
- qrlock.api\qrlock.default.tpl.php - "простой" темплейт. Минимальный темплейт (минимум дизайна). См. комментарии внутри файла.
- qrlock.api\qrlock.modern.tpl.php - "продвинутый" темплейт, с блоком пояснений (для пользователя сайта, на английском) и ссылкой для скачивания сканера QR-кодов.
- demo\connector.php - основной файл из данного каталога. Должен располагаться так, чтобы была возможность вызова его по протоколу HTTP (вызывается из рабочих скриптов). В нем содержится логика работы по общению вашего сервера с нашим в направлении "от вас - к нам". См. комментарии внутри файла.
- demo\index.php - главный пример работы сервиса. Данный файл домнстрирует как работает сервис. Для работы сервиса на вашем сервере уже не будет нужен и вся логика из этого файла должна быть перенесена к вам в проект. См. комментарии внутри файла.
- demo\demo.simple.php - полностью аналогичен предыдущему файлу, отличается от оного только отсуствием комментариев и одной строкой, в которой меняются параметры вызова функции отрисовки блока с QR-кодом.
- demo\10x.php - необязательный файл, содержимое его вообще произвольно, в рабочей версии может вообще отсутствовать. В рамках данных примеров открывается на мобильном устройстве с целью показать пользователю что все работает. Может быть размещен где угодно, даже на другом сервере. Может быть даже простым html-файлом.
Описание цикла работы
Цикл работы сервиса выглядит следующим образом:
- При открытии страницы с контентом (с вашего сервера) в код страницы помещается необходимое дополнение
в виде скрипта JavaScript и некоторых элементов дизайна, использующих разметку HTML/CSS. В приведенных примерах это делается автоматически
(используя нашу "библиотеку", написанную на PHP), в идеале лучше всего делать это самому ибо знание своего дизайна, настроек сервера,
использования ресурсов и разметки ваших страниц - это ваше дело и мы не можем построить наши примеры так, чтобы они работали на всех
серверах и сайтах одинаково.
Главное в том что этот код выполняет вызов файла connector.php (через JavaScript) с нужными параметрами. - При вызове файла connector.php (который, как мы писали ранее может называться как угодно и даже может
быть написан на любом другом языке) внутри этого файла формируется пакет для обращения к нашему серверу и отправляется на наш сервер.
После этого он регистрируется в нашей базе данных, из которой возвращается картинка с QR-кодом и токен, по которому можно отслеживать
в дальнейшем состояние данной регистрации (открыта, произведен переход пользователя, пользователь нажал кнопку на мобильном устройстве,
пользователь увидел новый контент) и код на сайте переходит в режим ожидания.
Замечание: схема с вызовом файла connector.php на вашем (!) сервере была выбрана во-первых, по причине того чтобы скрыть от посетителя сайта логику получения контента, во-вторых, чтобы скрыть ваши ключи АПИ к нашему сервису, а в третьих, чтобы иззбежать вызовов кросс-доменных соединений в JavaScript (запрещенных по умолчанию), которые безусловно возможны, но требуют еще большего усложнения схемы работы. В дальнейшем это всеравно будет реализовано, например запланирована работа по переходу на работу с WebSocket-ами, но сейчас это пока только в планах дальнейшей разработки. - После того как картинка с QR-кодом получена, токен так же получен, код на сайте начинает ожидать дальнейших действий пользователя. Все дальнейшее происходит автоматически (!) по отношению к сайту. Ничего на сайте нажимать или вводить не нужно (это надо как-то доносить пользователю чтобы он это понимал, для этого в одном из наших примеров присутсвтует краткое описание процесса).
- Пользователь сканирует QR-код и у него в телефоне (планшете) открывается сайт нашего сервиса с некоторым количеством кнопок с различными пин-кодами. Почему их несколько? Все дело в том что нам необходимо отделить случаи, когда один и тот же контент открывают различные пользователи на разных компьютерах. Да, в большинстве случаев такое совпадение маловероятно (осбенно на малонагруженных сайтах), однако на большинстве сайтов это будет не так. Поэтому пользователю на вашей странице выдается уникальный пинкод, который он должен будет выбрать из нескольких предложенных на мобильном устройстве. В случае правильного выбора, код, расположенный на сайте, получит эту информацию и обновит данные на странице, показав скрытый контент, а на мобильном устройстве пользователь увидит новую (а может увидеть и старую, все решает вебмастер сайта) страницу или даже может быть отправлен на какой-то сторонний сервис для дальнейшей монетизации его посещения.
- После нажатия пользователем правильного пинкода (если он выберет неправильный, ему об этом сообщат и предложат ввести правильный) процесс завершается и наш сервер рапротует вам об этом двумя способами. Первый - это тот, который обрабатывается кодом на сайте (как описано выше), второй - это наш сервер делает вызов вашего callback url (который задается при регистрации аккаунта) с параметром в виде токена (про который рассказывалось выше). Можно не задавать callback url, тогда этот вызов делаться не будет. Но это полезно если вам требуется выполнить какие-то действия на сервере после выполнения цикла показывания контента (удаление временных файлов, пометка о том что контент был открыт, подсчет статистики и пр.).
Файлы примеров
Далее приведены файлы примеров с комментариями