API «ВКонтакте»: разработка iFrame-приложений
АВТОР: Александр Зубаков Дата публикации: 13.04.2010

Недавно в самой популярной отечественной социальной сети «ВКонтакте» произошло то, чего долго ждали JavaScript-программисты; появилась возможность создавать iFrame-приложения, а для взаимодействия с API в этой сети теперь можно использовать не только Flash, но и JavaScript или любую другую клиентскую технологию.

В обзоре мы попытаемся разобраться в основных аспектах разработки iFrame-приложений для социальной сети «ВКонтакте», рассмотрим особенности использования API в JavaScript, коснемся процессов размещения и проверки ваших iFrame-приложений в социальной сети. Не обойдем вниманием и библиотеки независимых разработчиков, помогающие в использовании API «ВКонтакте».

Александр Зубаков, старший инженер по ИТ, http://xinit.ru, e-mail: Этот e-mail адрес защищен от спам-ботов, для его просмотра у Вас должен быть включен Javascript

Основа основ

Что же такое iFrame-приложения? iFrame-приложение в сети «ВКонтакте» — это обычная Web-страница, которая будет отображаться в так называемом «плавающем фрейме» (iframe) на странице приложения социальной сети. Эта страница должна быть размещена на вашем сервере, в Контакт ее закачать нельзя. В отличие от разработчиков Flash-приложений, нам нужно иметь свой сервер, что в принципе с лихвой компенсируется возможностью реализации всех преимуществ традиционных динамических Web-приложений.

iFrame-приложения могут состоять из одной или нескольких страниц. На страницах может быть как статический, так и генерируемый на сервере или создаваемый на стороне клиента при помощи технологии AJAX контент с использованием информации со своего и со сторонних серверов. На страницах приложения можно размещать не только HTML и JavaScript, но и Flash, Silverlight и даже Java-апплеты. iFrame-приложения могут использовать все преимущества и обычных методов API «ВКонтакте», и большинства интерактивных возможностей, ранее доступных лишь Flash-приложениям через Flash-контейнер.

API «ВКонтакте» вызывается отправкой запроса методом GET на адрес http://api.vkontakte.ru/api.php или http://api.vk.com/api.php в зависимости от того, под каким доменом работает пользователь. Интерактивные возможности интерфейса «ВКонтакте» вызываются путем использования объекта VK из библиотеки xd_connection.js, размещенной по адресу http://vkontakte.ru/js/xd_connection.js или http://vk.com/js/xd_connection.js.

Вызываем API

Несмотря на обилие клиентских технологий, в статье мы остановимся на использовании именно JavaScript, поскольку эта технология позволит реализовать все возможности «ВКонтакте». Кроме того, JavaScript — это старая и проверенная технология, широко используемая Web-разработчиками. Если вы читаете эту статью, значит, обладаете навыками работы с этим языком.

Дело в том, что API «ВКонтакте» — это полностью клиентская технология, работа с которой производится только со стороны клиента, т. е. непосредственно из браузера силами JavaScript или другой клиентской технологии. Есть и исключения, о которых вы можете узнать из официальной документации «ВКонтакте» на странице http://vkontakte.ru/pages.php?id=2372591. Пока запомните: с API «ВКонтакте» надо работать только со стороны клиента, так что не стоит пытаться вызывать методы API «ВКонтакте» с сервера, используя PHP, Perl или Python. Секрета в таком поведении «ВКонтакте» нет, дело в том, что при вызове методов API со стороны клиента сценарию «ВКонтакте», отвечающему за API, передаются файлы cookies пользователя, который в данный момент работает с приложением. Таким образом, Контакт может определить, какой именно пользователь работает с приложением и кто производит в приложении те или иные действия. Да и разработчику приложения так проще: не придется беспокоиться о безопасности, ведь Контакт уже сделал за нас всю работу.

