Автоматизация использования Javascript API Вконтакте

Пару дней назад, как обычно, никого не поставив в известность, Контакт добавил возможность разработки приложений на JavaScript, подключаемых через iframe. Доступ к API в этих приложениях, в общем-то, такой же, как и доступ к API из Flash — так или иначе, это обычный REST-протокол. Параметры передаются через строку запроса GET, а результат возвращается в виде JSON или XML.

Одной из проблем использования API Вконтакте является передача кроссдоменного запроса на http://api.vkontakte.ru/api.php. Другая проблема — громоздкое вычисление подписи, которой необходимо подписывать все запросы.Первым делом, я, как и многие другие разработчики, взялся за jQuery. Однако, во-первых, использовать 68-килобайтную библиотеку ради всего лишь кроссдоменных запросов — это как стрелять из пушки по воробьям. Да и как-то громоздко получился вызов API-функций с использованием jQuery, так что пришлось от jQuery отказаться в пользу маленькой функции для кроссдоменных запросов. Ну и чтобы как-то упростить себе жизнь, я решил сделать небольшую библиотеку, которая бы не только загружала указанный URL с получением ответа сервера, но и выполняла бы самое неудобное во всем этом API — вычисление подписи.

С конечным результатом можно ознакомиться, перейдя по ссылкам в конце статьи, а я остановлюсь на отдельных моментах использования и реализации.

Для использования API Вконтакте, к HTML-документу приложения необходимо, для начала, подключить файл с библиотекой:

1. <!-- В данном случае, скрипт расположен в каталоге 
2.      с соответствующим HTML-файлом --> 
3. <script src="vk_api.js" type="text/javascript"></script> 

* This source code was highlighted with Source Code Highlighter.

Сама библиотека представляет собой один объект vk_api и функцию md5, честно позаимствованную мной из Webtoolkit. Объект vk_api сам по себе к использованию не готов — от него необходимо создать экземпляр при помощи конструктора:

1. var api = new vk_api(/* параметры */);

* This source code was highlighted with Source Code Highlighter.

В принципе, можно было бы выполнить всю инициализацию при загрузке самого скрипта vk_api.js, но это не путь самурая — а вдруг вызывать API в этом сеансе вообще не придется? К тому же, при инициализации конструктору передаются параметры, которые так или иначе необходимо где-то устанавливать и передавать скрипту.

Итак, попробуем создать объект:

1. //Создаем объект от vk_api(). Вся дальнейшая работа должна проходить 
2. //только с объектом api. 
3. var api = new vk_api( 
4.     //Это Секрет, он указан на странице редактирования приложения 
5.     'hGtsH5G0', 
6.  
7.     //Эта функция будет вызвана, если инициализация API пройдет успешно. 
8.     //Хорошее место для установки всех callback-функций через 
9.     //addCallback() 
10.     function() { 
11.  
12.         //Вызываем окно изменения настроек с отмеченными настройками для 
13.         //доступа к друзьям и к стене. Пользователь не сможет закрыть 
14.         //вызванное окно, пока не установит требуемые настройки. 
15.         api.makeSettings(api.SETT_FRIENDS | api.SETT_WALL); 
16.  
17.         //Добавляем функцию, которая запустится, если пользователь добавит 
18.         //приложение к себе на страницу. 
19.         api.addCallback( 
20.           'onApplicationAdded', 
21.             function() { 
22.                 //действия 
23.             } 
24.         ); 
25.     }, 
26.  
27.     //Эта функция вызывается, если инициализация API не состоялась. 
28.     //В этом случае, невозможно использовать внешние (external) вызовы. 
29.     function() { 
30.         //сообщение об ошибке 
31.     }
32. );

* This source code was highlighted with Source Code Highlighter.

Как видите, все очень просто. Конструктору передается якобы секретный ключ (ага, секретный — в открытом виде представлен в коде страницы) и две функции, первая из которых выполняется в случае успешной инициализации, а другая — в случае возникновения ошибки при инициализации. На самом деле, вторая функция вовсе необязательна, если разработчик не хочет учитывать те единичные случаи, когда произойдет ошибка при инициализации. Кроме того, есть еще один параметр, который представляет собой обычный логический флаг, говорящий о том, включен ли режим тестирования.

