universalSDK · Документация

Интеграция за 3 минуты

Консоль
Консоль

🚀 Быстрый старт

Интеграция universalSDK за 3 минуты.

1. Скопируйте файл скрипта и вставьте в проекте: Project → Scripts → правый клик → Paste.

После копирования — Ctrl+V в окне Scripts браузера Construct 3. Файл usdk.js будет создан автоматически.

2. Инициализируйте SDK: Event Sheet → правый клик → Add action → Add JavaScript:

usdkInit("APP_ID", "API_KEY");

APP_ID и API_KEY → консоль разработчика → зарегистрируйте игру. Готово! Все методы ниже доступны через usdk.* в любом Add JavaScript.

⚠️ Глобальные переменные: везде где используется runtime.globalVars.xxx — создайте одноимённую переменную в Project → Global variables (Number или String).

📢 Реклама

Rewarded, Interstitial и Banner — единый API для всех платформ.

🎁 Rewarded

usdk.showRewarded("100 coins");

Колбэки: On_Rewarded_Show, On_Rewarded_Success, On_Rewarded_Close, On_Rewarded_Error. Проверьте tag = "100 coins" → выдайте награду в On_Rewarded_Success.

⏸ Interstitial

usdk.showInterstitial("level_end");

Колбэки: On_Interstitial_Show, On_Interstitial_Close. В On_Interstitial_Close — продолжите игру.

📌 Banner

usdk.showBanner("bottom");  // "bottom" | "top"
usdk.hideBanner();

Колбэки: On_Banner_Show, On_Banner_Hide.

Позиция top/bottom работает на VK, OK и CrazyGames. Yandex — всегда низ. Poki, GD, Telegram — баннеры не поддерживаются (usdk.isSupported("banner") = false).

🏆 Таблица лидеров

Submit score, показ лидерборда, запрос позиции игрока.

usdk.leaderboard.submitScore(runtime.globalVars.coins);
usdk.leaderboard.show(10);
usdk.leaderboard.show(10, true);  // cross-platform

Колбэки: On_Score_Submitted и On_Leaderboard_Shown. ⚠️ Переменную coins создайте в Project → Global variables.

usdk.leaderboard.getTop(10);
usdk.leaderboard.getPlayerRank();

Колбэк: On_Leaderboard_Top с JSON-массивом. getPlayerRank вызывает On_Player_Rank с позицией.

💾 Сохранения

Ключ-значение и Dictionary-сохранения.

🔑 Key-Value

usdk.save("coins", runtime.globalVars.coins);
usdk.load("coins").then(v => { runtime.globalVars.coins = v });

Колбэк: On_Save_Done / On_Load_Done. ⚠️ coins — глобальная переменная (Project → Global variables).

📖 Dictionary

saveDict("yourDictionary");
loadDict("yourDictionary");

Сохраняет/загружает весь C3 Dictionary с указанным именем через On_Save_Done / On_Load_Done.

👤 Игрок

Авторизация и данные игрока.

usdk.authorizePlayer().then(() => {
    runtime.globalVars.playerName = usdk.adapter.playerName || "";
});

// or just get name
usdk.getPlayerName().then(n => {
    runtime.globalVars.playerName = n || "?";
});

// platform language
usdk.getLanguage().then(v => {
    runtime.globalVars.language = v;
});

Колбэки: On_Auth_Success / On_Auth_Fail. ⚠️ Переменные playerName, language нужно создать в Project → Global variables.

🔗 Социальные функции

Share, Invite, Join Community, Rate.

usdk.share({ text: "Score: " + runtime.globalVars.coins });
usdk.inviteFriends();
usdk.joinCommunity();
usdk.rateGame();
usdk.addToFavorites();
usdk.clipboardWrite("universalSDK " + location.href);

Колбэки: On_Share_Done, On_Invite_Done, On_Join_Done/On_Join_Fail, On_Rate_Done, On_AddedToFav.

🎮 Геймплей

Сигналы начала/конца игры и проверка блокировщика рекламы.

usdk.gameplayStart();
usdk.gameplayStop();
usdk.checkAdBlock();
usdk.happyTime();

gameplayStart/Stop — сигналы для платформ (пауза/продолжение). Колбэки: On_AdBlock_Detected, On_HappyTime.

🏆 Достижения

Система достижений с прогрессом. 1 usdkCoin за операцию.

