vk-apps-launch-params

Информация о параметрах запуска на платформе VK Mini Apps.

Оглавление

• Основная информация
  • Как параметры запуска попадают в приложение
  • Аутентификация пользователей на сервере
• Передача параметров запуска на сервер
  • Cons
  • Pros
• Примеры проверки подписи на различных языках
  • PHP
  • Java (1.8)
  • Python 3
  • Node
  • TypeScript

Основная информация

Приложение VK Mini Apps получает от ВКонтакте параметры запуска. Они могут содержать различную информацию: место запуска (каталог приложений, сообщество, обычное открытие по ссылке и т.д.), идентификаторы пользователя и приложения, включены ли у пользователя уведомления, какой выбран язык и многие другие. С полным списком параметров запуска можно ознакомиться в официальной документации.

Как параметры запуска попадают в приложение

Каждый раз, когда мини-приложение запускается, ВКонтакте берёт указанный в настройках URL (или URL для разработки, если вы являетесь администратором приложения) и добавляет в конец строку поиска вместе с query-параметрами запуска. Таким образом, URL, доступный изнутри вашего приложения, будет иметь примерно такой вид:

https://example.com/?vk_app_id=111&vk_user_id=222&sign=mvkasjdl22Ds&...

Примечание:

Стоит помнить, что параметры запуска мини-приложения начинаются с префикса vk_. Но есть и дополнительный параметр — sign. Он отвечает за то, что все переданные параметры запуска являются валидными, то есть не подделаны. Как использовать sign рассмотрим ниже.

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

Параметры запуска имеют важную и полезную особенность — их можно использовать как аутентификационные данные на разработанном вами backend-сервисе. Это позволяет сократить время разработки и не утруждать себя написанием собственной системы аутентификации.

Вместе с параметрами запуска, как мы уже писали, передаётся sign — подпись, гарантирующая серверу корректность и правдивость параметров.

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

Передача параметров запуска на сервер

Для того чтобы получить список параметров запуска в строковом виде, достаточно обратиться к window.location.search:

// Используем slice(1), для того чтобы отбросить начальный знак вопроса.
const params = window.location.search.slice(1);

Если необходимо конвертировать параметры из строкового вида в объект, воспользуемся встроенной в node библиотекой querystring:

import qs from 'querystring';
// или
const qs = require('querystring');

const params = window.location.search.slice(1);
const paramsAsObject = qs.parse(params);

// Теперь мы можем использовать эти параметры как нам заблагорассудится.

Cons

Разработчики зачастую допускают ошибку, используя неявный и интуитивно непонятный explicit-метод передачи, — прикрепляемый браузером заголовок Referer, совпадающий с текущим адресом страницы.

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

Pros

Самым простым и корректным решением является явная передача своего заголовка и проверка его на серверной стороне.

import axios from 'axios';

// Создаём инстанс axios.
const http = axios.create({
  headers: {
    // Прикрепляем заголовок, отвечающий за параметры запуска.
    Authorization: `Bearer ${window.location.search.slice(1)}`,
  }
});

// Теперь при попытке сделать запросы при помощи ранее созданного инстанса
// axios (именуемого "http"), он будет автоматически прикреплять необходимый 
// нам заголовок, который мы сможем проверить на серверной стороне.

После того, как заголовок успешно прикрепляется, необходимо добавить его проверку на серверной стороне.

Примеры проверки подписи на различных языках

• PHP
• Java 1.8
• Python 3
• Node JS
• TypeScript
• GoLang