Обзор API социальной сети ВКонтакте

 

Использование Flash-контейнера

 

Для более тесной интеграции приложения c пользовательским интерфейсом ВКонтакте, предусмотрена возможность использования Flash-контейнера. После его включения SWF-приложение показывается пользователям не напрямую, а через SWF-обертку, которая в свою очередь выполняет функцию предзагрузчика и предоставляет методы для взаимодействия с внешним интерфейсом.  

Если приложение написано на Actionscript 2.0, то Вы можете использовать альтернативный доступ к JS API через Flash-посредник.

Возможности Flash-контейнера

На текущий момент Flash-контейнер  предоставляет следующие возможности:

• Открытие окон установки приложения, настроек, приглашения друзей и ввода голосов для оплаты услуг.
• Получение событий об успешной установке приложения пользователем, изменении настроек и баланса пользователя внутри приложения.
• Динамическое изменение размера окна приложения.

 

Как использовать Flash-контейнер?

Включить Flash-контейнер можно  на странице редактирования приложения. Но прежде чем включать эту возможность, необходимо подготовить приложение для корректной работы с контейнером.  
 
Для получения ссылки на объект, содержащий в себе необходимые методы и данные, необходимо выполнить следующую операцию:

var wrapper: Object = Object(parent.parent);

 
Все дальнейшие действия будут выполняться  с полученным объектом wrapper.  
 
Необходимо учитывать, что объект parent.parent становится доступен только после полной загрузки SWF-файла. Поэтому обращаться к этому объекту можно не раньше, чем сработает событие Event.ADDED_TO_STAGE.

 

 

 

Пример кода инициализации приложения

this.addEventListener( Event.ADDED_TO_STAGE, onAddedToStage );  
...  
function onAddedToStage(e: Event): void {  
var wrapper: Object = Object(parent.parent);  
// Init application  
}

 

Описание методов Flash-контейнера

Объект wrapper имеет следующие поля:

• wrapper.application – содержит свойства для изменения и получения настроек главной сцены.
• wrapper.external – содержит методы для осуществления внешних вызовов.

 

4.2.  IFrame-приложения.

Пользователь может создать любое интегрированное приложение, загружаемое с Вашего сервера с помощью встроенного на страницу ВКонтакте элемента IFrame. Такие приложения могут отображать информацию с помощью любых технологий, поддерживаемых браузером пользователя: HTML, Javasсript, AJAX, Flash и др.

Аналогично переменным flashVars, передаваемым во Flash-приложение, в IFrame-приложение эти переменные передаются посредством GET-параметров запроса.

 

Использование Javascript API в IFrame-приложении

Для более тесной интеграции IFrame-приложения c пользовательским интерфейсом ВКонтакте, предусмотрена возможность использования Javasсript API, который позволяет выполнять следующие функции:

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

 

Инициализация Javascript API

1. Необходимо добавить ссылку в код Вашей страницы:

<script src="http://vk.com/js/api/xd_connection.js?2" type="text/javascript"></script>

 
2. После загрузки страницы для  инициализации приложения можно  использовать следующий код: 

<script type="text/javascript">

  VK.init(function() {

     // API initialization succeeded

     // Your code here

  });

</script>

 

Методы Javascript API

Все нижеперечисленные методы доступны в контексте глобального  объекта VK, создаваемого в результате подключения файла xd_connection.js к странице приложения.

Название метода	Параметры	Описание
init	[Function success]	Инициализирует соединение с родительским окном для запуска  внешних вызовов. При успешной инициализации  соединения вызывается функция success.
callMethod	String name, Object param1, Object param2, ...	Осуществляет внешний  вызов метода javascript API
addCallback	String name, Function callback	Добавляет функцию callback в качестве обработчика события name.
removeCallback	String name, Function callback	Удаляет обработчик события name.
api	String method, Object params, Function callback	Выполняет запрос к ВКонтакте API и передаёт полученные данные в функцию callback.

 

 

Обработка событий

