Создать игру для TikTok в Combos

Сделаем Gift Arena: стример сражается с боссом, а зрители помогают энергией, лечением и атаками. Вы получите полный проект, локальный симулятор подарков, шаги публикации в Combos и порядок регистрации для настоящих подарков TikTok. Используется Combos SDK 1.1.0.

Играть в демо · Скачать полный проект

Сейчас нет доступного процесса активации реального взаимодействия TikTok. Можно разрабатывать, симулировать подарки и публиковать игру в Combos; публикация поста не включает настоящие подарки. Материалы интеграции и проверка LIVE готовят будущую активацию платформой, а не заявку, которую можно завершить сейчас.

1. Объявить подарки как игровые эффекты

Сначала определите правила, затем пишите подключение. Игрок начинает с 70 здоровья и 40 энергии, босс — со 100 здоровья. Атака расходует 10 энергии и наносит 10 урона. Выживший босс отвечает уроном 8. Зрители помогают тремя эффектами:

// rules.js — this game's contract
export const GIFT_CATALOG = Object.freeze({
  gift_battery: { target: 'energy', perCount: 20, max: 100 },
  gift_heal: { target: 'hp', perCount: 15, max: 100 },
  gift_flash: { target: 'bossHp', perCount: -10, max: 100 },
});

Это объявление находится в коде вашей игры. Оно не является вызовом регистрации SDK или каталогом TikTok. Батарея, Лечение и Вспышка — названия эффектов примера, а не настоящие имена или ID подарков TikTok. Не считайте, что Роза или определённая цена автоматически соответствуют эффекту.

Пример принимает целое количество от 1 до 1000, ограничивает здоровье и энергию значением 100, а здоровье босса снизу — нулём. Подарки не расходуют ход. Эффект на предельном значении считается успешным, даже если число больше не растёт. После победы или поражения новые команды возвращают false до следующего раунда. Это правила примера, не ограничения платформы. Продумайте накопление, перезарядку, переходы между раундами и дорогие эффекты и передайте те же правила настройщику соответствий.

2. Разделить обязанности игры и платформы

Зритель → настройка подарков TikTok → Combos → SDK onCommand → эффект в игре → логический результат → Combos → ACK TikTok.

Настроенное взаимодействие может дать instruction: "gift_flash", count: "3"; игра наносит 30 урона. count — количество команд после преобразования, не цена в монетах и не обязательно число подарков. Уточните и преобразование комбо при регистрации. Игра не должна самостоятельно читать launchData, подписывать запросы TikTok, создавать отдельный WebSocket или реализовывать webhook.

3. Реализовать контракт команд

type TTLiveCommand = {
  messageId: string;
  instruction: string;
  count: string;
  timestamp: string;
};

В публичной команде нет ID или имени зрителя и ID настоящего подарка. Нельзя строить рейтинг зрителей на полях, которых API не предоставляет.

Возвращайте true после подтверждённого сохранения эффекта, false при определённом отказе, а при неизвестном результате выбрасывайте исключение, например при ошибке хранения. Неизвестный результат не подтверждается и может быть доставлен повторно. Нельзя превращать все ошибки в успех или неопределённое частичное выполнение в подтверждённый отказ.

SDK повторно отправляет ожидающие результаты внутри документа. Игра должна обрабатывать и перезагрузку страницы. Пример сохраняет состояние и результат сообщения одной транзакцией IndexedDB и возвращает значение только после её завершения. Дубликат получает сохранённый результат. Новый раунд сохраняет квитанции. LIVE-данные разделены по аккаунту/игре Combos и отделены от тренировки.

Читать состояние соединения

getTTLiveClient() возвращает один клиент на документ игры. getLiveStatus() проверяет состояние, а onStatusChange() сразу сообщает текущее, затем изменения. Состояние содержит state, reason, action, confirmedAtMs: время последнего подтверждённого старта/heartbeat в миллисекундах, 0 означает неизвестность.

• connecting: начало соединения. connected: сессия взаимодействия подтверждена.
• recovering: дождаться переподключения SDK. unknown: нет текущего подтверждения; это не означает завершение трансляции.
• ended: сессия взаимодействия завершена. Следовать action: wait, none, relaunch_game. Для последнего заново открыть эту игру из LIVE Studio, а не перезапускать трансляцию из-за проблемы соединения.

4. Запустить полный проект

Подготовка и запуск

Скачайте и распакуйте ZIP. Нужны современный браузер и Python 3 для локального статического сервера; Node и npm не нужны. Сохраните структуру папки tiktok-arena:

cd tiktok-arena
python3 -m http.server 8080 --bind 127.0.0.1

Откройте http://127.0.0.1:8080/ и нажмите Начать тренировку. Не открывайте index.html двойным щелчком: модулям JavaScript нужен HTTP. Онлайн-демо работает без установки. Игра поддерживает те же десять языков, что и сайт.

Три воспроизводимых демо

Начинайте каждую из первых двух строк с нового раунда. Третья продолжает вторую без сброса. Начальные значения: здоровье 70, энергия 40, босс 100. Каждая кнопка подарка создаёт новое сообщение; Повторить последнее сообщение использует тот же ID.

