Основное Редактировано: 28.08.2020 в 04:58

Познакомьтесь с Easy VK ближе, чтобы понять, как он устроен и как с ним работать

build state downloads issues minimal node version

# Концепция работы с Easy VK

Многие возможности Easy VK ограничены до тех пор, пока вы не авторизуетесь. Чтобы не нарушался концепт log-in, в Easy VK предусмотрен алгоритм последовательной авторизации. То есть, Вы не получите объекта для работы с ВКонтакте до тех пор, пока не произойдет корректная авторизация. Таким образом, внутри Easy VK гарантирует сам для себя, и для Вас, что все компоненты будут работать внутри одной сессии, не застрагивая посторонние (если такие имеются) программы и компоненты.

Но Easy VK не ограничивает Вас в возможностях, ведь иногда авторизация вообще не нужна, чтобы работать с некоторыми компонентами API ВКонтакте, такие, как Streaming API, Callback API и некоторые методы, которые не требуют access_token'а для обращения к ним.

# Первый шаг

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

Авторизация происходит таким образом

easyvk({
  password: "ваш_пароль",
  username: "ваш_логин",
  // или по токену
  token: '{ВАШ_ТОКЕН_ГРУППЫ_ИЛИ_ПОЛЬЗОВАТЕЛЯ}'
}).then(vk => {

  /* Теперь Вы можете работать с объектом EasyVK (vk)
    для обращения к методам API ВКонтакте и не только */
  
  // Пример
  vk.call('messages.send', {
    peer_id: vk.session.user_id,
    message: 'Привет!',
    random_id: easyvk.randomId()
  });

})

Это самый простой метод авторизации. Теперь я подробнее опишу как работать с функцией easyvk.

Функция easyvk принимает один единственный параметр - объект с настройками и возвращает объект <Promise>. Ниже описана каждая настройка и приведены примеры работы с ними

password, username *(<string>, [<string>, <number>])
Логин и пароль для авторизации. Используются совместно при условии, что не используется настройка token
```
{
  password: "exampleMyPassword$%!",
  username: "+79990000000" //Number(79990000000) или просто "email@exmple.com"
}
```
token *(<string>)

! Используйте только, если не указываете логин и пароль.

Токен доступа для группы или пользователя, далее, по нему будут делаться все запросы в этой сессии.
reauth (<boolean>) [false]
Если есть необходимость заново авторизоваться с новыми данными, или просто обновить токен текущей сессии, выставите этот параметр как true

С версии 2.4.0 сессия сменяется автоматически, если данные были изменены. Если данные не изменены, но, например, вы хотите получить новый токен, лучше всего для этого использовать reauth
v ([<number>, <string>]) [5.75]
Версия API ВКонтакте по умолчанию. Рекомендуется писать строкой
```
{
  v: '5.75'
}
  
```
mode ([<Object>, <string>])
Режим работы Easy VK

В Easy VK есть поддержка работы через метод execute - это, когда все запросы выполняются через данный метод. Это немного упрощает ответы (так как execute не является полным зеркалом запросов и ответов ВК API, в некоторых моментах), но и значительно улучшает работу с API ВК.

Почему highload?
Если вам нужно, чтобы все запросы выполнялись "в очереди" через один запрос к execute, вы не хотите нагружать свой сервер запросами или хотите сделать, чтобы ваш бот отвечал быстрее большему количеству людей, то этот режим работы вам точно подойдет
```
{
  mode: 'highload', // Самая простая настройка
  mode: {
    name: 'highload',

    // Каждые 15 МС вся очередь гарантированно будет выполняться (точнее читайте ниже)
    timeout: 15 
  }
}
      
```
Данный подход обещает выполнять сразу 25 запросов к API всего за один запрос к серверу. То есть, если 25 человек почти в одно и то же время написали боту (а такое происходит не редко), то вместо того, чтобы делать для каждого из них запрос к messages.send, отправится всего 1 запрос к execute с 25 запросами к messages.send

