API чата — документация разработчика
Сервис August4u, благодаря специальному API доступа к базе данных чата,
предоставляет средство для интеграции чата с собственными проектами клиентов. Таким образом, становится
возможным осуществлять авторизацию и регистрацию пользователей на внешнем, по отношению к чату, сервере.
Для получения доступа к API чата необходимо в Личном Кабинете активизировать услугу "API для внешнего сервера"
и установить на свой сервер пакет файлов. Ссылка на архив пакета находится в конце этой страницы.
Важно. Для работы API чата на сервере должен быть установлен интерпретатор PHP версии не ниже 5.0
с поддержкой cURL.
Пакет содержит 4 файла:
- include/august.inc.php — системная библиотека для доступа к API чата;
- include/settings.inc.php — системные настройки API;
- license.txt — текст лицензии на английском языке;
- license.ru.txt — текст лицензии на русском языке.
Для настройки библиотеки необходимо отредактировать файл настроек include/settings.inc.php,
выставив параметры в нужные значения. Определены следующие параметры библиотеки:
- SESS_NAME — определяет префикс имени php-сессии;
- CHAT_URL — домен вашего чата;
- SECRET_KEY — секретный ключ для доступа к API, ключ выдается в Личном Кабинете
после подключения услуги;
- AUTH_CHECK_IP — флаг (1 - включено, 0 - выключено), повышение безопасности php-сессий,
в некоторых случаях могут возникать проблемы (слетает авторизация), если провайдер изменяет IP-соединения
в течении сессии либо при плохой связи;
- AUTH_CHECK_NICK — флаг (1 - включено, 0 - выключено), дополнительная проверка ника на
правила чата для ника перед авторизацией.
Для подключения системной библиотеки к собственному проекту необходимо добавить в скрипты следующий код
include "include/august.inc.php";
startSess (SESS_NAME);
Если в Вашем скрипте используются свой механизм запуска сессии, то вызов функции
startSess (SESS_NAME) необходимо убрать.
Системные вызовы API
Вызовы API чата осуществляется функцией august(), функция принимает два аргумента: в первом
указывается название системного вызова, во втором передаются данные для этого вызова через
массив, где ключи массива — это имена переменных, а значения — это значения переменных.
В данный момент реализованы только два системных вызова:
- "auth" — авторизация пользователя;
- "register" — регистрация пользователя.
Авторизация пользователя
Системный вызов авторизации выглядит следующим образом:
$r = august ("auth", array (
'nick' => ...,
'pass' => ...,
'pass_key' => ...,
'check_nick' => ...
));
где переменные:
- nick — ник пользователя;
- pass — зашифрованный пароль (см. ниже);
- pass_key — ключ шифрования пароля;
- check_nick — флаг, включающий проверку ника соответствию правилам чата.
Функция возвращает результат вызова, который может быть следующим:
- функция вернула false — означает, что запрос не был успешным, вероятно, не удалось
соединиться с сервером чата;
- функция вернула массив — результат зависит от значений элементов этого массива, массив
состоит из двух элементов: ID и AuthKey.
Если элемент ID массива больше нуля, значит авторизация прошла успешно и ID является номером
профайла пользователя, а элемент AuthKey содержит секретный ключ, необходимый для перехода в чат
без повторной авторизации. Если элемент ID меньше или равен нулю, то авторизация прошла с ошибкой
и элемент ID содержит код этой ошибки. Возможны следующие коды ошибок:
- AUTH_PROFILE_NONE — ник не зарегистрирован;
- AUTH_PROFILE_ERROR1 — сработала защита от перебора, слишком много неудачных авторизаций за промежуток времени;
- AUTH_PROFILE_ERROR2 — сработала защита от перебора, слишком быстрая попытка повторной авторизации;
- AUTH_PASSWORD_ERROR — неправильный пароль;
- AUTH_PASSWORD_NONE — пароль не введен;
- AUTH_NICK_ERROR — недопустимый ник.
Шифрование пароля
Шифрование пароля осуществляется по следующему алгоритму:
- на сервере генерируется строка из случайных символов длинной 32 символа, эта строка является ключом
шифрования пароля, который затем передается системному вызову (переменная pass_key);
- пароль, введенный пользователем, хешируется функцией md5();
- захешированный пароль и ключ шифрования пароля объединяются друг с другом логической операцией XOR;
- полученная строка снова хешируется функцией md5() и результат передается системному вызову
в качестве зашифрованного пароля (переменная pass).
Регистрация пользователя
Системный вызов регистрации выглядит следующим образом:
$r = august ("register", array (
'nick' => ...,
'pass' => ...,
'email' => ...
));
где переменные:
- nick — ник пользователя;
- pass — пароль, захешированный функцией md5();
- email — секретный email для восстановления пароля к анкете.
Минимально необходимым для регистрации являются только две переменные: nick и pass.
Функция возвращает результат вызова, который может быть следующим:
- функция вернула false — означает, что запрос не был успешным, вероятно, не удалось
соединиться с сервером чата;
- функция вернула массив — результат зависит от значений элементов этого массива, массив
состоит из одного элемента: Profile.
Если элемент Profile больше нуля, значит регистрация прошла успешно и Profile является
только что зарегистрированным номером профайла пользователя. Если элемент Profile меньше нуля,
то регистрация прошла с ошибкой, определены следующие коды ошибок:
- -1 — передан пустой ник;
- -2 — в нике используется недопустимый символ;
- -3 — слишком короткий ник;
- -4 — слишком длинный ник;
- -5 — что-то не так с паролем;
- -6 — такой ник занят;
- -7 — системная ошибка;
- -8 — слишком много регистраций, защита от флуда
Класс auth
Более удобным способом авторизации пользователя является использование класса авторизации auth.
Класс auth является высокоуровневой оберткой над системным вызовом "auth" и предоставляет
некоторые дополнительные средства.
Конструктор класса auth
Конструктор класса auth может выполнять одну из двух функций, в зависимости от переданных аргументов:
- в объект загружается текущее состояние пользователя из сессии — для этого конструктор вызывается без аргументов;
- производится авторизация пользователя — для этого конструктор вызывается с двумя аргументами:
первый содержит ник пользователя, второй содержит пароль, зашифрованный по алгоритму, описанному выше.
Методы и свойства класса auth
- метод isAuth() — возвращает истину, если пользователь авторизован;
- метод id() — возвращает номер профайла авторизованного пользователя;
- метод nick() — возвращает ник авторизованного пользователя;
- метод auth_key() — возвращает секретный ключ авторизации пользователя, необходимый
для перехода с сайта в чат без повторной авторизации;
- метод get( $name ) — возвращает значение переменной $name объекта;
- метод set( $name, $value ) — устанавливает переменной $name объекта значение $value;
- метод logout() — завершает авторизацию пользователя;
- свойство ID — возвращает номер профайла авторизованного пользователя или номер ошибки при неудачной
авторизации.
Класс auth автоматически генерирует ключ пароля, который необходим для шифрования пароля, что
значительно упрощает весь механизм авторизации. Получить этот ключ можно, вызвав метод get('PassKey').
Пример использования класса auth
include "include/august.inc.php";
startSess (SESS_NAME);
$Auth = new auth;
if ($Auth->isAuth ()) {
// код для авторизованного пользователя
$Nick = $Auth->nick (); // ник пользователя
...
} else {
// код для неавторизованного пользователя
// здесь, например, можно выводить форму для авторизации, при этом
// необходимо получить ключ пароля через метод get()
$Key = $Auth->get ('PassKey');
...
}
Пример авторизации пользователя
include "include/august.inc.php";
startSess (SESS_NAME);
// ник и зашифрованный пароль передаются методом post
$Auth = new auth ($_POST ['nick'], $_POST ['pass']);
if ($Auth->Error) {
// авторизация прошла с ошибкой, код ошибки находится в свойстве ID
$Code = $Auth->ID;
...
} else {
// авторизация прошла успешно
$ID = $Auth->id (); // номер профайла пользователя
$Nick = $Auth->nick (); // ник пользователя
}
Регистрация и анкета
Регистрация пользователя не ограничивается только регистрацией ника и установки пароля, кроме этого можно
сразу передать значения полей анкеты. Данные анкеты должны передаваться через дополнительный массив
uf[]. На примере становится более понятен принцип заполнения анкеты.
Пример кода регистрации и заполнения полей анкеты имя, отчество, фамилия, день рождения и пол
$r = august ("register", array (
'uf[_0001]' => ...,
'uf[_0002]' => ...,
'uf[_0003]' => ...,
'uf[Day]' => ...,
'uf[Month]' => ...,
'uf[Year]' => ...,
'uf[Sex]' => ...,
'nick' => ...,
'pass' => ...,
'email' => ...
));
Ключи массива uf[] соответствуют полям таблицы базы данных чата, в которой хранится анкета и
служебная информация пользователя. Определены следующие имена полей таблицы:
- _0001 — имя пользователя;
- _0002 — отчество пользователя;
- _0003 — фамилия пользователя;
- Day — день рождения;
- Month — месяц рождения;
- Year — год рождения;
- Sex — пол;
Названия и значения других полей анкеты можно узнать, открыв исходный html-код страницы регистрации в чате.
Шаблон сайта
Для демонстрации использования API чата имеется два примера. Первый пример содержит шаблон сайта, который
позволяет авторизовывать и регистрировать пользователей. Сайт построен по образу официального сайта
Сервиса http://august4u.net/. На сайте применяется динамическая погрузка формы авторизации и титульного
меню, код которых зависит от состояния авторизованности пользователя на сайте (авторизован/не авторизован).
Пример сайта находится по адресу http://example.august4u.net/.
Второй пример содержит минимальный код сайта, необходимый только для авторизации пользователя. На этом
примере можно изучить принцип работы автоирзации. Этот пример расположен по адресу
http://example.august4u.net/simple.php.
Файлы
Пакет API чата:
Шаблон сайта: