Apps API

getUserInfoGET#

The profile of the player who opened the game. Calling it on startup is common practice — you usually need the name, avatar and language right away.

lang is the player's account language ("ru" or "en"). It is their own choice on the platform, so it beats the browser and system locale — drive your localisation with it.

const {user} = await zloy.getUserInfo();
nameLabel.textContent = user.nickname;
if (user.avatar) avatarImg.src = user.avatar;
setLocale(user.lang);            // 'ru' | 'en' — the player's choice

// Response:
// { "ok": true, "user": { "user_id": 42, "username": "zloysega",
//   "nickname": "Sergey", "avatar": "…", "lang": "ru" } }

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

getUserFriendsGET#

The player's friends, paginated: offset (default 0) and limit (default and maximum 100). The response also carries total.

const {total, friends} = await zloy.getUserFriends(0, 100);
console.log(`friends: ${total}`);

// Response:
// { "ok": true, "total": 152, "offset": 0, "limit": 100,
//   "friends": [ { "user_id": 7, "nickname": "Alice", … } ] }

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

getUserFriendsInAppGET#

Same shape, but only friends who already installed your game. Good for “invite your friends” and for showing who you can play with right now.

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

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

getUserInstalledAppsGET#

Games the player has installed, paginated like the friend list. Useful for cross-promotion between your own games.

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

// Response:
// { "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": "Run in the dark.",
//     "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#

Publishes a result on the player's own wall. The post appears at zloy.net/<player>/<seq>, where seq is the post number within that player's page (so zloy.net/alice/7 and zloy.net/bob/7 are different posts). The player is the author; the request IP is stored alongside, as required by Russian social-network law.

text is required, up to 280 characters. Posting is allowed one week after the player registered, otherwise the response is posting_locked. An hourly per-player limit guards against spam — rate_limited.

const r = await zloy.postResult(`Scored ${score} points!`);
if (r.ok) window.open(r.url, '_blank');

// Response:
// { "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(`Scored ${score} points!`);

sendToWallPOST#

Puts an achievement on the game's own page (zloy.net/<game_slug>game): a markdown results table and a screenshot or a short clip. The post is signed by the player the call came from, so it also lands in their friends' feeds. The media joins the page gallery.

text — markdown, up to 4000 characters; image — a canvas, Blob or File: we accept png, jpeg, gif, bmp, webp (up to 4 MB, side up to 1920). video — a Blob or File in any format the server can read (webm from MediaRecorder, mp4, mov, mkv): up to 200 MB and up to 180 seconds. No need to compress before sending — we will.

A screenshot or a clip, but not both (otherwise image_and_video): a post card has one place for media, and the platform will not choose for you which one to show. At least one of the three — text, image or video — is required.

The screenshot is always stored as JPEG, whatever you send: a game frame is a photograph by nature, and PNG would keep it five times more expensively with no visible gain. Transparency is lost in the process — whatever was transparent turns black. A clip is always MP4 720p (H.264 + AAC): a game records with whatever is at hand, while the post is watched from someone else's phone via a link in a feed, and it gets no second try. 1080p and 4K are scaled down to 720p — invisible in a feed, three times lighter.

Clips are transcoded in a queue, and the post appears before the clip does. The reply comes back at once carrying media_status: "processing"; the clip itself reaches the post tens of seconds later, and until then the page says it is being prepared. The platform will not hold your call for all that time: a minute of waiting is a frozen screen for the player and a request timed out on your side. Rejections that are visible immediately (not a video, too long, too large) come back as normal errors — no waiting needed.

Only games upload media to zloy.net. People cannot — a stream of arbitrary pictures and clips is something we have no way to moderate; a game answers for what it posts with its key. Files are served from a separate domain, s.zloy.net.

The platform stamps the watermark itself — on screenshots and on clips alike: a black plate with the zloy.net icon and your game's address in the bottom-left corner (3% of the frame height). The post travels into friends' feeds and onwards through reposts, and the mark is the only thing that leads back to the game. You do not need to draw your own — but keep the bottom-left corner of the frame free: a score or a button there ends up under the plate.

The reply carries the address of the POST, not of the file. What gets published is the record: it has an address, a deadline, reactions and comments, and it is what you show the player. The image_url and video_url fields are gone — for a clip the file does not even exist yet when we reply.

A post lives 30 days, after which the platform deletes both the record and the file (the deadline comes back in expires_at). A game page is not an archive: last season's table crowds out today's.

Rate — one post per hour and at most 12 per day per player in this game. The limit belongs to the game: how much the player posted in other games does not touch yours, and the other way round. Over the limit you get rate_limited together with retry_after in seconds; retrying sooner is pointless. It is not a failure: say “you can share this later” rather than showing an error. If the game has no promo page yet the answer is no_page — there is nowhere to post.

const r = await zloy.sendToWall({
  text: `**Season closed!**\n\n| place | player | score |\n|---|---|---|\n| 1 | Alice | 9120 |`,
  image: document.querySelector('canvas'),   // canvas | Blob | File
});

if (r.ok) console.log(r.url, 'expires', r.expires_at);
else if (r.error === 'rate_limited') laterMsg(r.retry_after);

// Response — about the POST, not the file:
// { "ok": true, "seq": 41,
//   "url": "https://zloy.net/darkrunnergame/41",
//   "expires_at": "2026-09-16T21:03:11Z" }

// A CLIP — instead of a screenshot. Record it straight off the game canvas:
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 seconds of the trick
rec.onstop = async () => {
  const clip = new Blob(parts, { type: 'video/webm' });
  const r = await zloy.sendToWall({ text: 'What a run!', video: clip });
  // { "ok": true, "seq": 42, "url": "https://zloy.net/darkrunnergame/42",
  //   "expires_at": "…", "media_status": "processing" }
  // You can show the link right away: the post exists, the clip catches up.
};

interface WallPost {
  ok: boolean; seq: number; url: string;
  expires_at: string;
  media_status?: 'processing';   // the clip is still being transcoded
  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;   // seconds, only with rate_limited
}

const r: WallPost = await zloy.sendToWall({ text: 'New record!' });

payallowlisted#

The SDK shows a “Top up” overlay with a description and an amount in roubles; once the player confirms, a payment is created (GET /v1/createPayment?amount=<₽>&description=…) and the browser follows the returned url to the payment provider.

Payments are available to an allowlisted set of games. If your game is not on the list the call quietly resolves to {ok: false, error: 'payments_not_allowed'} and shows nothing. Check with GET /v1/paymentsAllowed → {"ok":true,"allowed":true|false}.

Where the purchase is credited (which bank cube and currency) is configured in the game's settings — see the bank cube.

const r = await zloy.pay('100 crystals', 199);
// r.ok === true       → confirmed, redirecting to the payment provider
// r.error === 'payments_not_allowed' | 'cancelled'

const r: {ok: boolean; error?: 'payments_not_allowed' | 'cancelled'} =
  await zloy.pay('100 crystals', 199);