timeout - это время (МС), через которое вся очередь гарантированно выполнится, если не поступило новых запросов. Таким образом, настраивая этот параметр, вы настраиваете скорость обработки запросов. Чем меньше значение - тем больше запросов будет делать ваш сервер.
Когда вы обращаетесь к vk.call(), метод записывается в очередь по access_token'у вызываемого метода. Следующий запрос к vk.call() запишется в очередь к тому же токену (если он не изменился), но вся очередь выполнится только через timeout времени после последнего добавления запроса.

Настройка языка и версии API для внутренних запросов execute не поддерживается самим ВК. Поэтому в обращении к execute будет использована глобальная настройка params.lang и params.v

При общих ошибках каждый ответ запроса execute будет получать значение false (так устроено в ВК API). Поэтому, если вы хотите ловить ошибку, понимать, что произошло не так, рекомендуется иногда отключать режим, чтобы видеть полное описание ошибки.

Общие ошибки вроде капчи или flood control ВК возвращает с полным описанием, их будет получать самый последний reject, который был добавлен в очередь.
fields (<string>,<Array>) []
Список полей, которые Вы хотите сохранить в текущую сессию после авторизации

Во время авторизации происходит запрос на метод groups.getById, чтобы получить больше информации о группе и сохранить ее в сессию, и, кроме того, если идет авторизация пользователя, происходит запрос на метод users.get, оба этих запроса принимают единый параметр fields. Именно он и настраивается при авторизации.
```
easyvk({
  password: "{ПАРОЛЬ}",
  username: "{ЛОГИН}",
  fields: "photo_200,screen_name",
  // Можно использовать, как массив: ["photo_200", "screen_name"]
}).then(vk => {
  console.log(vk.session.photo_200) // Картинка, аватарка
})
```
Для авторизации приложения о значениях fields читайте на этой странице
sessionFile ([<string>]) [/node_modules/easyvk/src/utils/.vksession]
Путь к файлу сессии, в этот файл будет сохраняться сессия в JSON виде
```
const path = require('path')
const sessionPath = path.join(__dirname, '.session-vk')

easyvk({
  sessionFile: sessionPath
})
```
save (<boolean>) [true]

! Не сохраняйте сессию в пользовательские папки, которые доступны клиенту из браузера.

Нужно ли сохранять сессию в файл.
clear (<boolean>) [false]
Если есть необходимость отчистить файл сессии после авторизации, используйте эту настройку.
captchaHandler (<Function>) [-]
Функция для ловли ошибки капчи. Вы можете решать капчу любым удобным вам способом. Пример смотрите на странице Работа с капчей
platform (<string>) [android]
Название платформы, через которую будет проходить авторизация пользователя. Если у Вас есть собственное приложение, для которого нужно произвести авторизацию пользователя по логину и паролю, воспользуйтесь настройками clientId и clientSecret
```
{
  platform: ["android", "ios", "windows"][0] // НЕ МАССИВ! ТОЛЬКО СТРОКА!
}
```
clientId, clientSecret ([<number>, <string>], <string>)[-]
Если у Вас есть необходимость авторизовать пользователя по данным Вашего приложения, через Ваше приложение, укажите ID и SECRET код Вашего приложения в эти настройки

