API приложений

getUserInfoGET#

Профиль игрока, открывшего игру. Спрашивать его при старте — нормальная практика: имя, аватар и язык обычно нужны сразу.

lang — язык аккаунта игрока ("ru" или "en"). Это его выбор на платформе, поэтому он точнее языка браузера и системы: включайте локализацию игры по нему.

const {user} = await zloy.getUserInfo();
nameLabel.textContent = user.nickname;
if (user.avatar) avatarImg.src = user.avatar;
setLocale(user.lang);            // 'ru' | 'en' — выбор игрока на платформе

// Ответ:
// { "ok": true, "user": { "user_id": 42, "username": "zloysega",
//   "nickname": "Сергей", "avatar": "…", "lang": "ru" } }

const {user}: UserInfo = await zloy.getUserInfo();
render(user);
i18n.locale = user.lang;         // 'ru' | 'en'

getUserFriendsGET#

Друзья игрока с пагинацией: offset (по умолчанию 0) и limit (по умолчанию и максимум 100). В ответе есть total — сколько всего.

const {total, friends} = await zloy.getUserFriends(0, 100);
console.log(`друзей: ${total}`);

// Ответ:
// { "ok": true, "total": 152, "offset": 0, "limit": 100,
//   "friends": [ { "user_id": 7, "nickname": "Алиса", … } ] }

const page: FriendsPage = await zloy.getUserFriends(0, 100);
page.friends.forEach(renderFriend);

getUserFriendsInAppGET#

То же самое, но только друзья, которые уже установили вашу игру. Годится для «позови своих» и для показа, с кем можно сыграть прямо сейчас.

const {friends} = await zloy.getUserFriendsInApp();
showInviteList(friends);

const {friends}: FriendsPage = await zloy.getUserFriendsInApp();

getUserInstalledAppsGET#

Игры, которые игрок установил. Пагинация как у друзей. Полезно для кросс-промо между вашими играми.

const {apps} = await zloy.call('getUserInstalledApps');

// Ответ:
// { "ok": true, "total": 3, "offset": 0, "limit": 100,
//   "apps": [ { "app_id": 1, "slug": "darkrunner", "name": "Dark Runner",
//     "icon": "https://zloy.net/uploads/appicons/a1-abc.png",
//     "summary": "Бегай во тьме.",
//     "url": "https://zloy.net/darkrunner" } ] }

interface App {
  app_id: number; slug: string; name: string;
  icon: string; summary: string; url: string;
}
interface AppsPage { ok: boolean; total: number; apps: App[] }

postResultGET#

Публикует результат на стене самого игрока: запись появляется по адресу zloy.net/<игрок>/<seq>, где seq — номер записи в пределах страницы игрока (поэтому zloy.net/alice/7 и zloy.net/bob/7 — разные записи). Автор записи — игрок; вместе с ней сохраняется IP запроса (требование закона о соцсетях).

text — до 280 символов, обязателен. Публиковать можно через неделю после регистрации игрока, иначе ответ posting_locked. Часовой лимит на игрока защищает от спама — rate_limited.

const r = await zloy.postResult(`Набрал ${score} очков!`);
if (r.ok) window.open(r.url, '_blank');

// Ответ:
// { "ok": true, "post_id": 812, "seq": 34,
//   "url": "https://zloy.net/alice/34" }

const r: {ok: boolean; post_id: number; seq: number; url: string} =
  await zloy.postResult(`Набрал ${score} очков!`);

sendToWallPOST#

Кладёт достижение на страницу самой игры (zloy.net/<адрес_игры>game): таблицу результатов в markdown и снимок или короткий ролик. Запись подписана игроком, от чьего имени пришёл вызов, поэтому она же появляется в ленте его друзей. Медиа попадает в галерею страницы.

text — markdown до 4000 символов, image — canvas, Blob или File: принимаем png, jpeg, gif, bmp, webp (до 4 МБ, сторона до 1920). video — Blob или File в любом формате, который читает сервер (webm с MediaRecorder, mp4, mov, mkv): до 200 МБ и до 180 секунд. Жать перед отправкой не нужно — сожмём мы.

Снимок или ролик, но не оба сразу (иначе image_and_video): в карточке поста место под медиа одно, и выбирать за вас, что показать, платформа не станет. Нужно хотя бы одно из трёх — текст, снимок или ролик.

Хранится снимок всегда как JPEG, чем бы вы его ни прислали: кадр из игры — фотография по природе, и PNG держал бы её впятеро дороже без разницы на глаз. Прозрачность при этом теряется — то, что было прозрачным, станет чёрным. Ролик — всегда MP4 720p (H.264 + AAC): игра пишет тем, что есть под рукой, а смотрят пост с чужого телефона по ссылке из ленты, и второй попытки у него не будет. 1080p и 4K уменьшаются до 720p — в ленте разницы не видно, а весит втрое меньше.