В результате совершения пользователем  каких-либо действий на странице с приложением, родительское окно создает события, которые можно отслеживать с  помощью функции VK.addCallback(String name, Function value). В таблице ниже приведен список таких событий.

Название события	Параметры	Описание
onApplicationAdded	–	Событие происходит, когда  пользователь добавляет приложение к себе на страницу.
onSettingsChanged	int settings	Событие происходит, когда  пользователь изменяет настройки приложений. Параметр settings передаваемого объекта в функцию обратного вызова содержит в себе битовую маску выставленных значений настроек. Подробнее о значении параметра настроек в описании метода getUserSettings.
onBalanceChanged	int balance	Событие происходит, когда  пользователь положил или снял голоса с баланса приложения. Параметр balance содержит текущий баланс пользователя в сотых долях голоса. Этот параметр можно использовать только для вывода пользователю. Достоверность баланса всегда нужно проверять с помощью метода secure.getBalance.
onOrderCancel	–	Событие происходит, когда  пользователь отменяет покупку.
onOrderSuccess	int orderId	Событие происходит, когда  покупка закончилась успешно.
onOrderFail	int errorCode	Событие происходит, когда  покупка закончилась неуспешно.
onProfilePhotoSave	–	Событие происходит, когда  пользователь подтвердил сохранение фотографии в окне, вызванном с помощью  функции showProfilePhotoBox.
onWallPostSave	–	Событие происходит, когда  пользователь подтвердил публикацию записи на стене в окне, вызванном с  помощью функции showWallPostBox.
onWallPostCancel	–	Событие происходит, когда  пользователь отменяет публикацию записи на стену.
onWindowResized	int width, int height	Событие происходит, когда  размер окна приложения был изменен. Параметры width и height содержат новые размеры приложения в пикселах.
onLocationChanged	String location	Событие происходит, когда  изменяется значение хеша после символа # в адресной строке браузера. Например, это происходит в результате использования кнопок "назад" и "вперед" в браузере. Данное событие происходит всегда при запуске приложения.
onWindowBlur	–	Событие происходит, когда  окно с приложением теряет фокус. Например, когда пользователь открывает  окно с настройками приложения.
onWindowFocus	–	Событие происходит, когда  окно с приложением получает фокус. Например, когда пользователь закрывает  окно с настройками приложения.
onScrollTop	int scrollTop, int windowHeight	Событие происходит, когда  вызывается метод scrollTop. Параметр windowHeight - высота окна в браузере.
onScroll	int scrollTop, int windowHeight	Событие происходит, при  прокрутке пользователем страницы. Для того, чтобы подписаться на данное событие - необходимо вызвать метод scrollSubscribe. Параметр windowHeight - высота окна в браузере.
onToggleFlash	bool show	Событие происходит, когда  открывается всплывающее окно, и  flash компоненты в приложении у которых нет возможности установить wmode="opaque" необходимо спрятать, параметр show - определяет, какое действие необходимо произвести с компонентами, спрятать или показать.

 

Пример выполнения запроса  к API:

VK.api("getProfiles", {uids:"1,2,3,4"}, function(data) {  
    // Действия с полученными данными  
});

3. Standalone-desktop приложениея для API Вконтакте.

Для доступа к API ВКонтакте из любого Standalone-приложения предусмотрен механизм клиентской авторизации на базе протокола OAuth 2.0. В качестве клиента может выступать любое Desktop/мобильное приложение, имеющее доступ к управлению Web-браузером. Standalone/Mobile-приложениях и сайтах, а также серверных частях любых типов приложений перед вызовом большинства методов API необходимо проводить авторизацию пользователя (или приложения). Существует два вида авторизации:

• Авторизация OAuth (клиентская и серверная). Механизмы авторизации хотя и схожи для Standalone/Mobile-приложений и для сайтов, но имеют и отличия, которые делают их не взаимозаменяемыми.
• Авторизация Open API (только клиентская). Доступна только для сайтов.