Кроме того, данные параметры используются для авторизации по методу Client Credentials Flow
lang (<string>) [ru]
Укажите язык по умолчанию, с которым будет работать Easy VK. Почти все ответы сервера ВК будут приходить на этом языке. Кроме того, сам Easy VK поддерживает мультиязычность и имеет перевод некоторых основных ошибок на два языка.
```
{
  lang: ["ru", "en", "uk", "kz"][0]
}
```
captchaSid ([<string>, <number>])
SID последней полученной капчи
captchaKey (<string>)
Текст с последней полученной капчи (для "решения" капчи)
proxy (<string>)
Прокси адрес для работы с ВКонтакте API (некоторые функции могут блокироваться самим ВК из-за использования прокси. Как они понимают, что вы используете прокси - для меня пока что остается загадкой)
```
{
  proxy: 'socks5://35.241.106.196:1080'
}
```
```
{
  proxy: 'https://103.209.178.174:8080'
}
```
```
{
  proxy: 'protocol://username:password@address:port'
}
```
userAgent (<string>)
User-Agent header для всех запросов Easy VK. Может использоваться для использования audio api от ВКонтакте с уже готовыми токенами доверенных клиентов (типа Kate Mobile)
```
{
  userAgent: 'Mozilla/5.0 (Windows NT 6.3; Win64; x64) AppleWebKit/537.36 ...'
}
```
utils (<Object>)
Объект настроек для подключения внутренних утилит easyvk, если какие-то утилиты отключены, они не будут занимать место в оперативной памяти. По умолчанию Easy VK отключает некоторые утилиты самостоятельно, в зависимости от типа авторизации (например, для группы не будут доступны User LongPoll и StreamingAPI и т.д). Вы можете включать их, если это необходимо
```
{
  bots: true, // Bots LongPoll
  longpoll: true, // User LongPoll (возможна нестабильная работа в связи с ограничениями ВКонтакте на секцию messages)
  http: true, // HTTP Клиент для работы с Audio API
  widgets: true, // Дополнительные виджеты
  uploader: true, // Внутреннее решение для загрузки файлов на сервер
  callbackAPI: true, // Callback API
  streamingAPI: true, // Streaming API 
}
```

debug (<Object> Debugger)

Объект Debugger от Easy VK для удобного дебага запросов и ответов сервера


const easyvk = require('easyvk')
const { Debugger } = easyvk

let debug = new Debugger();

debug.on('response', ({body}) => {
  console.log(body)
})

debug.on('request', ({query, url, method}) => {
  console.log(method, url, query)
})

easyvk({
  debug,
  ...{}
}).then(vk => {
  // ...
})

authType (<string>)
Тип авторизации на случай, если вы используете token для работы с API. Это необходимо, потому что Easy VK создает внутри себя сессию для запуска впервые, позже он ее использует уже без запросов. Но, чтобы ее создать, Easy VK внутри себя делает три запроса для выявления принадлежности токена к какому-то типу. Поэтому если что-то внутри ВКонтакте поменяется, и будет валить ошибками, то можно попробовать просто указать прямой тип авторизации, чтобы Easy VK знал куда обращаться
```
{
  authType: [easyvk.easyvk.USER_AUTH_TYPE, easyvk.GROUP_AUTH_TYPE, easyvk.APPLICATION_AUTH_TYPE][0]
}

{
  authType: ['user', 'group', 'app'][0]
}


  
```
onlyInstance (<boolean>)
Нужно ли возвращать только инстанс easyvk, не проводя авторизацию. Может быть нужно, если вам необходимо получить доступ к HTTP Клиенту

# Авторизация группы

Чтобы обращаться к API ВКонтакте от имени группы, Вам необходимо авторизоваться, как группа. Для этого необходимо взять access_token группы (из настроек группы) и воспользоваться следующим примером


easyvk({
  token: '{GROUP_TOKEN}'
}).then(vk => {
  
  console.log(vk.session.group_id);


})

После авторизации группы, в объекте сессии будут доступны некоторые свойства группы


  {
    group_id,
    group_name,
    group_screen, // буквенный ID группы
    ...({...fields})  // Поля, которые были указаны в настройках Easy VK
  }

# Client Credentials Flow

С обновления Easy VK версии 2.1.0 идет поддержка Client Credentials Flow. Ранее его не было, оно было костыльным, и в большинстве случаев Easy VK сам выполнял все задачи, которые должны контролировать пользователи, но теперь это не так и я рад, что такое упущение было устранено. Теперь можно воспользоваться авторизацией Cred Flow для получения сервисного ключа доступа, который нужен для secure методов. Для этого Вам нужно получить ID Вашего приложения и секретный ключ (защищенный) и настроить авторизацию


  easyvk({
    clientId: '{APP_ID}',
    clientSecret: '{APP_SECRET_CODE}'
  }).then(vk => {
    // Работаем с кодом дальше
  })

