SDK для разработчиков

Quick start

1. В index.html твоей игры подключи SDK:

   <script src="https://igraytut.ru/sdk/v1/sdk.js"></script>

2. В своём коде (после загрузки DOM):

   (async () => {
     const ctx = await IgrayTut.init({ gameId: "your-game-slug" });
     console.log("Привет,", ctx.user?.displayName ?? "гость");
   
     // Сохранение
     await IgrayTut.storage.save({ level: 5, coins: 1200 });
   
     // Аналитика
     IgrayTut.analytics.event({ name: "level_complete", properties: { level: 5 } });
   })();

3. gameId — slug твоей игры в каталоге ИграйТут (тот же что в URL /games/[slug]). Узнать можно в карточке игры в кабинете разработчика.

Модули

storage. Облачные сохранения

Сохраняет JSON-объект, привязанный к пользователю и игре. Перезаписывает целиком.

// Сохранить
await IgrayTut.storage.save({ level: 5, coins: 1200, inventory: ["sword"] });

// Загрузить (null если нет сохранения)
const data = await IgrayTut.storage.load();
if (data) restoreState(data);

// Удалить
await IgrayTut.storage.remove();

Для гостей (не залогинен) возвращает 401. Игра должна использовать localStorage как fallback.

analytics. События

IgrayTut.analytics.event({
  name: "level_complete",             // snake_case, до 50 символов
  properties: {                        // до 10 пар; значения до 200 символов
    level_id: "forest_03",
    duration_sec: 92,
    score: 15000,
  },
});

// Helper для уровней
IgrayTut.analytics.levelComplete("forest_03", 92, 15000);

Rate-limit 100 событий/мин на юзера. События старше 30 дней удаляются.

leaderboard. Лидерборды

Сначала создай лидерборд в /dev/games/[id]/leaderboards (имя, сортировка, maxRealisticScore, minPlayDurationSec).

// Отправить результат (обновится только если лучше предыдущего)
const { rank, isPersonalBest } = await IgrayTut.leaderboard.submit({
  name: "best_score",
  score: 42000,
  metadata: { level: 5 },
});
if (isPersonalBest) showToast("Новый рекорд!");

// Получить топ + свою позицию
const { top, self, total } = await IgrayTut.leaderboard.get("best_score", {
  limit: 10,
});
// top: [{ rank, userId, username, displayName, avatarUrl, score }, ...]
// self: запись текущего юзера (может быть вне топа)
// total: общее число записей

Антифрод: submit с score > maxRealisticScore скрывается (юзер получает успех, но в публичном топе не появляется). Rate-limit 1/мин на юзера+лидерборд.

achievements. Достижения

Создай ачивки в /dev/games/[id]/achievements (code, название, описание, опц. targetValue для прогресс-шкалы, isSecret).

// Простая ачивка
const { firstTime } = await IgrayTut.achievements.unlock({ id: "first_kill" });
if (firstTime) showAchievementToast("Первая победа!");

// Ачивка с прогресс-шкалой (targetValue = 100)
await IgrayTut.achievements.unlock({ id: "100_coins", progress: 42 });
// Когда progress >= target, автоматически разблокируется

// Получить список разблокированных
const list = await IgrayTut.achievements.list();
// [{ id: "first_kill", unlockedAt: "2026-04-17T..." }, ...]

Все ачивки игрока по всем играм на /profile/achievements. Rate-limit 30 unlock/мин.

payments. Внутриигровые покупки (IAP)

Создай товары в /dev/games/[id]/iap (code, цена в рублях, consumable / non_consumable).

// Показать список товаров
const items = await IgrayTut.payments.getItems();
// [{ itemId, title, description, priceRub, iconUrl, kind }, ...]

// Купить (откроется ЮKassa, после успеха резолвится с succeeded)
const result = await IgrayTut.payments.purchase({ itemId: "100_coins" });
if (result.status === "succeeded") {
  giveCoins(100);
}

// Проверить одноразовый товар
if (await IgrayTut.payments.has("remove_ads")) {
  disableAds();
}

// Все купленные non-consumable (для восстановления после переустановки)
const owned = await IgrayTut.payments.getOwned();

Чек формируется через «Мой налог» автоматически (54-ФЗ). На MVP весь доход идёт оператору платформы; 70/30 с разработчиком в v2 после перехода на ИП.

ads. Реклама

API готово, но все методы возвращают { shown: false, reason: "not_configured" }до подключения РСЯ/AdsGram (после 1 мес трафика). Код игры можно писать сразу. Когда реклама подключится, он заработает без изменений.

// Rewarded. Вознаграждение за просмотр
const { rewarded } = await IgrayTut.ads.showRewarded({ placement: "extra_life" });
if (rewarded) grantExtraLife();

// Interstitial. Между уровнями
await IgrayTut.ads.showInterstitial({ placement: "level_complete" });

// Для Premium-пользователей interstitial резолвится мгновенно без показа

Локализация

В настройках игры (`/dev/games/[id]/edit`) укажи поддерживаемые языки. SDK при инициализации выдаст игре итоговую локаль исходя из приоритета: tester override, профиль юзера, заголовок Accept-Language, fallback на первый язык из списка.

const ctx = await IgrayTut.init({ gameId: "your-slug" });
const lang = ctx.locale;  // "ru" | "en" | "uk" | "kk" | "be"

const i18n = await import(`./locales/${lang}.json`).catch(() =>
  import("./locales/ru.json")  // fallback
);
document.getElementById("title").textContent = i18n.title;

Если игра поддерживает только русский, укажи в форме только ru. Тогда SDK всегда вернёт locale === "ru".

Таблица миграции с Яндекс.Игр

Файлы SDK

Перед публикацией

Прежде чем отправлять игру на модерацию, ознакомься с правилами модерации и офертой разработчика. Это сократит число итераций с модератором и ускорит публикацию.