Документация по интеграции приложения iPlayer.org API+OAuth2

in English: open

Игровая платформа iPlayer.org позволяет интегрировать приложения используя протокол OAuth2.

Как подключить приложения?

Подключением приложения занимается менеджер iPlayer.org:
Методи, skype: metodi.chukovski

Для инициализации вашего приложения, вам нужно сообщить менеджеру свой URL страницы на котором будет находится ваше приложение.

Пример: https://iplayer.your_game.com/?lang=ru

После того, как менеджер зарегистрировал приложение, вы получите 2 ключа: client_key и client_secret.

Теперь ваше приложение зарегестрировано в iPlayer.org, и вы можете получить информацию о пользователе iPlayer.org.

Как получить информацию о пользователе?

iPlayer.org делает пункты в красной рамке (на картинке) автоматически и передает access_token в приложение:

Пример: https://iplayer.your_game.com/?lang=ru&access_token=a1b2c3d4e5f6

При помощи access_token приложение может запросить данные о пользователе :

https://iplayer.org/oauth/user/info?access_token=a1b2c3d4e5f6

Пример библиотеки PHP, которая по access_token возвращает данные пользователя iPlayer.org: файл iplayer.php (Скачать)

Пример, как использовать библиотеку:

include "iplayer.php";

$iplayer = IPlayer::handle_request();

try{
$user = $iplayer->user_info();
print_r($user);
}catch(IPlayer_Exception $e){
echo "Error: ". $e->getMessage();
die();
}

В ответе вы получаете массив с информацией о пользователе, или IPlayer_Exception в случае ошибки

Array
(
[name] => Имя пользователя
[surname] => Фамилия пользователя
[nickname] => Ник пользователя
[gender] => m|f Пол пользователя
[birthday] => 1984-06-05 00:00:00 Дата рождения пользователя
[_id] => 156 Уникальный идентификатор пользователя на сервере iPlayer
[avatar] => https://iplayer.org/uploads/a/0/156.jpg Путь к аватарке пользователя
)

Работающий пример приложения можно посмотреть по ссылке (после регистрации/авторизации):

https://iplayer.org/game/example

Как передавать информацию о платежах пользователя с приложения в iPlayer.org?

Когда приложение принимает платежи от пользователей - нужно сообщать iPlayer.org о каждом платеже с привязкой к [user_id] пользователя iPlayer.org

api.iplayer.org/partner/payment - оповещение о платеже

Работающий пример можно посмотреть по ссылке:

https://api.iplayer.org/partner/payment?game=example&user_id=14560&total=130.92&secret=example&currency=usd&confirm=1

параметры

user_id - id пользователя в iPlayer
total - сумма платежа (10.2, 12.5 точка в качестве десятичного знака)
currency - валюта (USD, EUR, RUB, PLN ...)
game - client key из раздела “Как подключить приложение” (barbarians ...)
secret - client secret из раздела “Как подключить приложение”

Если запись добавлена в базу данных iPlayer, возвращается ответ вида

{
"response": {
"payment_id": "13"
}
}

payment_id - уникальный идентификатор платежа в статистике iPlayer.org. Для будущих сверок платежей мы рекомендуем сохранять их payment_id.

Любой платеж требует подтверждения уникальности сервером игры:

api.iplayer.org/partner/payment/confirm - подтверждение получения payment_id нужно для подтверждения УНИКАЛЬНОСТИ платежа (фиксация транзакции):

https://api.iplayer.org/partner/payment/confirm?payment_id= 2002

параметры

payment_id - id платежа полученный в ответе api.iplayer.org/partner/payment

в случае успеха возвращает

{ "response": { "status": "confirmed" } }

если платеж уже был подтвержден или не найден

{ "response": { "status": "cancelled" } }

Если получен ответ "confirmed" или "cancelled" - то iPlayer.org подтвердил статус платежа.

Подтверждение платежа не имеет срока давности, желательно отправлять сразу после получения payment_id или в те же сутки.

Детальный пример передачи и подтверждения уникальности платежа

Пользователь user_id=256837 купил в игре botva игровой валюты на сумму 77.39 RUB

Игра отправляет данный платеж в iPlayer

https://api.iplayer.org/partner/payment?game=botva&user_id=256837&total=77.39&secret=BOTVA_SECRET&currency=rub&confirm=1

Если сервер iPlayer не прислал ответ вида:

{ "response": { "payment_id": "418" } }

то игра повторяет запрос:
https://api.iplayer.org/partner/payment?game=botva&user_id=256837&total=77.39&secret=BOTVA_SECRET&currency=rub&confirm=1

...
Стандартное время ответа сервера до 1-6 сек.

Получения ответа "response" означает, что iPlayer записал данный платеж в базу данных. Теперь нужно подтвердить уникальность платежа (зафиксировать транзакцию).

Игра отправляете запрос

https://api.iplayer.org/partner/payment/confirm?payment_id=418

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

{ "response": { "status": "confirmed" } } - означает, что платеж подтвержден и зафиксирован со стороны iPlayer и стороны игры.

{ "response": { "status": "cancelled" } } - платеж подтвержден ранее или не найден.

Если игра не получила ответа, игра повторяет запрос (https://api.iplayer.org/partner/payment/confirm?payment_id=418)

После получения любого из ответов от сервера iPlayer - никаких других действий по платежу “418” не требуется.

Если игра не получила ответа на запрос payment_id или статуса status обратитесь к менеджеру за объяснением работы API:
Методи, skype: metodi.chukovski

Проверка получения истории платежей

https://api.iplayer.org/partner/payment/history?game=example&secret=example&count=20

параметры