// Add action → Add JavaScript
usdk.achievements.setProgress("highScore", 80);
usdk.achievements.unlock("firstGame");
usdk.achievements.show();

Колбэки: On_Achievement_Unlocked(id, title, icon) — 3 String, и On_Achievement_Progress(id, progress) — String + Number. show() открывает оверлей (бесплатно).

🎯 Квесты

Система квестов с прогрессом и наградами. 1 usdkCoin за операцию.

🎯 Настройка: Консоль → ваша игра → кнопка 🎯 → Создать квест (ID, название, иконка, цель, награда).
// Add action → Add JavaScript
usdk.quests.progress("kill10", 1);  // +1 к прогрессу
usdk.quests.show();               // открыть оверлей

Колбэк: On_Quest_Completed(id, title) — 2 String. show() открывает оверлей (бесплатно).

🎁 Ежедневные награды

7-дневный цикл наград. Показ бесплатно, забрать награду — 1 usdkCoin.

🎁 Настройка: Консоль → ваша игра → кнопка 🎁 → выберите иконку для каждого дня (эмодзи или своя картинка — Pro/Max).
// Add action → Add JavaScript
usdk.dailyRewards.show();  // открыть оверлей

Колбэк: On_DailyReward_Claimed(day, streak) — 2 Number. show() — бесплатно, забрать награду — 1 usdkCoin.

🔔 VK/OK Миссии

Привязка достижений к миссиям ВКонтакте и Одноклассников. Когда игрок разблокирует достижение в игре — миссия платформы завершается и друзья получают уведомление. Бесплатно (native API, без usdkCoins).

⚙️ Требуется: 1) VK Service Token в форме игры в консоли; 2) ID и баллы миссии в редакторе достижения. Работает для платформ VK и OK (общая инфраструктура).

Настройка

  1. Создайте миссию в VK Games Dashboard → Соц. механики → Миссии.
  2. Скопируйте ID миссии и укажите требуемые баллы.
  3. В консоли universalSDK откройте игру и впишите VK Service Token (серверный токен приложения).
  4. В редакторе достижения (если в платформах игры есть VK или OK) впишите VK Mission ID и VK Mission Value.
usdk.achievements.unlock("firstGame");
// → достижение разблокируется + миссия VK/OK получает баллы → друзьям уведомление

Ошибки VK (нет миссии, неверный токен) тихо игнорируются — достижение в игре разблокируется в любом случае.

💬 Глобальный чат

Встроенный чат для игроков. Доступен на тарифах Pro и Max.

💡 Включите чат в консоли: Edit Game → ✅ Global Chat. Только для Pro/Max.
// Add action → Add JavaScript
usdk.openChat("MY CHAT");
// or without title (default "Chat")
usdk.openChat();

// crossPlatform: false (default) / true
usdk.openChat("CHAT", 20, false);
usdk.openChat("CHAT", 20, true);

Колбэк: On_Chat_Message(tag, text, playerName, platform) — 4 параметра. Срабатывает при каждом новом сообщении (кроме своих). crossPlatform = false (по умолчанию) — только своя платформа. true — все кроме Local.

📥 Загрузить историю вручную

// Add action → Add JavaScript
usdk.fetchChat(10);
usdk.fetchChat(10, false);  // default: own platform
usdk.fetchChat(10, true);   // cross-platform

fetchChat стоит 1 usdkCoin. Колбэки: On_Chat_Loaded(count) — один раз с количеством, и On_Chat_Loaded_Message(text, playerName, platform) — на каждое сообщение автоматически (for-цикл не нужен).

🔔 Push-уведомления

Подписка на push-уведомления платформы. Бесплатно.

usdk.push.subscribe();

VK — нативное разрешение (VKWebAppAllowNotifications). Local (тест) — мок-попап. Возвращает {allowed: true/false}.

🎉 Конфетти

Эффект конфетти при разблокировках. Бесплатно.

usdk.achievements.setProgress("highScore", 80, true);  // 3-й параметр — конфетти
usdk.quests.progress("kill10", 1, true);
usdk.dailyRewards.show(true);

Параметр showConfetti (по умолчанию true): false — отключить конфетти для вызова. Колбэк: On_Confetti_Shown (для SFX/вибрации).

🛠 Утилиты