Дело в том, что в режиме тестирования, у каждого вызываемого метода API, должен добавляться еще один всегда одинаковый параметр. Так что поддержка глобального однократного включения режима тестирования избавит разработчиков от лишних телодвижений при подготовке приложения к релизу — надо будет удалить всего один параметр конструктора, вместо правки множества вызовов API.

Если посмотреть пару тройку десятков приложений Вконтакте, то очень многие из них прямо таки требуют, чтобы пользователи их установили и разрешили им какие-то действия. Приложения в этом случае либо просто выводят сообщение с инструкцией о том, куда мне идти что надо сделать, либо, в лучшем случае, сразу отображают окно установки или изменения настроек. Ну грех было не реализовать подобные функции на уровне библиотеки. Причем, по просьбе одного человека, я ушел немного дальше, и реализовал указанные функции таким образом, что пользователь вообще не сможет закрыть окошко с предложением установить приложение или что-то ему разрешить, пока не согласится с требованиями приложения. Таким образом не надо предусматривать дополнительные страницы приложения для тех пользователей, которые отказались от установки или что-то приложению не разрешили — достаточно просто вызвать одну или две функции:

1. //Выводим окно с просьбой установить приложение
2. api.makeInstall();
3. api.addCallback(
4.     'onApplicationAdded',
5.  
6.     //Эта функция будет вызвана, когда пользователь установит приложение
7.     function() {
8.         $('#text').append('Application added\n');
9.         
10.         //Просим у пользователя разрешить приложению доступ к
11.         //друзьям и к публикации на стенах
12.         api.makeSettings(api.SETT_FRIENDS | api.SETT_WALL);
13.         api.addCallback(
14.          'onSettingsChanged',
15.  
16.             //Функция выполнится, когда пользователь изменит настройки приложения
17.             function(settings) {
18.                 $('#text').append('New parameters: ' + String(settings) + '\n');
19.             }
20.         );
21.     }
22. );

* This source code was highlighted with Source Code Highlighter.

Перейдем, наконец, к тому, ради чего приложение и разрабатывалось, т. е. непосредственно к вызову API-функций. Для этого предусмотрен метод call:

1. //Вызываем метод API через функцию call() 
2. api.call( 
3.  
4.     //Название метода API. 
5.     //Допустим, получение расширенной информации о профилях. 
6.     'getProfiles', 
7.  
8.     //Это объект с параметрами метода API. Если параметров нет, 
9.     //то этот аргумент можно не указывать. 
10.     { 
11.         uids: '4124584,2327412,1237975', 
12.  
13.         //Можно указывать массивы, которые будут автоматически 
14.         //преобразованы в строки. 
15.         fields: [ 
16.             'first_name', 'last_name', 'nickname', 
17.             'bdate', 'city' , 'country', 'photo' 
18.         ] 
19.     }, 
20.  
21.     //Эта функция будет вызвана, когда будет получен ответ от сервера. 
22.     //data - это готовый к использованию объект, созданный из строки 
23.     //JSON, полученной от сервера. 
24.     function(data) { 
25.         //Действия с объектом data 
26.     } 
27. );

* This source code was highlighted with Source Code Highlighter.

Как видите, все просто, и никаких лишних действий, что нам и нужно.

Что касается так называемого секретного ключа, передаваемого конструктору vk_api первым параметром, то для него я предусмотрел простейшее, даже не шифрование, а кодирование. Ключ в закодированном виде выглядит примерно так: sx--36l76l11l57l52l14l65l42l56l31l — вариация на тему кодов символов. Первые символы строки sx-- нужны для того, чтобы сохранить возможность передачи конструктору незакодированного секретного ключа — если строка начинается с sx--, значит, ключ закодирован, иначе ключ передан открытым текстом. Почему такое простое кодирование? Да потому что это защита от дурака, не более. От юного хацкера, только что прочитавшего очередную статью в известном журнале, этот метод поможет уберечься, а от квалифицированного разработчика, знающего основы JavaScript, никакое шифрование не спасет, потому что в конечном итоге, скрипту-то секрет нужен в открытом виде, а значит и функция для расшифровки должна быть в коде.

Собственно, ничего необычного в библиотеке-то и нет. Но от рутинной работы при разработке приложений, библиотека спасет. Как и обещал, ниже ссылка на скачивание.

Библиотека: vk_api-1.4.4.zip.
Страница проекта на Google Code: http://vk-jsapi.googlecode.com/
Новые версии и полное описание.