Skip to main content

Python Clever Api

Project description

# **Clever API**
Библиотека созданная для удобного взаимодействия с API мобильного приложения Клевер, разрабатываемого во ВКонтакте.

## Навигация
- [Установка](#Установка)
- [Использование](#Использование)
- [Получение токена](#Получение-токена)
- [Обработчики](#Обработчики)
- [Действия](#Действия)
- [Отправка ответа](#Отправка-ответа)
- [Бамп](#Бамп)
- [События](#События)
- [sq_game_winners](#sq_game_winners)
- [sq_friend_answer](#sq_friend_answer)
- [sq_question](#sq_question)
- [sq_ed_game](#sq_ed_game)
- [sq_question_answers_right](#sq_question_answers_right)
- [video_comment_new](#video_comment_new)
- [Примеры](#Примеры)

## Установка
Протестирована работа с Python 3.6.

* Установка с помощью pip (пакетный менеджер Python):
```
$ pip install cleverapi --upgrade
```
* Установка из исходного кода (требуется git)
```
$ git clone https://github.com/oncecreated/cleverapi.git
$ cd cleverapi
$ python setup.py install
```

## Использование
Пользоваться библиотекой очень легко. Например, для простого вывода текста вопроса из онлайн викторины потребуется всего несколько строчек кода:

```python
from cleverapi import CleverApi, CleverLongPoll

api = CleverApi("TOKEN")
lp = CleverLongPoll(api)

@lp.question_handler()
def new_question(event):
print(event["question"]["text"])

lp.game_waiting()
```
Главным методом взаимодействия библиотеки и Клевера, является **CleverLongPoll** используемый библиотекой. С помощью него становится возможным в реальном времени получать игровые события, будь то ответ вашего друга или новый вопрос.

## Получение токена
Для работы библиотеки необходимо получить access_token из приложения Клевер, сделать это можно воспользовавшись ссылкой (access_token будет в адресной строке после подтверждения прав доступа):

`http://oauth.vk.com/authorize?client_id=6334949&scope=589842&display=mobile&response_type=token`

## Обработчики
Поступающие игровые события нужно как-то обрабатывать, для этого нужно использовать специальные обработчики.

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

```python
@lp.game_winners_handler()
def print_winners(event):
print(event)
```

У функции после декоратора должен быть единственный параметр, отвечающий за информацию о событии.

Список доступных декораторов:

|Декоратор | Тип события | Описание|
|---|---|---|
| `comment_handler`| `video_comment_new`|Событие комментария к игровой трансляции|
| `question_handler`|`sq_question`|Событие нового вопроса|
| `friend_answer_handler`|`sq_friend_answer`|Событие ответа друга пользователя|
| `right_answer_handler`|`sq_question_answers_right`|Событие результата ответа на вопрос|
| `end_game_handler`|`sq_ed_game`|Событие окончания викторины|
| `game_winners_handler`| `sq_game_winners` |Событие списка победивших игроков |
| `all_events_handler`|-|Дополнительный декоратор для получения всех событий пришедших с LongPoll |
| `last_time_answer`|`sq_question`|Дополнительный декоратор, вызываемый в последнее возможное время ответа на вопрос (может быть полезно, когда нужно ответить не сразу после получения вопроса) |


## Действия
В игре существуют некоторые действия, за которые вам начисляют клеверсы. Для начисления виртуальных монеты необходимо самостоятельно вызывать методы **send_action_***.

Например, если вы правильно ответили на вопрос, то не забудьте оповестить об этом сервер:
```python
api.send_action_answer_correct()
```

Список возможных действий:

|Действие | Описание|
|---|---|
| `send_action_watched_game`|Вы досмотрели игру до конца|
| `send_action_join_game`|Вы присоединились к игре|
| `send_action_answer_correct`|Вы дали правильный ответ|
| `send_action_win_game`|Вы выиграли игру|
| `send_action_invite_friend`|Вы пригласили друга|
| `send_action_community_notify`|Вы подписались на уведомления сообщества Клевер|
| `send_action_aliexpress_auth`|Вы выполнили вход в приложение партнера|

## Отправка ответа
Для отправки ответа используется метод. **send_answer**:
```python
api.send_answer(coins_answer, game_id, answer_id, question_id)
```
Стоит остановиться на двух параметрах этого метода:
- `coins_answer` (`bool`) - Передавайте True если играете на клеверсы, передавайте значение False, если вы продолжаете играть на деньги. *Осторожно, если вы передадите значение False когда уже выбыли из игры ваш ответ не будет засчитан*
- `game_id` (`int`) - идентификатор текущей игры, его можно получить из атрибута `game_id` класса `CleverLongPoll`

## Бамп
Для бампа используется метод. **bump**:
```python
api.bump(lat, lon)
```
Стоит остановиться на двух параметрах этого метода:
- `lat` (`string`) - Широта
- `lon` (`string`) - Долгота

Передаются в виде градусов (xx.xxxxxx)

Внимание: За 1 бамп с 1 человеком дают 50 клеверсов, с 1 человеком можно бампится 1 раз в неделю. Лимит бампов в неделю: 1000 клеверсов.

Подробнее: https://ru.wikipedia.org/wiki/Географические_координаты

## События
Игровые события в формате JSON.

### **sq_game_winners**
```json
{
"type":"sq_game_winners",
"owner_id":-162894513,
"video_id":456230000,
"users":[
{
"name":"Самира В.",
"photo_url":"https://vk.com/images/camera_200.png?ava=1"
},
{
"name":"Владислав П.",
"photo_url":"https://vk.com/images/camera_200.png?ava=1"
},
{
"name":"Варвара Д.",
"photo_url":"https://vk.com/images/camera_200.png?ava=1"
},
{
"name":"Анастасия Ф.",
"photo_url":"https://vk.com/images/camera_200.png?ava=1"
},
{
"name":"Тёма Б.",
"photo_url":"https://vk.com/images/camera_200.png?ava=1"
},
{
"name":"Евгений В.",
"photo_url":"https://vk.com/images/camera_200.png?ava=1"
},
{
"name":"Вячеслав З.",
"photo_url":"https://vk.com/images/camera_200.png?ava=1"
},
{
"name":"Дарья М.",
"photo_url":"https://vk.com/images/camera_200.png?ava=1"
},
{
"name":"Светлана С.",
"photo_url":"https://vk.com/images/camera_200.png?ava=1"
}
],
"prize":0,
"winners_num":9,
"version":2
}
```

### **sq_friend_answer**
```json
{
"type":"sq_friend_answer",
"game_id":200,
"user_id":100,
"answer_id":0,
"photo_url":"https://vk.com/images/camera_200.png?ava=1",
"is_live_enabled":true
}
```

### **sq_question**
```json
{
"type":"sq_question",
"owner_id":-162894513,
"video_id":456239000,
"question":{
"id":11,
"text":"Кто основал социальную сеть ВКонтакте?",
"answers":[
{
"id":0,
"text":"Николай Дуров"
},
{
"id":1,
"text":"Павел Дуров"
},
{
"id":2,
"text":"Илон Маск"
}
],
"time":null,
"number":1
},
"version":2
}
```

### **sq_ed_game**
```json
{
"type":"sq_ed_game",
"owner_id":-162894513,
"video_id":456230000,
"version":2
}
```

### **sq_question_answers_right**
```json
{
"type":"sq_question_answers_right",
"owner_id":-162894513,
"video_id":456230000,
"question":{
"text":"Кто основал социальную сеть ВКонтакте?",
"answers":[
{
"id":0,
"text":"Николай Дуров",
"users_answered":1584
},
{
"id":1,
"text":"Павел Дуров",
"users_answered":389217
},
{
"id":2,
"text":"Илон Маск",
"users_answered":389
}
],
"right_answer_id":1,
"id":11,
"is_first":true,
"is_last":false,
"number":1,
"sent_time":1529600002,
"answer_set":true
},
"question_time":1529600000,
"version":2
}
```

### **video_comment_new**
```json
{
"type":"video_comment_new",
"owner_id":-162894513,
"video_id":456230000,
"comment":{
"id":0,
"from_id":100,
"date":152960000,
"text":"мыши"
},
"user":{
"id":100,
"photo_50":"https://vk.com/images/camera_200.png?ava=1",
"photo_100":"https://vk.com/images/camera_200.png?ava=1",
"first_name":"Павел",
"last_name":"Анисимов",
"sex":2
},
"version":2
}
```

## Примеры
[like_friends.py](https://github.com/oncecreated/cleverapi/blob/master/examples/like_friends.py) - использование библиотеки для создания бота, который выбирает наиболее популярный ответ у друзей
[bump.py](https://github.com/oncecreated/cleverapi/blob/master/examples/bump.py) - использование библиотеки для бампа, который происходит в выбранных координатах


Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for cleverapi, version 0.3.3
Filename, size File type Python version Upload date Hashes
Filename, size cleverapi-0.3.3-py3-none-any.whl (14.4 kB) File type Wheel Python version py3 Upload date Hashes View
Filename, size cleverapi-0.3.3.tar.gz (12.3 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page