usdk.getLanguage().then(v => {  // "ru" | "en" | "tr"…
    runtime.globalVars.language = v;
});
usdk.clipboardWrite("text");  // copy to clipboard
usdk.checkAdBlock();          // adblock check

📋 API Reference

Полный список методов universalSDK.

МетодПараметрыВозвращаетusdkCoins
usdkInit(appID, apiKey)appID: string, apiKey: stringPromise<void>2
usdk.boot(appID, apiKey, runtime)appID: string, apiKey: string, runtime?: objectPromise<void>2
usdk.showRewarded(tag, onSuccess?, onClose?, onError?)tag: string, callbacks: functionsPromise<void>
usdk.showInterstitial(tag, onClose?)tag: string, onClose: functionPromise<void>
usdk.showBanner()Promise<void>
usdk.hideBanner()Promise<void>
usdk.leaderboard.submitScore(score)score: numberPromise<object>1
usdk.leaderboard.show(limit?, crossPlatform?)limit: number, crossPlatform: boolean (default false)Promise<object>
usdk.leaderboard.getTop(limit?)limit: number (default 10)Promise<Array>1
usdk.leaderboard.getPlayerRank()Promise<{rank, totalEntries}>1
usdk.save(key, value)key: string, value: anyPromise<void>1
usdk.load(key)key: stringPromise<any>1
saveDict(name)name: string (C3 Dictionary)Promise<void>1
loadDict(name)name: string (C3 Dictionary)Promise<void>1
usdk.authorizePlayer()Promise<void>
usdk.getPlayerName()Promise<string>
usdk.getLanguage()Promise<string>
usdk.share(data)data: {text?: string, url?: string}Promise<void>
usdk.inviteFriends()Promise<void>
usdk.joinCommunity()Promise<void>
usdk.rateGame()Promise<void>
usdk.addToFavorites()Promise<void>
usdk.clipboardWrite(text)text: stringPromise<void>
usdk.openChat(title?, limit?, crossPlatform?)title: string, limit: number, crossPlatform: boolean (default false)void (opens overlay)1
usdk.achievements.setProgress(id, progress)id: string, progress: numberPromise<object>1
usdk.achievements.unlock(id)id: stringPromise<object>1
usdk.achievements.get(id?)id: string (опционально)Promise<object>1
usdk.achievements.getAll()Promise<Array>1
usdk.achievements.show()void (opens overlay)
usdk.fetchChat(limit?, crossPlatform?)limit: number, crossPlatform: boolean (default false)Promise<Array> · C3 callbacks1
usdk.gameplayStart()Promise<void>
usdk.gameplayStop()Promise<void>
usdk.checkAdBlock()Promise<boolean>
usdk.happyTime()Promise<void>
usdk.quests.progress(id, value, showConfetti?)id: string, value: number, showConfetti: boolean (default true)Promise<{completed, newlyCompleted}>1
usdk.quests.getAll()Promise<Array>1
usdk.quests.show()void (opens overlay)
usdk.dailyRewards.show(showConfetti?)showConfetti: boolean (default true)void (opens overlay)
usdk.dailyRewards.getState()Promise<{day, streak, canClaim}>1
usdk.dailyRewards.claim()Promise<{day, streak}>1
usdk.push.subscribe()Promise<{allowed}>
usdk.showModal(title, desc, yes, no, tag?)title/desc: string, yes/no: string, tag: stringPromise<"yes"|"no">
usdk.isSupported(feature)feature: string (interstitial, rewarded, banner, playerAuth, share, invite, rate, clipboard, joinCommunity, adblock, addToHome, addToFav, leaderboards)Promise<boolean>
usdk.saveVar(name)name: string (C3 global var)Promise<void>1
usdk.loadVar(name)name: string (C3 global var)Promise<any>1
usdk.getPlayerId()Promise<string>
usdk.getPlatform()string (local, vk, ok, yandex, telegram, …)
usdk.addToHomeScreen()Promise<void>
usdk.addToFavorites()Promise<void>
usdk.tag(t)t: stringusdk (chainable)
🛡 Защита от исчерпания: При исчерпании usdkCoins срабатывает On_Quota_Exceeded — облачные операции автоматически переключаются на локальный режим (localStorage). Игра не блокируется.
🖥 Экран загрузки: Free — всегда включён; Pro/Max — можно отключить в консоли (Edit Game → Экран загрузки).