SAQAҚұжаттамаКіру

Құжаттама / SDK

SAQA Games SDK v1

Ойын iframe ішінде іске қосылады және платформамен postMessage арқылы байланысады. SDK-ні тек платформаның мекенжайынан жүктеу керек — origin сол жерден анықталады.

Unity-де жасайсыз ба? Дайын C# плагині мен қадамдық нұсқаулық бар — Unity нұсқаулығын ашыңыз.

Қосу

index.html-ге бір скрипт тегін қосып, init() шақырыңыз. Ол Promise қайтарады.

<script src="https://saqa.app/sdk/v1.js"></script>
<script>
  SaqaSDK.init().then(function (sdk) {
    window.sdk = sdk;
    console.log("Ойыншы:", sdk.player.isAuthorized() ? sdk.player.name : "қонақ");
    sdk.features.LoadingAPI.ready(); // жүктелу экранын жабады
  });
</script>

Платформадан тыс ашылса (мысалы, жергілікті серверде) SDK 5 секундтан кейін авторизациясыз режимде қайтарылады — ойын бәрібір іске қосылады.

Өмірлік цикл

// Ресурстарды жүктеп жатқанда — 0-ден 1-ге дейінгі үлес:
sdk.features.LoadingAPI.setProgress(loaded / total);

// Ойын ресурстары жүктеліп, ойнауға дайын болғанда:
sdk.features.LoadingAPI.ready();

// Нақты ойын процесі басталғанда / тоқтағанда:
sdk.features.GameplayAPI.start();
sdk.features.GameplayAPI.stop();

setProgress ойнатқыштағы жүктелу жолағын толтырады да, ойыншы нақты пайызды көреді. Оны шақырмасаңыз да жолақ көрінеді: платформа билдке шағын индикатор қосады, ол жүктелген мегабайт санын өзі есептейді.

Ойнау уақыты автоматты түрде есептеледі: ойын жүктеліп болғаннан кейін, бет ойыншыға көрініп тұрған уақыт саналады. Ойыншы басқа қолданбаға ауысса, санақ өзі тоқтайды.

GameplayAPI сол санақты дәлдеу үшін керек: stop() шақырсаңыз, мәзірде не кідірісте тұрған уақыт статистикаға қосылмайды, ал start() оны қайта қосады. Шақырмасаңыз да уақыт жиналады.

Ойыншы және бұлттық сақтау

sdk.player.isAuthorized();  // boolean
sdk.player.id;              // string | null
sdk.player.name;            // string | null

// Прогресті сақтау (әдепкі: бар деректермен біріктіріледі)
await sdk.player.setData({ level: 7, coins: 250 });

// Ауыстырып жазу
await sdk.player.setData({ level: 1 }, { merge: false });

// Оқу
const data = await sdk.player.getData();          // барлығы
const some = await sdk.player.getData(["level"]); // тек көрсетілгендер

// Сандық көрсеткіштер
await sdk.player.setStats({ wins: 3 });
const stats = await sdk.player.incrementStats({ wins: 1, deaths: 2 });

Авторизациясыз ойыншыда бұл әдістер AUTH_REQUIRED кодымен қате береді. Ойын оны ұстап, жергілікті localStorage-ке сақтауы керек.

Лидербордтар

Лидербордты алдымен кабинетте құрыңыз, содан кейін оның техникалық атауымен шақырыңыз.

await sdk.leaderboards.setScore("score", 12500, "уақыт: 1:24");

const board = await sdk.leaderboards.getEntries("score", {
  quantityTop: 20,
  includeUser: true,
});

// board.entries   → [{ rank, score, extraData, player: { id, name, avatarUrl } }]
// board.userEntry → ағымдағы ойыншының жазбасы (немесе null)

Нәтиже нашарласа сервер жазбайды: рекорд тек жақсарады. Сұрыптау бағыты (үлкен/кіші мән жақсы) лидерборд параметрінде беріледі.

Жарнама

sdk.adv.showFullscreenAdv({
  callbacks: {
    onOpen: () => pauseGame(),
    onClose: (wasShown) => resumeGame(),
    onError: (err) => resumeGame(),
  },
});

sdk.adv.showRewardedVideo({
  callbacks: {
    onRewarded: () => giveBonus(),
    onClose: () => resumeGame(),
  },
});

Ағымдағы нұсқада жарнама — демонстрациялық блок (санақ таймері). Нақты жарнама желісін ойнатқыш деңгейінде жалғауға болады, ойын коды өзгермейді.

Авторизация

if (!sdk.player.isAuthorized()) {
  try {
    await sdk.auth.openAuthDialog();
    // Ойыншы кіру бетіне өтеді
  } catch (e) {
    // Бас тартты — қонақ режимінде жалғастырамыз
  }
}

Экран және құрылғы

await sdk.screen.fullscreen.request();
await sdk.screen.fullscreen.exit();

sdk.deviceInfo.type;        // "mobile" | "tablet" | "desktop"
sdk.deviceInfo.isMobile();  // boolean
sdk.environment.lang;       // "kk"

Қателерді өңдеу

try {
  await sdk.player.setData({ level: 7 });
} catch (err) {
  if (err.code === "AUTH_REQUIRED") {
    saveLocally();           // қонақ режимі
  } else {
    console.warn(err.message);
  }
}

Кодтар: AUTH_REQUIRED, REQUEST_FAILED, UNKNOWN_METHOD, INTERNAL. Сұраныс 20 секундта жауап бермесе де қате лақтырылады.

Шектеулер мен қауіпсіздік

  • • Бір ойынға сақталатын деректер: 256 КБ дейін (JSON).
  • • Лидерборд ұпайы: 0 – 2 000 000 000 аралығындағы бүтін сан.
  • • Ұпайды клиент жібереді, сондықтан бәсекелі ойындарда серверлік тексеру қажет — бұл платформа деңгейінде шешілмейді.
  • • Ойын бөлек origin-де жүктеледі: платформаның cookie-і мен localStorage-і оған қолжетімсіз.
  • • Барлық сұраныстар ойнатқыш беті арқылы жүреді — ойын ешқашан платформаның API-іне тікелей жүгінбейді.
Games SDK API · SAQA