Подключение GamePush к игре со своим бэкендом

Для кого этот гайд

У вас уже есть клиент игры и свой бэкенд. Прогресс, баланс и награды вы храните сами. GamePush нужен, чтобы выйти на площадки: авторизация, платежи, реклама и события платформы — без замены вашего сервера.

Компонент	За что отвечает
Клиент игры	Вызовы GamePush SDK: профиль, вход, покупки, реклама, готовность / пауза / звук
GamePush	Площадки, платежи, подпись игрока, вебхуки
Ваш сервер	Сессия, прогресс, проверка подписи, начисление покупок

1. Добавить игру в GamePush

1. Войдите в панель и добавьте игру.
2. Откройте Публичную зону.

Вам понадобятся три значения:

Значение	Где используется
ID проекта (projectId)	На клиенте: загрузка SDK
Публичный ключ (publicToken)	На клиенте: загрузка SDK
Секретный ключ	Только на сервере: проверка подписи игрока и платежей

Создайте секретный ключ, если его ещё нет.

warning

Храните секретный ключ только на сервере. Не добавляйте его в код игры, не отправляйте в браузер и не публикуйте в репозитории или на скриншотах. С этим ключом можно подделать данные игрока и уведомления об оплате.

3. Откройте Доверенные сайты, добавьте адреса вроде http://localhost:3000 и staging. Для локальной и staging-проверки включите для них галочку Тестовый.

2. Подключить SDK

Чтобы получить готовый скрипт для встраивания GamePush SDK, воспользуйтесь разделом Добавление игры: подставьте свои projectId и publicToken.

window.onGPInit = async (gp) => {
    await gp.player.ready;
    // SDK и профиль игрока доступны
};

После onGPInit дождитесь gp.player.ready, прежде чем читать профиль или запускать сценарии площадки.

3. iframe и перезагрузка страницы

На площадках игра почти всегда открывается внутри iframe: снаружи страница площадки, внутри — ваша игра.

SDK рассчитан на то, что документ игры в этом фрейме живёт всю сессию. Если внутри фрейма сделать полную перезагрузку страницы (location.reload(), переход по ссылке на «ту же» игру, кнопка «Рестарт», которая обновляет страницу), код игры и незавершённые вызовы SDK обрываются. Скрипт может загрузиться снова, но площадка уже привязана к старому запуску и часто не поднимает SDK повторно в том же фрейме. После этого реклама, покупки и другие методы могут перестать отвечать — пока игрок не закроет игру и не откроет её снова через площадку.

Поэтому:

• экраны, уровни и «начать заново» делайте сменой состояния в уже загруженной странице, без перезагрузки;
• не уничтожайте и не создавайте заново iframe с игрой, когда игрок просто переходит по меню снаружи (на странице площадки или в вашей оболочке).

Если без перезагрузки фрейма не обойтись, делайте полный перезапуск игры через площадку, а не просто обновляйте страницу внутри iframe.

4. Авторизовать игрока и проверить подпись

Когда SDK готов, на клиенте уже есть профиль GamePush. Его можно показать в интерфейсе, но одному ID с клиента доверять нельзя — его легко подменить. Чтобы сервер понял, какой игрок к нему обращается, клиент передаёт gp.player.authToken, а бэкенд проверяет подпись.

Клиент

Дождитесь gp.player.ready. Дальше доступны поля профиля (gp.player.id, gp.player.isLoggedIn и другие) — полный список в разделе Менеджер игрока.

Если игроку нужно войти через площадку или выйти:

await gp.player.login();
await gp.player.logout();

При запросах к своему API отправляйте на сервер gp.player.authToken. При желании можно добавить gp.player.id только для дополнительной сверки.

Что такое gp.player.authToken

Это JWT. GamePush подписывает его секретным ключом проекта алгоритмом HS256. Токен появляется после готовности или синхронизации игрока.

warning

Если секретный ключ в панели не создан, строка будет пустой — сначала создайте ключ в Публичной зоне.

Внутри токена, в частности:

Поле	Смысл
sub	ID игрока в GamePush. Ему можно доверять только после проверки подписи
credentials	Идентификатор этого игрока на площадке
exp	Срок действия — 15 минут

Подробнее — в разделе Токен авторизации для своего бэкенда.

Сервер

На бэкенде:

1. Проверьте JWT секретным ключом проекта.
2. Возьмите ID игрока из поля sub.
3. Если клиент ещё прислал playerId в теле запроса — сравните его с sub. При расхождении отклоните запрос.
4. Дальше работайте как обычно: откройте свою сессию или привяжите игрока к своему аккаунту. Обычно authToken один раз обменивают на вашу сессию и не передают JWT GamePush в каждом запросе: у него короткий срок жизни (15 минут).

Пример проверки:

import jwt from 'jsonwebtoken';

const payload = jwt.verify(authToken, projectSecret, { algorithms: ['HS256'] });
const playerId = Number(payload.sub);
// дальше — ваша сессия для playerId

$decoded = JWT::decode($authToken, new Key($projectSecret, 'HS256'));
$playerId = (int) $decoded->sub;

warning

Без проверенного authToken не принимайте playerId с клиента. Публичный ключ (publicToken) для этой проверки не подходит — нужен секретный ключ проекта на сервере.

5. Смена ID игрока на вашей стороне

У гостя в GamePush тоже есть свой player.id. Профиль на клиенте может смениться не только после ваших кнопок «Войти» / «Выйти»: игрок вошёл на площадке, сменил аккаунт или вышел. После этого ID и authToken уже другие — прежнюю серверную сессию использовать нельзя.

На клиенте удобнее подписаться на события профиля, а не ждать только результат login() / logout():

gp.player.on('sync', onPlayerUpdated);
gp.player.on('load', onPlayerUpdated);
gp.player.on('logout', () => {
    // профиль ещё обновляется — пока остановите запросы со старой сессией
});

async function onPlayerUpdated(success) {
    if (!success) return;
    // заново отправьте authToken на свой сервер и откройте сессию для нового ID
}

После входа или выхода вызовите gp.player.load(), чтобы получить свежий профиль и JWT. Не на всех площадках выход через SDK доступен — перед показом кнопки «Выйти» проверяйте gp.platform.isLogoutAvailable. Подробнее про вход и выход — в разделе Менеджер игрока.

На вашем бэкенде:

Ситуация	Что происходит в GamePush	Что сделать у себя
Гость авторизовался	Может смениться player.id	Закрыть гостевую сессию. Открыть сессию для нового ID после проверки нового authToken. Переносить ли гостевой прогресс в аккаунт — решаете вы; GamePush сам это не сделает
Авторизованный сменил аккаунт	Другой player.id	Не отдавать данные прежнего игрока. Привязать запросы к новому ID
Авторизованный вышел	Снова гость (другой или прежний гостевой профиль)	Закрыть сессию авторизованного игрока. Дождаться нового профиля и authToken, открыть сессию для актуального ID

Клиент должен сразу перестать отправлять старый токен сессии. Если сессию нужно завершить и на сервере в тот же момент — сделайте у себя отдельный запрос на отзыв; иначе токен действует до конца своего срока.

6. Заполнить список покупок в GamePush

Покупки и подписки в SDK работают только с товарами, которые заведены в проекте GamePush — раздел Покупки. Без этого списка вызвать оплату и обработать выдачу на своём сервере не получится.

У каждого товара нужен стабильный тег (tag) — по нему вы обращаетесь к товару из кода (GOLD_1000, VIP и т. п.). Название и переводы можно менять; тег лучше не менять. Для подписки дополнительно включают признак подписки и период — см. Подписки.

Как заполнить каталог

Есть два варианта:

1. Вручную — создайте товары в Покупках: тег, название, описание, цена.

2. Импортом:

   1. Откройте Покупки → Export to CSV/JSON и выгрузите шаблон CSV GamePush (или текущий список, если обновляете).

   2. Заполните строки: для новых товаров поле id оставьте пустым; обязательно укажите tag, имена и цены (realPrices.* / цены площадок — по колонкам шаблона).

   3. В панели нажмите Import from CSV, проверьте превью и подтвердите импорт.

   4. В игре после gp.player.ready убедитесь, что товары видны SDK, например:

      gp.payments.products.find((product) => product.tag === 'GOLD_1000');

Другие варианты — импорт с Яндекс Игр, произвольный CSV, обновление существующих записей по id — описаны в разделе Импорт и экспорт покупок.

Для теста достаточно товаров в панели и тестового адреса. Перед выходом на площадку часто нужны её собственные ID товаров и настройки — см. Настройка платежей на площадках.

7. Покупки и подписки

Оплату проводят GamePush и площадка. Не начисляйте товар на сервере только по запросу от клиента — такой запрос легко подделать. Доверяйте подписанному вебхуку, который GamePush присылает на ваш бэкенд.

