От разработчиков — разработчикам

Приветствуем всех наших коллег - разработчиков приложений! Специально для вас мы открываем интерфейс программирования приложений для социальной сети вКругуДрузей. Вы можете создать приложение и использовать API вКругуДрузей для обмена данными с нашими серверами.

Группа поддержки разработчиков: API.vkrugudruzei.ru

Спецификация команд 10.04.2012: скачать

API вКругуДрузей

Адрес сервиса API вКругуДрузей: http://api.vkrugudruzei.ru/servicepoint.ashx.

API представляет собой набор команд, объединённых в группы (сервис-классы). Команда идентифицируется полным именем: Имя_Сервис_Класса.Имя_команды. За один http-запрос (GET или POST) можно вызывать любое количество команд. Увидеть описание всех доступных команд и протестировать их работу можно в браузере сервис-классов: SCE.

Параметры запроса к АPI

• cmd1.name, cmd2.name..., cmdN.name- идентификаторы команд, для выполнения
• cmd{i}.args.paramName1, cmd{i}.args.paramName2,.... cmd{i}.args.paramNameN - параметры команд
• serializer- определяет формат ответа, возможны три значения:
  • SimpleXml - простой XML (используется по умолчанию)
  • JSON - JSON
  • JSONDateISO - JSON, в котором дата выводится в ISO формате вида "2008-09-09T13:17:00.0000000Z"
  • DataContractXMLFormatter - сложный XML (удобен для использования в .NET приложениях)
• deserializer- определяет формат входных данных, необходим только для POST запросов, возможно одно значение:
  • HTTP_POST_Form_Deserializer- входные параметры должны раполагаться в полях формы (!не в строке запроса)

Типы команд

1. Открытые

Эти команды не требуют никаких параметров защиты. Вы можете выполнять их как со своих серверов, так и с клиентов.

2. Требующие сессию пользователя

Эти команды можно вызывать только из-под аккаунта вКругуДрузей. Вы можете их протестировать в SCE(для текущего аккаунта). Программный вызов возможен только с клиентов через JavaScript и Flash посредники.

3. Требующие подпись приложения

При вызове этих команд необходимо в http-запросе дополнительно передать два параметра: appid- идентификатор вашего приложения и appsig- подпись.

Подпись вычисляется как MD5 хэш строки вида: appid&appsecretkey&cmdname1&argname&argname&cmdname2&argname&argname , где appsecretkey- секретный ключ приложения; имена команд сортируются по алфавиту; имена аргументов сортируются по алфавиту.

Например, для запроса:

http://api.vkrugudruzei.ru/servicepoint.ashx?cmd1.name=Application.WithdrawUserMoney&cmd1.args.userId=23424&cmd1.args.money=2&appid=100&appsig=6c82cbd79794f002dae7bf86cb5f6e5d

Команды данного типа предназначены для вызова с сервера. Вызов с клиентов также возможен, но этого делать не рекомендуется из-за соображений безопасности.

Формирование URL изображений

Например, в результате выполнения команды, получена ссылка:
http://img31.vkrugudruzei.ru/images/025/288/47/ca481a06ec1541c78ee3c36df86db10c_{0}.jpg
Часть "{0}" необходимо заменить на один из имеющихся типоразмеров - avatar, ico, small, med, big. Соответственно, поулучаем 5 возможных URL изображения:

• http://img31.vkrugudruzei.ru/images/025/288/47/ca481a06ec1541c78ee3c36df86db10c_avatar.jpg
• http://img31.vkrugudruzei.ru/images/025/288/47/ca481a06ec1541c78ee3c36df86db10c_ico.jpg
• http://img31.vkrugudruzei.ru/images/025/288/47/ca481a06ec1541c78ee3c36df86db10c_small.jpg
• http://img31.vkrugudruzei.ru/images/025/288/47/ca481a06ec1541c78ee3c36df86db10c_med.jpg
• http://img31.vkrugudruzei.ru/images/025/288/47/ca481a06ec1541c78ee3c36df86db10c_big.jpg

Аутентификация пользователя

Существует возможность несанкционированного запуска приложения, через подмену параметра userId, переданного через flashVars или url. Для проверки пользователя, запустившего приложение, используйте команду bool Application.UserIsValid(int userId, Guid userSig)
userId, userSig- параметры, переданные в приложение при запуске.

Приложения вКругуДрузей

• iFrame приложения
• Flash приложения

<script type="text/javascript" src="http://vkrugudruzei.ru/x/content/jscript/trunk/jsapi/xfr.js"></script>

function(data){
    data.result == "complete"; // Успешное выполнение
    data.result == "cancel"; // Отмена действия пользователем

    data.result == "error"; // Ошибка при попытке отображения окна
        data.message;       // Сообщение с ошибкой
    
}

vkdr.app("showInstallBox", {}, function(data){
    data.result == "complete"; // Установка приложения
});

vkdr.app("showSettingsBox", { settings: 1 }, function(data){
    data.result == "complete"; // Сохранение настроек
});

vkdr.app("showInviteBox");

vkdr.app("showPaymentBox", { coins: 13 }, function(data){
    data.result == "complete"; // Оплата прошла
});

vkdr.app("showShareFriendsBox", { 
    message: "hello, world!", 
    imageName: "image.png" 
}, function(data){
    data.result == "complete"; // Запись опубликована
});

vkdr.app("showWallPostBox", { 
    userId: 4351810,
    message: "hello, world!", 
    imageName: "image.png" 
}, function(data){
    data.result == "complete"; // Запись опубликована
});

vkdr.app("reload");

vkdr.app("resize", { 
    width: 1152, 
    height: 864 
}, function(data){
    data.width <= 1152; // Ширина и высота
    data.height <= 864; // полученные после изменения размеров
    data.maxWidth; // Ширина и высота
    data.maxHeight; // доступный максимум
});

vkdr.app("fullscreen", {}, function(data){
    data.width <= 1152; // Ширина и высота
    data.height <= 864; // полученные после изменения размеров
    data.maxWidth; // Ширина и высота
    data.maxHeight; // доступный максимум
});

vkdr.app("setTitle", { title: "hello, world!" });

vkdr.addEvent("applicationAdd", function(){
    // do smth
});

vkdr.addEvent("settingsChange", function(data){
    data.settings;
});

vkdr.addEvent("balanceChange", function(data){
    data.balance;
});

vkdr.addEvent("appStateChange", function(data){
    data.size.width;
    data.size.height;
    if(data.background == false)
        // приложение видно пользователю
    else
        // например, открыто окно добавления записи в гостевую
});

// В данном примере событие сработает, 
// только когда изменится свойсво background
// остальные свойства будут также доступны
vkdr.addEvent("appstateChange:background", function(data){
    data.background == true;
});

// Cработает, только когда изменится размер окна браузера
vkdr.addEvent("appstateChange:maxSize", function(data){
    data.maxSize;
});

vkdr.addEvent("wallPostSave", function(){
    // do smth
});

vkdr.addEvent("wallPostCancel", function(){
    // do smth
});

vkdr.addEvent("shareFriendsSave", function(){
    // do smth
});

vkdr.addEvent("shareFriendsCancel", function(){
    // do smth
});

vkdr.addEvent("windowBlur", function(){
    // do smth
});

vkdr.addEvent("windowFocus", function(){
    // do smth
});

{
max: {width, height}, 
current: {width, height}
}

vkdConnection.addEventListener(SettingsEvent.SETTINGS_CHANGED, onSettingsChanged);
//... 
function onSettingsChanged(e: SettingsEvent): void { 
var settings: uint = e.settings;
// do something
}