Руководство по использованию JS API

JS API предоставляет возможность разрабатывать приложения в Моем Мире и подключать внешние сайты с использованием JavaScript.

Библиотека позволяет осуществлять вызовы API прямо из браузера пользователя, минуя ваш сервер, помогая вам экономить трафик и вычислительные ресурсы. Кроме того, она дает доступ к некоторым возможностям, которые не доступны для вызова с сервера.

Подключение JS API

В IFrame-приложении или на внешнем сайте

Для использования JS API вам нужно:

  1. На домен вашего приложения или сайта загрузить файл receiver.html
  2. На вкладке Настройки IFrame управления приложением или в интерфейсе редактирования сайта указать адрес загруженного файла receiver.html
  3. Подключить загрузчик библиотеки, добавив следующий код в элемент <head> всех страниц, где вы хотите использовать JS API:
    <script type="text/javascript" src="http://connect.mail.ru/js/loader.js">
    </script>
  4. Загрузить библиотеку с помощью вызова функции mailru.loader.require(part, callback). Первым аргументом в нее передается часть библиотеки, которую надо загрузить (сейчас это только api). Второй аргумент — это функция, которая будет вызвана когда библиотека будет подгружена, выполняйте всю работу с API внутри этой функции
  5. Инициализировать библиотеку
    • для приложений: вызвав функцию mailru.app.init(private_key)
    • для сайтов: вызвав функцию mailru.connect.init(app_id, private_key)
  6. После инициализации вы можете использовать любые функции JS API для получения данных, поднятия диалоговых окон и другого интерактивного взаимодействия

Важно! Для корректной работы JS API на многостраничных приложениях необходимо передавать на внутренние страницы все GET-параметры, которые приложение получает на главной странице. Это не относится к сайтам.

Файл receiver.html

Файл receiver.html нужен для кроссдоменной передачи данных через JavaScript в старых браузерах. Он статический и мы не планируем его менять. Загрузите его на ваш сервер и он подойдет для всех приложений и сайтов, которые работают на одном домене.

Мы проверяем содержимое файла receiver.html на побитовое совпадение с оригиналом, поэтому размещать на сервере нужно исходный файл с нашего сервера, без обработки его текстовыми редакторами (они могут вставлять BOM или делать другие преобразования, которые приведут к ошибке при проверке ресивера).

Если вы разрабатываете приложение или сайт и ваше тестовое окружение не доступно из интернета, то мы не сможем проверить правильность файла receiver.html на ваших внутренних серверах и сообщим вам об этом в интерфейсе управления. Однако, адрес должен сохраниться в настройках и будет использоваться в работе JS API. Просто при выкладывании вашего проекта в публичный доступ проверьте, что receiver.html загружен и указан в настройках правильно.

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

  1. <html>
  2.   <head>
  3.     <script type="text/javascript" src="http://connect.mail.ru/js/loader.js">
  4.     </script>
  5.   </head>
  6.   <body>
  7.     <script type="text/javascript">
  8.        mailru.loader.require('api', function() {
  9.            mailru.app.init('ваш приватный ключ из настроек приложения');
  10.            // все готово, здесь можно работать с функциями API
  11.        });
  12.     </script>
  13.   </body>
  14. </html>

Пример кода сайта

  1. <html>
  2.   <head>
  3.     <script type="text/javascript" src="http://connect.mail.ru/js/loader.js">
  4.     </script>
  5.   </head>
  6.   <body>
  7.     <script type="text/javascript">
  8.        mailru.loader.require('api', function() {
  9.            mailru.connect.init('app_id из настроек сайта',
  10.                                'ваш приватный ключ из настроек сайта');
  11.            // все готово, здесь можно работать с функциями API
  12.        });
  13.     </script>
  14.   </body>
  15. </html>

Во Flash-приложении

Вы можете использовать все функции JS API внутри Flash части вашего приложения. Для этого мы создали Flash API — ActionScript прослойку для вызова функций JS API. Подробнее о подключении и применении читайте на странице документации по Flash API.

Использование библиотеки

Функции JS API разделены на те, которые можно вызывать с сайтов, из приложений и общие функции (доступный и с сайтов, и из приложений). Функции для приложений сгруппированы в объекте mailru.app, для сайтов — mailru.connect, общие — в mailru.common.

Практически все функции работают асинхронно и возвращают результат не напрямую, а в функцию-коллбэк, которую надо указывать первым параметром. Обратите внимание, что перед использованием функций библиотеки надо провести ее инициализацию как описано выше.

mailru.session

Объект, в котором хранятся данные о сессии. Становится доступным после вызова mailru.app.init или mailru.connect.init

{
 app_id: "464119", // id вашего приложения
 exp: "1273243245", // срок действия сессии
 ext_perm: "notifications", // разрешения, данные пользователем вашему приложению
 is_app_user: "1", // установлено ли у пользователя приложение
                   // 1 - установлено, 0 - не установлено

 oid: "1324730981306483817", // id пользователя
 session_key: "28ec5ee94bb0fdd90e0a86b19317d860", // идентификатор сессии
 sig: "00c2bf2d9ec6334b92f3856351c6dd1a", // подпись запроса, настоятельно 
                                          // рекомендуем ее проверять на сервере при 
                                          // использовании данных для авторизации

 ss: "d41d8cd98f00b204e9800998ecf8427e", // не используется
 state: "", // не используется
 vid: "1324730981306483817" // id текущего пользователя, который вы можете 
                            // использовать для авторизации
}

Про различие между vid и oid читайте в руководстве по социальным приложениям. Для внешних сайтов oid всегда равен vid.

Работа с событиями

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

Для работы с событиями используйте функции events.listenjs и events.removejs. В документации функций, которые могут генерировать события, указано какие именно события генерируются.

Тестовое приложение

Функции JS API

Справочник по JS API

Другие технологии