Аккаунты и перевод

Сначала прочитай о доступности SDK и ошибках. Примеры используют внедрённый глобальный объект; игра не запрашивает учётные данные аккаунта.

Вход после действия игрока

Вызывай checkSession() прямо перед действием, которому нужен аккаунт. Если результат false, вызывай login() после явного действия игрока. Интерфейс входа управляется хостом. cancelled — нормальный выбор; сбои передачи, всплывающего окна или синхронизации аккаунта отклоняют Promise.

После success сразу продолжай действие. Не нужны перезагрузка, опрос или повторная проверка сессии для той же операции. Для следующего независимого действия проверь сессию заново. Пока запрос выполняется, отключи кнопку запуска.

<button id="player-button">Show player</button>
<output id="player-info" aria-live="polite"></output>

async function readPlayerAfterClick() {
  const sdk = window.combos;
  if (!sdk) return null;
  const { methods } = await sdk.init();
  if (!methods.includes("getUserInfo")) return null;
  if (!(await sdk.checkSession())) {
    const result = await sdk.login();
    if (result.status !== "success") return null;
  }
  return sdk.getUserInfo();
}
 
const button = document.querySelector<HTMLButtonElement>("#player-button");
const output = document.querySelector<HTMLOutputElement>("#player-info");
button?.addEventListener("click", async () => {
  if (!output) return;
  button.disabled = true;
  try {
    const player = await readPlayerAfterClick();
    output.textContent = player
      ? player.nickName || "Player"
      : "Player information is unavailable.";
  } catch {
    output.textContent = "Unable to read player information. Please try again.";
  } finally {
    button.disabled = false;
  }
});

Кнопки и сообщения — примеры игрового интерфейса; адаптируй их под языки игры. Функция возвращает null, если возможность отсутствует или вход отменён; реальные ошибки обрабатывает обработчик нажатия.

Чтение информации об игроке

getUserInfo() не принимает аргументы. Вызывай его после проверки сессии или успешного входа. Без входа запрос отклоняется с session_required.

Предусмотри замену отсутствующим данным для отображения. Сохраняй область действия идентичности в пределах приложения; не используй этот ответ как учётные данные или доказательство разрешений для своего сервера. В нём нет ID пользователя платформы, электронной почты или сессии Cloud Ability.

Перевод уже показанных текстов

Сначала покажи исходный текст, затем запроси перевод. sourceLocale задаёт язык исходника, а не желаемый целевой язык. Хост выбирает текущий язык продукта. sourceTexts содержит точные исходные строки или шаблоны; эти же строки служат ключами результата.

<button data-source-text="Play"></button>
<button data-source-text="Pause"></button>

async function localizeLabels() {
  const nodes = [...document.querySelectorAll<HTMLElement>("[data-source-text]")];
  const sourceTexts = nodes.map(node => node.dataset.sourceText ?? "");
  nodes.forEach((node, index) => { node.textContent = sourceTexts[index]; });
 
  const sdk = window.combos;
  if (!sdk) return;
  try {
    const { methods } = await sdk.init();
    if (!methods.includes("requestI18n")) return;
    const result = await sdk.requestI18n({ sourceLocale: "en", sourceTexts });
    if (!result.needed) return;
    nodes.forEach((node, index) => {
      const source = sourceTexts[index];
      node.textContent = result.translations[source] || source;
    });
  } catch {
    // Keep the source copy on screen.
  }
}
 
void localizeLabels();

Результат — { needed: false } или { needed: true, locale, translations }. Оставляй исходник, если перевод не нужен, ключ отсутствует, хост не поддерживает функцию или запрос завершился ошибкой. Некорректный результат SDK также превращается в needed: false. Вставляй перевод как текст, а не сырой HTML. Переводи стабильные шаблоны до подстановки динамических значений и меняй sourceLocale, если изменяешь английские исходники примера.

Дополнительные API Cloud Ability

Текущий Web-хост не объявляет следующие четыре метода. Используй их только при явном наличии в init().methods. Этот контракт не включает AI автоматически после публикации игры.

type Authorization = {
  decision: "AUTHORIZATION_DECISION_GRANTED" | "AUTHORIZATION_DECISION_DENIED";
  decidedAtMs: number;
};
type AuthSetting = Partial<Record<"ai_model", Authorization>>;
type CloudAbilitySession = { session: string; expiresAtMs: number };

AUTHORIZATION_DECISION_DENIED — нормальное решение, не сбой передачи. Не записывай нулевое значение UNSPECIFIED. Время указано в миллисекундах. Не отправляй ID пользователя, устройства или игры. Держи сессию только в памяти, соблюдай expiresAtMs, удаляй её после игры и никогда не помещай в хранилище, логи или URL.