{{indexmenu_n>40}}
====== Зашифрована інформація про гру (Task API) ======

===== Навіщо це потрібно? =====

Якщо вам необхідно безпечно передати дані про поточного гравця або команду під час гри стороннім зовнішнім сервісам (наприклад, Telegram-боту, скрипту авторизації або кастомному сайту з флеш-грою), використовуйте генерацію зашифрованого рядка.

У цьому випадку навіть технічно підковані гравці не зможуть побачити, які саме дані передаються в URL або параметрах скрипта, і не зможуть підмінити їх самостійно. Це особливо критично на іграх довгого формату (Long).

===== Як це налаштувати? =====

==== 1. Генерація секретного ключа ====
  * Перейдіть до редактора вашої гри.
  * Знайдіть розділ **"API для зовнішніх сайтів / телеграм ботів"**.
  * Натисніть кнопку **"Згенерувати"**. Движок створить унікальний ключ (наприклад, ''XgHxzCvUSXwPfR7wBvdY4xHC6tSFLewx'').

==== 2. Використання плейсхолдера в завданні ====
У тексті завдання, підказки або в параметрах посилання на зовнішній сервіс пропишіть конструкцію виду:
<code>
!api:поле1,поле2!
</code>

Доступні поля для шифрування (вказуються через кому):
  * **''user_id''** — ID гравця. У розшифрованому JSON перетворюється на ключ **''u''**.
  * **''user_name''** — логін гравця. У JSON — **''un''**.
  * **''team_id''** — ID команди. У JSON — **''tm''**.
  * **''team_name''** — назва команди. У JSON — **''tmn''**.
  * **''task_n''** — порядковий номер поточного рівня. У JSON — **''t''**.
  * **''task_id''** — ID поточного рівня. У JSON — **''tid''**.
  * **''game_id''** — ID гри. У JSON — **''gid''**.

==== Приклад генерації ====
Якщо ви пропишете в завданні:
<code>
!api:user_id,task_id!
</code>
Движок згенерує зашифрований hex-рядок виду:
<code>
0394334e96a2f0fa738470e9a9778c684ba214990d200eab
</code>
Його можна розшифрувати на вашому сервері за допомогою ключа гри та алгоритму Blowfish (ECB). В результаті ви отримаєте JSON:
<code>
{"u": 162862, "tid": 42719}
</code>

[[https://qeng.org/game.php?jump_to&gid=3493&task_id=42719|Приклад завдання в грі]]

===== Приклади розшифрування на сервері =====

==== PHP ====
<code PHP>
$data = '0394334e96a2f0fa738470e9a9778c684ba214990d200eab';
$key  = 'XgHxzCvUSXwPfR7wBvdY4xHC6tSFLewx';
$decoded = json_decode(
  trim(
    openssl_decrypt(
      hex2bin($data),
      'BF-ECB',
      $key,
      OPENSSL_RAW_DATA | OPENSSL_NO_PADDING
    )
  ),
  true
);
// $decoded => array('u' => 162862, 'tid' => 42719)
</code>

==== Python ====
*(Потрібна бібліотека blowfish: ''pip install blowfish'')*
<code Python>
import binascii
import json
import typing
import blowfish

def decrypt_qeng_data(data: str, key: str) -> typing.Dict[str, typing.Union[str, int]]:
    data_bytes = binascii.unhexlify(data)
    cipher = blowfish.Cipher(key.encode())
    data_decrypted = b"".join(cipher.decrypt_ecb(data_bytes))
    data_decrypted = data_decrypted.rstrip(b'\x00')
    return json.loads(data_decrypted)

# Використання
data = '0394334e96a2f0fa738470e9a9778c684ba214990d200eab'
key = 'XgHxzCvUSXwPfR7wBvdY4xHC6tSFLewx'
print(decrypt_qeng_data(data, key)) # => {'u': 162862, 'tid': 42719}
</code>

==== Ruby ====
<code Ruby>
require 'json'
require 'openssl'

module Blowfish
  def self.decrypt(data, key)
    crypto = OpenSSL::Cipher::Cipher.new('bf-ecb').send(:decrypt)
    crypto.key_len = key.length
    crypto.key = key
    crypto.padding = 0
    crypto.update([data].pack("H*")) << crypto.final
  end
end

def qeng_data_decrypt(data, key)
  decrypted_text = Blowfish.decrypt(data, key)
  JSON.parse(decrypted_text, symbolize_names: true)
end

# Використання
data = '0394334e96a2f0fa738470e9a9778c684ba214990d200eab'
key = 'XgHxzCvUSXwPfR7wBvdY4xHC6tSFLewx'
puts qeng_data_decrypt(data, key) # => {:u=>162862, :tid=>42719}
</code>