Проверьте 0, 1.5, 1001, 9007199254740993: без эффекта, с false. Победите в новом раунде Вспышкой ×10 и отправьте новый подарок — он будет отклонён до следующего раунда. Используйте Атаку и Заряд для обычного боя. Панель доставки показывает вход, результат и итоговые значения. Синтетические локальные команды не покупают подарки и не отправляют ACK TikTok.

5. Подключить ту же игру в Combos

Сохраните connection.js и game.js при публикации. Combos внедряет window.combos; дополнительный npm SDK или второй скрипт SDK не нужен. Кнопка Подключить Combos LIVE:

1. Вызывает init() и проверяет возможность getTTLiveSession и getter клиента. Название возможности не является публичным методом для прямого вызова.
2. Выполняет checkSession() и при необходимости login() из нажатия. Отмена останавливает процесс, успех продолжает то же действие.
3. Использует getUserInfo() для разделения локальных сохранений. ID не являются секретными учётными данными или доказательством серверных прав.
4. Подписывается на состояние и вызывает getTTLiveClient().connect({ onCommand }) с обработчиком тренировки.
5. Оставляет Отключить / отменить доступной при повторах подключения. При отмене и выходе отписывается и вызывает disconnect().

Этот основной код уже есть в архиве; полная версия также обновляет интерфейс. store.update() — транзакция из storage.js, не API SDK:

import { executeCommand } from './rules.js';
 
// `store` is the account/game-scoped store opened by prepareStore().
function commandHandler(store) {
  return async (command) => {
    const { result } = await store.update((saved) =>
      executeCommand(saved, command),
    );
    return result; // State + receipt committed; no catch-and-return-false.
  };
}

connect() может долго оставаться в ожидании при повторах. Разрешённый Promise ещё не доказывает, что настоящий подарок сработал. LIVE скрывает кнопки симуляции. Проверяйте видимый эффект и результат в зарегистрированной сессии.

6. Опубликовать в Combos

Установите официальный Combos CLI . Нажмите Сохранить обложку PNG, поместите cover.png рядом с папкой tiktok-arena. Из родительской папки выполните:

combos --version
combos account login
combos post create --dir ./tiktok-arena --title 'Gift Arena' --cover ./cover.png --platform pc --screen-orientation landscape --allow-recommend=false
combos post get

Войдите в браузере под аккаунтом публикации. Откройте возвращённую ссылку и проверьте игру в плеере Combos. Сохраните созданный файл привязки combos.json. Из того же каталога обновляйте тот же пост:

combos post update --dir ./tiktok-arena --platform pc

Это статическая игра для PC в альбомной ориентации. В корне загружаемой папки должны находиться index.html и все относительные ресурсы. Публикация не включает TT. Обычная ссылка позволяет тренироваться, но без зарегистрированного контекста запуска LIVE Studio не создаёт реальную сессию. Подробнее — в руководстве H5.

7. Подготовить материалы для будущей интеграции

Доступного входа для активации и подтверждённого процесса реального подключения пока нет. Регистрация игры/аккаунтов и сопоставление подарков должны дождаться инструкций платформы; SDK и CLI не предоставляют публичный API самостоятельной регистрации. Подготовь следующие материалы для будущего процесса. Это подготовительный список, а не открытый приём заявок:

До теста подтвердите точный зарегистрированный вход в игру, разрешения игры/аккаунтов и активное соответствие подарков. Реальные ID, названия и цены берутся из настроенного каталога. При согласованной Вспышке ×3 игра должна получить:

{
  "instruction": "gift_flash",
  "count": "3"
}

Не помещайте в игру секреты TikTok, CAS-токены или вручную собранный launchData: ими занимается платформа. Без регистрации у вас есть опубликованная игра Combos и рабочий симулятор; реальная приёмка TikTok ещё не пройдена.

8. Проверить реальный LIVE после появления активации

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

1. Разрешённым аккаунтом откройте зарегистрированный вход из TikTok LIVE Studio, подключите игру и убедитесь в connected.
2. С согласия участника запустите настроенное тестовое взаимодействие. Запишите messageId, инструкцию/количество, значения до/после и результат. Попросите контакт подтвердить получение соответствующего ACK. Не записывайте секреты или персональные данные зрителей.
3. Проверьте согласованное комбо: количество × эффект, границы, отсутствие повторного эффекта при повторной доставке. Сравните с локальными демо.
4. Кратко отключите и восстановите сеть: известная команда не должна применяться снова. Перезагрузите страницу в поддерживаемом хостом сценарии, проверьте состояние/квитанции и следуйте указанию перезапустить игру, если оно появится.
5. Завершите взаимодействие, проверьте ended / relaunch_game, отмену при подключении и выход из игры. Старые команды не должны давать дополнительные эффекты.

Хранилище защищает только тот же браузер/origin/аккаунт/игру. Оно не обеспечивает восстановление между устройствами или доверенную игровую экономику. Не очищайте его во время LIVE. После 10 000 квитанций пример останавливает новые команды вместо удаления старых результатов. Для постоянных наград или промышленной нагрузки сохраняйте эффект и квитанцию вместе в собственном авторитетном backend и определяйте срок хранения по подтверждённым результатам.

Устранение проблем

Справочник SDK · Аккаунт и языки