Ролик перекодируется в очереди, и запись появляется раньше него. Ответ приходит сразу и несёт media_status: "processing"; сам ролик доезжает к записи через десятки секунд, а до тех пор на странице написано, что он готовится. Держать ваш вызов всё это время платформа не станет: минута ожидания — это замерший экран у игрока и оборванный по таймауту запрос у вас. Отказы, которые видны сразу (не видео, слишком длинный, слишком большой), приходят обычной ошибкой — их ждать не нужно.

Медиа на zloy.net выкладывает только игра. Человеку загрузка закрыта — поток произвольных картинок и роликов нечем модерировать; за то, что кладёт игра, она отвечает своим ключом. Файлы раздаются с отдельного домена s.zloy.net.

Водяной знак платформа ставит сама — и на снимок, и на ролик: чёрную плашку с иконкой и адресом вашей игры в левом нижнем углу (высота — 3% кадра). Пост уходит в ленту друзей и дальше по пересылкам, и метка — единственное, что приводит по нему обратно в игру. Рисовать свою не нужно, а вот левый нижний угол кадра лучше держать свободным: счётчик или кнопка там окажутся под плашкой.

В ответе — адрес ЗАПИСИ, а не файла. Публикуется запись: у неё адрес, срок, реакции и комментарии, и именно её показывают игроку. Полей image_url и video_url больше нет — у ролика в момент ответа файла ещё и не существует.

Запись живёт 30 суток, дальше платформа удаляет и её, и файл (срок возвращается в expires_at). Страница игры — не архив: таблица прошлого сезона вытесняет сегодняшнюю.

Частота — пост в час и не больше 12 в сутки на игрока в этой игре. Лимит принадлежит игре: сколько игрок постил в других, вашей не касается, и наоборот. Перебор — rate_limited вместе с retry_after в секундах; повторять раньше бессмысленно. Это не поломка: покажите «поделиться можно будет позже», а не ошибку. Если у игры ещё нет промо-страницы, ответ — no_page: постить некуда.

const r = await zloy.sendToWall({
  text: `**Сезон закрыт!**\n\n| место | игрок | очки |\n|---|---|---|\n| 1 | Алиса | 9120 |`,
  image: document.querySelector('canvas'),   // canvas | Blob | File
});

if (r.ok) console.log(r.url, 'исчезнет', r.expires_at);
else if (r.error === 'rate_limited') laterMsg(r.retry_after);

// Ответ — про ЗАПИСЬ, а не про файл:
// { "ok": true, "seq": 41,
//   "url": "https://zloy.net/darkrunnergame/41",
//   "expires_at": "2026-09-16T21:03:11Z" }

// РОЛИК — вместо снимка. Записать его прямо с холста игры:
const stream = document.querySelector('canvas').captureStream(30);
const rec = new MediaRecorder(stream, { mimeType: 'video/webm' });
const parts = [];
rec.ondataavailable = (e) => parts.push(e.data);
rec.start();
setTimeout(() => rec.stop(), 8000);        // 8 секунд трюка
rec.onstop = async () => {
  const clip = new Blob(parts, { type: 'video/webm' });
  const r = await zloy.sendToWall({ text: 'Вот это проход!', video: clip });
  // { "ok": true, "seq": 42, "url": "https://zloy.net/darkrunnergame/42",
  //   "expires_at": "…", "media_status": "processing" }
  // Ссылку можно показывать сразу: запись уже есть, ролик подтянется к ней.
};

interface WallPost {
  ok: boolean; seq: number; url: string;
  expires_at: string;
  media_status?: 'processing';   // ролик ещё перекодируется
  error?: 'no_page' | 'empty' | 'text_too_long' | 'image_too_large'
        | 'image_and_video' | 'video_too_large' | 'video_too_long'
        | 'bad_video' | 'video_unsupported'
        | 'rate_limited' | 'posting_locked' | 'banned';
  retry_after?: number;   // секунды, только при rate_limited
}

const r: WallPost = await zloy.sendToWall({ text: 'Рекорд!' });

payпо допуску#

SDK показывает оверлей «Пополнить игру» с описанием и суммой в рублях; после подтверждения создаётся платёж (GET /v1/createPayment?amount=<₽>&description=…) и браузер переходит по полученному url в платёжную систему.

Платежи доступны ограниченному списку игр. Если игра не в списке, вызов тихо возвращает {ok: false, error: 'payments_not_allowed'} и ничего не показывает. Проверка допуска — GET /v1/paymentsAllowed → {"ok":true,"allowed":true|false}.

Куда зачислять купленное (какой банк и валюта) настраивается в свойствах игры — см. кубик «Банк».

const r = await zloy.pay('100 кристаллов', 199);
// r.ok === true       → игрок подтвердил, идёт переход в платёжную систему
// r.error === 'payments_not_allowed' | 'cancelled'

const r: {ok: boolean; error?: 'payments_not_allowed' | 'cancelled'} =
  await zloy.pay('100 кристаллов', 199);