1. Клиент открывает оплату через SDK.
2. GamePush отправляет на ваш сервер вебхук о покупке.
3. Сервер проверяет подпись и один раз начисляет покупку по purchase._id.
4. Клиент узнаёт у вашего API, что выдача прошла, и подтверждает доставку в GamePush через consume.

Клиент

const result = await gp.payments.purchase({ tag: 'GOLD_1000' });
// result.purchase._id — id конкретной транзакции

if (gp.payments.isSubscriptionsAvailable) {
    await gp.payments.subscribe({ tag: 'VIP' });
}

Методы и параметры — в разделах Платежи и Подписки.

Вебхук

1. Нужен URL вашего сервера, доступный из интернета. Для локальной разработки подойдёт туннель или сразу staging.
2. В панели откройте Доверенные сайты → Webhooks и укажите URL. Для тестовых игроков включите галочку Тестовый.
3. В Настройках уведомлений отметьте нужные события. В интерфейсе они называются так:

В панели	Событие в вебхуке (event)
Купить покупку игроком	PurchasePlayerPurchase
Отменить подписку игрока	CancelPlayerSubscription
Возобновить подписку игрока	ResumePlayerSubscription
Подписка игрока истекла	ExpirePlayerSubscription

Для разовых покупок достаточно первого. Для подписок включите все четыре.

Тело вебхука: base64payload.signature (это не JWT). Подпись — SHA-256 от строки base64payload_secretKey, где secretKey — секретный ключ проекта из Публичной зоны. Полный формат — в разделе Webhooks.

import crypto from 'node:crypto';

function readWebhook(body, projectSecret) {
    const [encoded, signature] = String(body).split('.');
    const expected = crypto
        .createHash('sha256')
        .update(`${encoded}_${projectSecret}`)
        .digest('hex');

    if (expected !== signature) throw new Error('invalid_signature');

    return JSON.parse(Buffer.from(encoded, 'base64').toString('utf8'));
}

После проверки подписи:

• обработайте событие PurchasePlayerPurchase;
• начисляйте только при purchase.orderStatus === 'PAID';
• размер награды берите на своём сервере по product.tag, а не из клиента;
• один purchase._id — одно начисление: повторный вебхук с тем же _id не должен выдать товар снова.

Подписки

Для подписки приходят тот же вебхук покупки и события отмены, возобновления и истечения подписки (см. таблицу выше). Храните у себя дату окончания доступа и, если нужно, флаг автопродления. Доступ лучше проверять по дате конца периода: после отмены автопродления оплаченный срок обычно ещё действует.

Подтвердить выдачу (consume)

consume не меняет ваш баланс — он сообщает GamePush, что покупка уже обработана у вас. Вызывайте его только после успешного начисления на сервере.

Подтверждайте выдачу по _id конкретной транзакции, а не по тегу товара целиком:

await gp.payments.consume({ purchaseId: purchase._id });

Один и тот же товар (GOLD_1000) можно купить много раз — у каждой оплаты свой _id. То же подтверждение можно вызвать с сервера через API GamePush; на клиенте обычно достаточно SDK. См. Платежи.

При запуске игры проверьте список gp.payments.purchases: если начисление у вас уже есть, а consume ещё не вызывали — подтвердите покупку по _id. Иначе игрок мог закрыть вкладку сразу после оплаты.

8. Показать рекламу

В SDK рекламой управляет менеджер gp.ads: через него показывают ролики и баннеры на площадке. Перед показом проверьте, доступен ли нужный формат прямо сейчас — это зависит от площадки и ограничений по частоте.

GamePush поддерживает:

• fullscreen — gp.ads.showFullscreen();
• rewarded video — gp.ads.showRewardedVideo();
• preloader — gp.ads.showPreloader();
• sticky-баннер — gp.ads.showSticky().

if (gp.ads.isFullscreenAvailable) {
    await gp.ads.showFullscreen();
}

if (gp.ads.isRewardedAvailable) {
    const success = await gp.ads.showRewardedVideo();
    // success === true — ролик досмотрен
}

if (gp.ads.isPreloaderAvailable) await gp.ads.showPreloader();
if (gp.ads.isStickyAvailable) await gp.ads.showSticky();

Если за просмотр рекламы вы даёте награду на своём сервере, одного ответа SDK в браузере недостаточно — нужна ваша серверная проверка.

Провайдеры и настройка блоков — в разделе Реклама.

9. Обязательные методы SDK