# Авторизация приложения

С обновления Easy VK версии 2.1.0 идет поддержка Client Credentials Flow, а вместе с ним еще и авторизация приложения по токену приложения. Для авторизации приложения Вам необходимо взять сервисный ключ приложения и воспользоваться им, как указано ниже


  easyvk({
    token: "{APP_TOKEN}"
  }).then(vk => {
    console.log(vk.session.app_id);
  })

После авторизации приложения в объекте сессии будет доступна некоторая информация о Вашем приложении.


  {
    app_id: 0,
    app_title: '',
    app_type: '',
    app_icons: ['', ''],
    author: {
      id: 0
    },
    app_members: 0,
    client_id: parseInt('233_ID_приложения', 10)
  }

# Двухфакторная авторизация

В EasyVK есть поддержка двухфакторной авторизации. Для того, чтобы ее пройти, необходимо сначала получить код приложения из SMS или из приложения-верификтора, а затем передать его в параметр code при авторизации пользователя.

[+] (Спойлер) - Пример кода для двухфакторной авторизации пользователя


const easyvk = require("easyvk");
const readline = require('readline');

const rl = readline.createInterface({
  input: process.stdin,
  output: process.stdout
});

async function main (vk) {
  // главный код вашего приложения  
  console.log(vk.session);
}

async function logInWith2Auth (params) {
  return new Promise((_2faNeed) => {

    function relogIn (_2faCode = "") {

      if (_2faCode) params.code = _2faCode

      easyvk(params).then(main).catch((err) => {

        if (!err.easyvk_error) {
          if (err.error_code == "need_validation") {
            _2faNeed({
              err: err,
              relogIn: relogIn
            });
          }

        }

      })
    }

    relogIn()

  })
}

logInWith2Auth({
  username: "Логин",
  password: "Пароль",
  reauth: true,
}).then(({err: error, relogIn}) => {

  console.log(error.validation_type);
  
  rl.question(error.error + " ", (answer) => {

    let code = answer;
    relogIn(code);

    rl.close();

  });

})

Кроме того, с версии 2.6.0 в EasyVK появилась поддержка двухфакторной аутентификации в HTTP Клиенте

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

[+] (Спойлер) - Пример кода для двухфакторной авторизации пользователя HTTP клиента

const readline = require('readline')

const rl = readline.createInterface({
  input: process.stdin,
  output: process.stdout
});

async function loginByFormWithTwoFactorSupport (code='') {
  return vk.http.loginByForm({
    cookies: './cookies',
    reauth: true,
    code
  }).catch(e => {
    if (e.is2fa) {
      return new Promise((resolve, reject) => {
        rl.question(`Введите ключ авторизации `, (key) => {
          return loginByFormWithTwoFactorSupport(key).then(resolve).catch(reject)
        })
      })
    } else {
      throw e;
    }
  })
}

let client = await loginByFormWithTwoFactorSupport();

# База знаний

Данный раздел будет пополняться со временем.

[+] (Спойлер) - FAQ, вопросы и ответы

Пока что здесь пусто

# Благодарности

Easy VK уже существует почти год. И мне есть, кому сказать спасибо за это.

Иван Сотников

[+] (Спойлер) - Ссылка на профиль ВК (удалю по просьбе)

https://vk.com/is2511

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

Эмиль Сергеев

[+] (Спойлер) - Ссылка на профиль ВК (удалю по просьбе)

https://vk.com/srhfty

За найденные проблемы библиотеки, да и просто помощь в указании на эти проблемы. Благодаря Эмилю, можно сказать, вообще началась работа над ошибками)

Вадим Марченко

[+] (Спойлер) - Ссылка на профиль ВК (удалю по просьбе)

https://vk.com/vjakos

За помощь словом и поддержкой.

Спасибо всем, кто проявлял хоть какую-то активность в сообществе Easy VK во ВКонтакте

Мне нравится EasyVK