Mission Pawsible Game SDK

Введение

Mission Pawsible Game SDK - это библиотека для интеграции игр в Telegram Mini App с поддержкой встраивания через iframe.

Установка

Установка пакета

После настройки registry установите пакет:

npm install @1paws1/game-sdk

Импорт

import { MissionPawsibleSDK } from "@1paws1/game-sdk";

Инициализация

Создание экземпляра SDK

const sdk = new MissionPawsibleSDK({
  clientId: "your-client-id",
  debug: false, // опционально
  apiUrl: "https://backend.missionpawsible.game", // опционально
});

Параметры конструктора (Options)

clientId (обязательный)

• Тип: string
• Описание: Уникальный идентификатор клиента, полученный при интеграции с Mission Pawsible платформой. Используется для аутентификации при запросах к API.

debug (опциональный)

• Тип: boolean
• По умолчанию: false
• Описание: Включает режим отладки. При true в консоль будут выводиться логи работы SDK для диагностики проблем.

apiUrl (опциональный)

• Тип: string
• По умолчанию: "https://backend.missionpawsible.game"
• Описание: URL адрес API бекенда Mission Pawsible. Используется для получения подмененного initData при работе в интегрированном режиме.

Методы SDK

init()

Инициализирует SDK и настраивает интеграцию с Telegram WebView.

⚠️ ВАЖНО: Метод init() должен вызываться до вызова Telegram.WebApp.ready() или любых других методов Telegram SDK.

Пример использования:

const sdk = new MissionPawsibleSDK({
  clientId: "your-client-id",
  debug: true,
});

// Вызывайте init() ПЕРЕД Telegram.WebApp.ready()
sdk.init();

// Теперь можно безопасно использовать Telegram SDK
Telegram.WebApp.ready();

Возвращаемое значение: void

Свойства после инициализации:

• sdk.isInitialized - true, если SDK успешно инициализирован
• sdk.isIntegrated - true, если игра запущена в интегрированном режиме (через Mission Pawsible платформу)

authorize<T>(callback: AuthorizeCallback<T>): Promise<T>

Используется для получения и подмены initData перед отправкой на ваш бекенд.

⚠️ ВАЖНО: Метод authorize() используется для подмены initData. В интегрированном режиме SDK автоматически получает новый initData с сервера Mission Pawsible, который должен использоваться вместо оригинального.

Пример использования:

const authData = await sdk.authorize(async ({ isIntegrated, initData }) => {
  // Отправка initData на ваш бекенд
  const response = await fetch("https://your-backend.com/auth", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      initData: initData,
      isIntegrated: isIntegrated,
    }),
  });

  return await response.json();
});

Параметры:

• callback - Асинхронная функция, которая получает объект с параметрами:
  • isIntegrated: boolean - флаг, указывающий работает ли игра в интегрированном режиме
  • initData: string - строка initData для отправки на бекенд (уже подмененная, если isIntegrated = true)

Что делает метод:

1. Если isIntegrated = false:

   • Использует оригинальный initData из window.Telegram.WebApp.initData
   • Вызывает callback с оригинальными данными

2. Если isIntegrated = true:

   • Проверяет, что SDK инициализирован (выбросит ошибку, если init() не был вызван)
   • Отправляет запрос на ${apiUrl}/integration/auth с clientId и оригинальным initData
   • Получает новый подмененный initData с сервера
   • Вызывает callback с подмененным initData

Возвращаемое значение: Promise<T> - результат выполнения callback функции

Ошибки:

• Error: "SDK not initialized" - если метод вызван до init() в интегрированном режиме

getOptions(): Options

Возвращает текущие опции SDK.

Пример использования:

const options = sdk.getOptions();
console.log(options.clientId); // 'your-client-id'
console.log(options.debug); // false
console.log(options.apiUrl); // 'https://backend.missionpawsible.game'

Возвращаемое значение: Объект Options с текущими настройками SDK

Работа с бекендом

⚠️ КРИТИЧЕСКИ ВАЖНО: Валидация initData на бекенде

При отправке initData на ваш бекенд, обязательно проверяйте значение isIntegrated:

Если isIntegrated = false:

• Валидируйте initData используя Bot Father token (стандартная валидация Telegram)

Если isIntegrated = true:

• НЕ используйте Bot Father token для валидации
• Используйте secret значение, которое вы получили при интеграции вместе с clientId
• Этот secret используется для валидации подмененного initData, полученного от Mission Pawsible API

Пример валидации на бекенде:

// Псевдокод для примера
async function validateInitData(initData: string, isIntegrated: boolean) {
  if (isIntegrated) {
    // Используйте secret, полученный при интеграции
    const secret = getIntegrationSecret(clientId);
    return validateWithSecret(initData, secret);
  } else {
    // Используйте Bot Father token
    const botToken = process.env.BOT_TOKEN;
    return validateWithBotToken(initData, botToken);
  }
}

Полный пример использования

import { MissionPawsibleSDK } from "@1paws1/game-sdk";

// 1. Создание экземпляра SDK
const sdk = new MissionPawsibleSDK({
  clientId: "your-client-id",
  debug: process.env.NODE_ENV === "development",
});

// 2. Инициализация ПЕРЕД Telegram.WebApp.ready()
sdk.init();

// 3. Теперь можно использовать Telegram SDK
Telegram.WebApp.ready();

// 4. Использование authorize для получения подмененного initData
async function authenticate() {
  try {
    const userData = await sdk.authorize(async ({ isIntegrated, initData }) => {
      // Отправка на ваш бекенд
      const response = await fetch("https://your-backend.com/auth", {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          initData,
          isIntegrated,
        }),
      });

      if (!response.ok) {
        throw new Error("Authentication failed");
      }

      return await response.json();
    });

    console.log("User authenticated:", userData);
    return userData;
  } catch (error) {
    console.error("Authentication error:", error);
    throw error;
  }
}

// 5. Вызов аутентификации
authenticate();

Отладка

Для включения режима отладки установите debug: true при создании экземпляра SDK:

const sdk = new MissionPawsibleSDK({
  clientId: "your-client-id",
  debug: true,
});

В консоли браузера вы увидите подробные логи:

• Инициализация SDK
• Проверка режима интеграции
• Запросы к API для получения подмененного initData
• Обработка событий от родительского окна

Типы

type Options = {
  clientId: string;
  debug?: boolean;
  apiUrl?: string;
};

type AuthorizeCallbackParams = {
  isIntegrated: boolean;
  initData: string;
};

type AuthorizeCallback<T> = (params: AuthorizeCallbackParams) => Promise<T>;

Поддержка

При возникновении проблем проверьте:

1. ✅ init() вызван до Telegram.WebApp.ready()
2. ✅ clientId указан корректно
3. ✅ В интегрированном режиме используется правильный secret для валидации на бекенде
4. ✅ Включен режим отладки для диагностики (debug: true)