Итак, понимая, что методы API надо вызывать со стороны клиента, а в нашем случае используя JavaScript, следует определиться со способом вызова. Проблема здесь в том, что необходимо совершать кроссдоменные запросы с сервера, на котором размещено приложение, на сервер «ВКонтакте». Универсальный вариант здесь пока один — JSON, т. е. способ передачи и получения данных со стороннего домена, используя HTML-тег <script> и специальным образом сформированный ответ сервера в формате JSON.

Чтобы лучше понять, о чем мы только что говорили, рассмотрим пример реального запроса. Допустим, нам необходимо узнать, установил ли пользователь приложение. Для этого существует специальный метод API «ВКонтакте» — isAppUser. Как видно из документации по этому методу (всю документацию по методам API вы можете найти на сайте «ВКонтакте» на странице http://vkontakte.ru/pages.php?id=2369282), никаких дополнительных параметров не требуется, а возвращаемое значение может быть лишь 1 или 0. Допустим, мы работаем с приложением из-под домена vkontakte.ru. Тогда, как уже было сказано выше, нам нужно будет методом GET передать запрос на адрес http://api.vkontakte.ru/api.php с указанием параметров, необходимых для успешного вызова метода isAppUser. Строка запроса будет выглядеть так:

Рассмотрим каждый параметр отдельно.

api_id — идентификатор приложения. Все приложения в сети «ВКонтакте» доступны по адресам вроде http://vkontakte.ru/app1833634 или http://vkontakte.ru/app1833634_4576857, в обоих случаях идентификатором приложения будет цифровая часть URL после /app, до конца URL или до символа «_», т. е. в приведенных примерах идентификатор приложения будет иметь значение 1833634.

v — версия API. Видимо, этот параметр сделан на будущее, для организации обратной совместимости при введении так давно и часто обещаемого администрацией «ВКонтакте» API версии 3.0. Пока параметр v может принимать лишь одно значение — «2.0».

method — собственно метод API «ВКонтакте», который мы хотим вызвать. В данном случае isAppUser.

format — формат возвращаемых данных. Может быть xml или json, а может и вообще отсутствовать (в таком случае данные будут возвращены в формате XML). Однако при использовании API из JavaScript параметр format всегда должен быть явно указан и иметь значение json.

sig — подпись запроса. Обязательный параметр для всех запросов, кроме тестовых, о которых мы поговорим чуть позже. Подпись представляет собой хэш, вычисленный по алгоритму md5, от строки, имеющей формат viewer_idname1=value1name2=value2secret.

Подробнее о способе формирования подписи можно прочитать на странице http://vkontakte.ru/pages.php?id=2369497 официальной документации. В нашем случае подпись будет вычисляться по следующей строке:

Здесь 5042864 — идентификатор пользователя, который в данный момент работает с приложением, т. е. ваш.

Heg54Jhgp4 — это так называемый секретный ключ. Узнать, а если надо и поменять его значение можно на странице редактирования приложения. Здесь нужно отметить, что ключ этот, несмотря на название, никакой не секретный, а скорее даже наоборот. Он специально создан для того, чтобы подписывать запросы на стороне клиента, а значит, потенциально доступен любому пользователю. Бояться этого не нужно. Дело в том, что, какой бы запрос к API ни сформировал злоумышленник, он сможет его выполнить только от своего имени! Именно здесь и открываются все преимущества передачи файлов cookies при использовании API на стороне клиента.

При вычислении подписи нужно запомнить важную особенность: параметры name=value идут в строке для вычисления подписи отсортированными в алфавитном порядке по возрастанию имен name.

callback — имя JavaScript-функции (так называемая callback-функция), которая будет вызвана сразу после того, как от сервера «ВКонтакте» придет ответ с результатами вызова метода API. В качестве единственного параметра функции будет передан объект, поля которого содержат информацию, пришедшую от сервера «ВКонтакте». Структура полученного объекта соответствует структуре JSON-объекта, передаваемого сервером «ВКонтакте» в ответ на вызов метода API, и описана в документации по каждому методу. Надо понимать, что callback-функция должна быть заранее объявлена и доступна в момент, когда от сервера «ВКонтакте» приходит ответ.

Упомянем еще один параметр, в данном запросе не присутствующий, — test_mode. Он может принимать значение 1 или 0 (по умолчанию) и существует почти для всех методов API «ВКонтакте». Если установить указанный параметр в значение 1, приложение будет запущено в тестовом режиме, т. е. не будет проводиться авторизация и проверяться подпись, а любой пользователь будет считаться администратором. В таком режиме доступны далеко не все возможности API «ВКонтакте». Теоретически этот параметр позволяет тестировать приложения в офлайновом режиме, т. е. не размещая их в «ВКонтакте», правда, на практике это просто не нужно, поскольку никто не мешает на время разработки организовать на своем компьютере HTTP-сервер, разместить на нем разрабатываемое приложение и указать его адрес в «ВКонтакте». Таким образом, приложение и будет разрабатываться на локальной машине, но без ограничений тестового режима.

Со строкой запроса вроде бы разобрались. Теперь осталось найти способ передать ее на сервер «ВКонтакте». Объект XMLHTTPRequest, обычно используемый для асинхронной передачи данных, имеет жесткое ограничение: он не поддерживает кроссдоменные запросы. Ранее мы говорили о JSONP — теперь посмотрим на него в действии! При необходимости отправить нашу строку запроса на сервер «ВКонтакте», необходимо, чтобы в HTML-коде страницы приложения оказался вот такой код:

Когда парсер браузера увидит этот код, он загрузит документ, размещенный по адресу, указанному в атрибуте src, на каком бы сервере документ ни находился. Естественно, будут переданы все параметры GET-запроса.

Но как известно, сервер «ВКонтакте» в ответ на вызовы методов API возвращает ответ в формате JSON или XML, что зависит от параметра format. В нашем примере ответ придет в формате JSON, а именно вот такой:

Что же будет, когда к основному HTML-документу приложения будет подключен скрипт такого вида? Ответ предельно прост — ничего! Мы никак не сможем воспользоваться этими данными. Но не все потеряно: на помощь приходит параметр callback. Ведь если этот параметр присутствует в строке запроса вместе с параметром format, равным json, ответ от сервера «ВКонтакте» придет немного в другом формате. Для нашего примера ответ будет таким:

А от исполнения такого кода мы уже сможем получить кое-какие дивиденды. Ведь если мы где-то до вызова метода API объявим функцию parseJSON(), то в качестве ее параметра получим ответ сервера «ВКонтакте», которым уже сможем воспользоваться. В следующем примере функция parseJSON() просто сообщит пользователю, установлено ли у него приложение.

Все это, конечно, хорошо, но тег <script> как-то должен оказаться на странице приложения. Можно вставить его туда на стадии разработки, но это не всегда удобно потому что часто надо вызывать методы API не при загрузке страницы, а в результате каких-либо действий пользователя. Благо, осуществить это довольно просто при помощи JavaScript — нужно лишь добавить к DOM документа объект HTMLScriptElement с соответствующими атрибутами. А сделать это можно при помощи простейшей функции (см. листинг 1).

Листинг 1.

Собирая воедино все сказанное выше, попробуем вызвать метод isAppUser, когда пользователь нажмет на ссылку (см. листинг 2).

Листинг 2.

Но помните, что не все методы API «ВКонтакте» одинаково полезны. Дело в том, что для использования некоторых методов требуется разрешение пользователя. Ну действительно, вам бы хотелось, чтобы приложение без вашего ведома оставляло на стене сообщения или изменяло ваш аватар? Думаю, что нет. И это надо помнить, работая с некоторыми методами API. Мы рассмотрим, как попросить у пользователя разрешения на выполнение таких «опасных» методов, но немного ниже.