Құжаттама / Unity

Unity ойындарын жариялау

Unity WebGL билдтері толық қолдау табады, оның ішінде Brotli және Gzip қысылған нұсқалары да. Төменде билдтен бастап жариялауға дейінгі барлық қадам.

1. Билд баптаулары

File → Build Settings → WebGL, содан кейін Player Settings:

Параметр	Мән	Себебі
Compression Format	Brotli	Сервер Content-Encoding тақырыбын дұрыс береді — билд ең кіші болады.
Decompression Fallback	өшірулі	Қоссаңыз билд ~30% ауырлайды. Бізде қажеті жоқ.
Run In Background	қосулы	Ойыншы басқа қойындыға өткенде ойын тоқтап қалмайды.
Enable Exceptions	None немесе Explicitly Thrown	Билд өлшемін едәуір азайтады.
Strip Engine Code	қосулы	Қолданылмайтын код алынып тасталады.
Data Caching	қосулы	Қайта кіргенде ойын жылдам ашылады (IndexedDB).

Unity 2021 LTS және одан жаңа нұсқалары ұсынылады.

2. SDK скриптін қосу

Unity-дің әдепкі WebGL шаблонын көшіріп алып, өз шаблоныңызды жасаңыз:

Assets/
└── WebGLTemplates/
    └── SAQA/
        ├── index.html
        └── thumbnail.png   (міндетті емес)

index.html ішіндегі <head> бөліміне бір жол қосыңыз:

index.html

<script src="https://saqa.app/sdk/v1.js"></script>

Содан кейін Player Settings → Resolution and Presentation → WebGL Template тізімінен «SAQA» шаблонын таңдаңыз.

3. Плагин файлдарын қосу

Екі файлды жобаңызға көшіріңіз:

SaqaSDK.jslib

Assets/Plugins/WebGL/

C# пен браузердің арасын жалғайды

Жүктеу →

SaqaSDK.cs

Assets/Saqa/

Кодтан шақыратын C# оралымы

Жүктеу →

.jslib файлы міндетті түрде Assets/Plugins/WebGL/ ішінде жатуы керек — Unity оны сол жерден ғана байланыстырады.

4. Кодтан қолдану

Ойын басталғанда бір рет Init шақырыңыз. Барлық әдіс асинхронды — жауап callback арқылы келеді.

using Saqa;
using UnityEngine;

public class GameBootstrap : MonoBehaviour
{
    void Start()
    {
        SaqaSDK.Init(available =>
        {
            if (!available)
            {
                // Платформадан тыс ашылған (немесе редактор) — қонақ режимі
                Debug.Log("SAQA SDK қолжетімсіз");
                return;
            }

            Debug.Log(SaqaSDK.IsAuthorized
                ? $"Сәлем, {SaqaSDK.PlayerName}!"
                : "Қонақ режимі");

            SaqaSDK.GameReady();      // жүктелу экранын жабады
            LoadProgress();
        });
    }
}

Бұлттық сақтау

// Сақтау — JSON нысанын жолмен береміз
SaqaSDK.SetData("{\"level\":7,\"coins\":250}", res =>
{
    if (res.NeedsAuth) ShowLoginHint();   // кірмеген ойыншы
    else if (!res.Ok)  Debug.LogWarning(res.Error);
});

// Оқу
[System.Serializable]
class Save { public int level; public int coins; }

void LoadProgress()
{
    SaqaSDK.GetData(res =>
    {
        if (!res.Ok) return;
        var save = res.As<Save>();
        Debug.Log($"Деңгей: {save.level}, тиын: {save.coins}");
    }, "level", "coins");
}

Лидерборд

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

SaqaSDK.SetScore("score", 12500);

SaqaSDK.GetEntries("score", res =>
{
    if (!res.Ok) return;
    var board = res.As<SaqaLeaderboard>();
    foreach (var e in board.entries)
        Debug.Log($"{e.rank}. {e.player.name} — {e.score}");

    if (board.userEntry != null)
        Debug.Log($"Сіздің орныңыз: {board.userEntry.rank}");
}, quantityTop: 10);

Жарнама

// Толықэкранды
Time.timeScale = 0f;
SaqaSDK.ShowFullscreenAd(_ => Time.timeScale = 1f);

// Сыйақылы — тек rewarded=true болғанда сыйлық беріңіз
SaqaSDK.ShowRewardedAd(res =>
{
    var ad = res.As<SaqaAdResult>();
    if (res.Ok && ad.rewarded) GiveBonus();
    Time.timeScale = 1f;
});

Өмірлік цикл

SaqaSDK.GameReady();       // ресурстар жүктелді
SaqaSDK.GameplayStart();   // раунд басталды
SaqaSDK.GameplayStop();    // пауза, мәзір немесе ойын соңы

GameplayStart/Stop сессия ұзақтығын есептеуге керек — кабинеттегі статистика содан жиналады.

5. Архивтеп жүктеу

Билд қалтасының ішіндегісін ZIP-ке жинаңыз. Бір ғана түбір қалта болса да жарайды — ол автоматты алынып тасталады.

MyGame.zip
├── index.html
├── Build/
│   ├── MyGame.loader.js
│   ├── MyGame.framework.js.br
│   ├── MyGame.data.br
│   └── MyGame.wasm.br
└── TemplateData/
    └── ...

Одан кейін кабинетте жаңа ойын жасап, архивті жүктеңіз де модерацияға жіберіңіз.

Шектеулер

• ZIP архиві: 200 МБ дейін
• Тарқатылған өлшем: 512 МБ дейін
• Файл саны: 20 000 дейін
• Бұлтта сақталатын деректер: бір ойынға 256 КБ
• Көп ағынды билдтер (SharedArrayBuffer) әзірге қолдау таппайды — Player Settings ішінде threads өшірулі болуы керек

Әдеттегі Unity WebGL билді Brotli-мен 5–50 МБ болады, сондықтан шектеулерге еркін сыяды.

Жиі кездесетін қателер

Ойын ақ экранда тұрып қалды

Браузер консолін ашыңыз (F12). Көбіне себебі — Build қалтасындағы файл атауының сәйкес келмеуі: билдті қайта жасап, ZIP-ті толық жинаңыз.

«Unable to parse Build/...framework.js.br»

Файл Content-Encoding тақырыбынсыз берілген. Бізде бұл дұрыс бапталған — егер өз серверіңізде тексеріп жатсаңыз, .br файлдарына Content-Encoding: br қосу керек.

SaqaSDK.IsAvailable әрқашан false

WebGL шаблонына SDK скрипті қосылмаған. 2-қадамды тексеріңіз: <script src="/sdk/v1.js"> тегі index.html ішінде болуы керек.

Редакторда SDK жұмыс істемейді

Бұл — қалыпты жағдай. Редакторда IsAvailable = false болады да, ойын қонақ режимінде жүреді. Тексеру үшін WebGL билдін жасап, кабинетке жүктеңіз.

Деректер сақталмайды

res.NeedsAuth тексеріңіз: кірмеген ойыншыда бұлттық сақтау жұмыс істемейді. Мұндайда PlayerPrefs-ке жергілікті сақтап, кейін синхрондаңыз.

Толық SDK анықтамасы (барлық әдіс пен қате кодтары) — Games SDK құжаттамасында.