После авторизации определяется уровень прав приложения, в зависимости  от которых приложение может совершать  только строго определенные действия, а также выдаётся ключ доступа access_token, c помощью которого можно выполнять любые запросы к API ВКонтакте от имени пользователя или от имени приложения.

Для написания своего приложения пользователю вначале необходимо зарегистрировать его. Для этого необходимо зайти в раздел «Разработчикам» на сайте Вконтакте и выполнить регистрацию нового приложения. В этом случае приложению будет присвоен id, который впоследствии будет использоваться при авторизации.

В качестве языка программирования был выбран C# в силу его гибкости и удобства при написании Web-приложений.

Для работы с API Вконтакте приложению необходима авторизация. Сделать это можно посредством компонента WebBrowser. Подключив данный компонент, ему можно передать ссылку следующего вида:

https://oauth.vk.com/authorize?client_id=Your_App_Id&redirect_uri=https://api.vk.com/blank.html&scope=Your_Scope&display=popup&response_type=token

В данной ссылке на сервер авторизации  Вконтакте передаются следующие параметры:

• client_id - id приложения, которое выдается при регистрации приложения в Вконтакте;
• redirect_uri - адрес, на который будет переадресован пользователь после прохождения авторизации (домен указанного адреса должен соответствовать основному домену в настройках приложения). Если  разрабатывается Standalone-приложение и параметр response_type = "token", то в качестве параметра redirect_uri необходимо указывать адрес https://oauth.vk.com/blank.html, на который будут переданы данные авторизации. В данном случае появляется возможность использовать расширенные методы работы с API.
• scope - битовая маска настроек доступа приложения, которые необходимо проверить при авторизации пользователя и запросить, в случае отсутствия необходимых. Можно указывать в цифровом виде или названиями через запятую.
• display - тип отображения страницы авторизации. Поддерживаются следующие варианты:
• page – форма авторизации в отдельном окне
• popup – всплывающее окно
• mobile – авторизация для мобильных устройств (без использования Javascript) .
• response_type - тип ответа:
• code если предполагается делать запросы со стороннего сервера (по умолчанию)
• token если предполагается делать запросы с клиента.

 

Окно авторизации в  этом случае будет выглядеть так, как показано на рисунке 1.

 

Рисунок 1. Окно авторизации приложения

 

В случае успешной авторизации необходимо подтвердить разрешения, выданные приложению, после чего оно получит доступ к данным. Используя GET-запросы к API, приложение может осуществлять широкий спектр действий. В данном примере приложение отправляет пост на стену пользователя, содержащий текст «test». GET-запрос в этом случае выглядит следующим образом:

https://api.vk.com/method/wall.post.xml?message=test&access_token=" + token

Здесь параметр method определяет метод API, которым будет пользоваться приложение. Следует заметить, что расширение .xml указывает в каком формате будет возвращен ответ – в xml или json-формате (в случае отсутствия расширения .xml). После указания метода необходимо указать параметры, которые передаются серверу. В данном случае достаточно передать один параметр – сообщение, которое будет размещено на стене пользователя. Для того, чтобы сообщение было размещено необходимо подтвердить, что оно было отправлено от авторизованного приложения. Для этой цели в запросе указывается параметр access_token, который приложение получает сразу после успешной авторизации. Поэтому данный access_token необходимо сохранять на все время сеансовой сессии.

 

Заключение

 

API Вконтакте предоставляет широкие возможности для работы с данными, а также простые и удобные механизмы для взаимодействия со сторонними программами. Это позволяет создавать различные приложения, использующие этот API, практически на всех распространенных и популярных языках программирования (Java, C++, C#, PHP и т.д.) на всех платформах, включая мобильные (Windows 7/8, Android, IOS), что, возможно, и является одной из причин роста популярности социальной сети Вконтакте.

 

Список использованной литературы:

1. Документация для разработчиков ВКонтакте:

URL: http://vk.com/development/

 

2. VKontakte API:

 

URL: http://habrahabr.ru/hub/vkontakte_api/

 

3. API:

URL: http://wikipedia.org/