Площадке нужно знать, что игра загрузилась, на каком языке интерфейс и когда ставить игру на паузу или отключать звук. Для этого в SDK есть общие методы — см. Основные возможности и Звуки.

Готовность игры

Когда ресурсы загружены и первый экран готов к взаимодействию, сообщите площадке:

await gp.gameStart();

Не путайте этот вызов с gp.gameplayStart() / gp.gameplayStop() — они отмечают начало и конец геймплея (раунд, уровень), а не загрузку игры. Сами по себе они игровую логику не запускают и не останавливают.

Язык

Язык приходит от площадки или SDK в gp.language (ISO 639-1). Перевод интерфейса вы делаете сами. Подпишитесь на смену языка:

gp.on('change:language', () => {
    // обновите строки интерфейса под gp.language
});

Пауза

SDK выставляет флаг gp.isPaused и отправляет события pause / resume — например, когда вкладка уходит в фон или показывается реклама. На паузе остановите геймплей и ввод у себя. Запросы, которые уже ушли на ваш сервер, SDK не отменяет.

gp.on('pause', () => { /* поставить игру на паузу */ });
gp.on('resume', () => { /* продолжить */ });

Звук

Перед воспроизведением эффектов и музыки смотрите флаги SDK. При отключении звука или на паузе остановите текущее воспроизведение. После возобновления не включайте звук принудительно — снова проверьте флаги.

gp.sounds.isSFXMuted;
gp.sounds.isMusicMuted;

gp.sounds.on('mute', () => { /* остановить звук */ });
gp.sounds.on('mute:sfx', () => { /* остановить эффекты */ });

10. Обратная связь

Чтобы игрок мог написать в поддержку из игры, откройте встроенный диалог GamePush:

await gp.feedbacks.open();

Свою форму и чат на сервере для этого поднимать не обязательно. Обращения появятся в панели проекта в разделе Feedback — там же можно ответить игроку, сменить статус и оставить служебное сообщение, которое игрок не увидит.

Подробности API и настройки — в разделе Обратная связь.

11. Как протестировать интеграцию с SDK GamePush

Проверьте интеграцию локально, на staging и в песочнице GamePush. Адреса тестовых версий добавьте в Доверенные сайты и отметьте как Тестовые, чтобы они не смешивались с продакшеном.

Localhost

На localhost удобно проверить загрузку SDK, профиль игрока, проверку authToken на своём сервере и смену сессии при входе, выходе и смене аккаунта. Платежные уведомления на обычный localhost с интернета не приходят: для покупок нужен публичный адрес (туннель) или проверка уже на staging.

Staging (dev origin)

Основная проверка перед площадкой. Добавьте staging-адрес в доверенные сайты, тестовый webhook направьте на staging-сервер. Пройдите цикл целиком: покупка → проверка подписи → начисление по purchase._id → consume. Для подписки отдельно проверьте, что после отмены автопродления доступ остаётся до конца оплаченного срока.

Песочница GamePush

Песочница открывается из раздела Хостинг игр в панели проекта: загрузите билд или укажите URL своей сборки (staging / туннель) и нажмите Протестировать игру. Так можно проверить gameStart, паузу, отключение звука, смену языка, рекламу и обратную связь, не публикуя игру на площадку.

Проверяем сценарии

Дополнительно проверьте:

• при смене экранов и «начать заново» страница во iframe не перезагружается;
• повторное уведомление с тем же purchase._id не начисляет покупку второй раз;
• если вкладку закрыли сразу после оплаты, при следующем запуске покупка доначисляется и подтверждается через consume по _id;
• после входа гостя, смены аккаунта и выхода у вас открывается сессия для актуального ID игрока.

Если нужно разобраться в работе SDK, включите логи параметром _gp_logs=1 в адресе игры — см. Отладка. В тестовом режиме также доступны инструменты разработчика.

Перед публикацией проверьте игру и на самой площадке: вход, покупки и реклама могут работать иначе, чем в песочнице GamePush. Перед отправкой на модерацию пройдите также чек-лист тестирования.

12. Что дальше

Дальше остаётся подключить игру к нужным площадкам и пройти их модерацию. Перед отправкой сверьтесь с чек-листом тестирования.

Оставайтесь на связи

С другими разделами документации вы можете ознакомиться здесь. Для начала работы вы можете ознакомиться с нашими туториалами.

Сообщество GamePush в Telegram: @gs_community.

Для ваших обращений e-mail: official@gamepush.com

Желаем вам успехов!