Реклама

SDK предоставляет возможности для монетизации игры через показ рекламы.

Доступны три типа рекламы: preloader, fullscreen и rewarded. Вы самостоятельно выбираете, какой тип рекламы использовать, исходя из общих рекомендаций по сохранению комфортного пользовательского опыта и правил показа для каждого типа рекламы.

ℹ️

Вызов рекламы не является обязательным условием для публикации игры. Если вы не хотите использовать рекламную монетизацию, просто не вызывайте её из игры 😊

Общий порядок показа рекламы

1. Проверка доступности показа рекламы.
2. Приостановка игрового процесса и фонового аудио, вызов рекламы и ожидание завершения показа.
3. Возобновление игрового процесса.

Проверка возможности показа рекламы

Конкретный тип рекламы может не поддерживаться, либо быть недоступен для показа в текущий момент.

Проверить возможность показа рекламы можно с помощью флага isSupported и метода canShow(), которые имеются у каждого типа рекламы:

isSupported: boolean;
canShow(): Promise<boolean>;

isSupported определяет, поддерживается ли показ данного типа рекламы у игрока. Значение статично и не меняется в течение игровой сессии.

canShow() определяет, доступен ли показ данного типа рекламы в текущий момент. Метод нужно вызывать непосредственно перед каждым показом рекламы.

Пример определения возможности показа рекламы:

// тип рекламы: preloader
const isPreloaderAdSupported = sdk.ads.preloader.isSupported;
const canShowPreloaderAd = await sdk.ads.preloader.canShow();

// тип рекламы: fullscreen
const isFullscreenAdSupported = sdk.ads.fullscreen.isSupported;
const canShowFullscreenAd = await sdk.ads.fullscreen.canShow();

// тип рекламы: rewarded
const isRewardedAdSupported = sdk.ads.rewarded.isSupported;
const canShowRewardedAd = await sdk.ads.rewarded.canShow();

Показ рекламы

У каждого типа рекламы есть метод show для показа рекламы:

show(): Promise<{ rendered: true; } | { rendered: false; reason: AdError; }>;

Метод возвращает Promise с результатом показа. Флаг rendered означает, было ли отображено окно с рекламным блоком.

Если показ рекламы недоступен, то rendered вернёт false и в поле reason будет указана причина (см. подробнее в разделе Коды ошибок).

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

Пример:

const canShowAd = await sdk.ads.fullscreen.canShow();

if (canShowAd) {
	// приостановка игрового процесса перед показом окна с рекламой
	pauseGame();

	await sdk.ads.fullscreen.show();

	// возобновление игрового процесса после показа рекламы
	resumeGame();
}

⚠️

canShow() и show() возвращают Promise, поэтому важно не забыть дождаться результата с помощью await или .then.

Типы рекламы

Preloader

Рекламный баннер, который показывается игрокам на этапе загрузки игры. Таймер при показе не используется, игроки сразу смогут закрыть рекламу.

Так как игроки видят баннер почти сразу после запуска игры, этот тип рекламы сильнее всего влияет на метрики игры, при этом является самым дешёвым форматом.

Показ доступен только на мобильных устройствах до вызова sdk.gameStarted().

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

const loadGameResourcesPromise = loadGameResources();

// инициализация SDK
const sdk = await PkbSDK.init();

// проверка, можно ли показать preloader-рекламу
const canShowAd = await sdk.ads.preloader.canShow();

// ожидание загрузки ресурсов и завершения показа рекламы
await Promise.all([
  loadGameResourcesPromise,
  canShowAd ? sdk.ads.preloader.show() : Promise.resolve(),
]);

// запуск игры и информирование sdk о готовности игры
await startGame();
sdk.gameStarted();

ℹ️

Для рекламы типа Preloader допускается не ставить игру на паузу и продолжать загрузку ресурсов. Но музыку ставить на паузу обязательно, если она присутствует на экране загрузки

Fullscreen

Формат рекламы для использования в перерывах игрового процесса (например, между уровнями).

Игрок может закрыть рекламу только по истечении таймера в 5 секунд.

Повторный показ ограничен интервалом не менее 120 секунд с момента предыдущего показа.

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

async function onLevelFinished() {
  // проверка, можно ли показать fullscreen-рекламу в данный момент
  const canShowAd = await sdk.ads.fullscreen.canShow();

  // приостановка игрового процесса и показ рекламы
  if (canShowAd) {
	pauseGame();

    await sdk.ads.fullscreen.show();
  }

  // возобновление игрового процесса (переход к экрану следующего уровня)
  openNextLevelScreen();
}

💡

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

Rewarded

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

Самый дорогой формат, но сильно влияет на игровой опыт из-за долгого таймера.

Ограничений на частоту показа нет.

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

async function showRewardedAdForCoins() {
  // проверка, можно ли показать rewarded-рекламу в данный момент
  const canShowAd = await sdk.ads.rewarded.canShow();
  if (!canShowAd) {
    return;
  }

  // приостановка игрового процесса и показ рекламы
  pauseGame();
  const result = await sdk.ads.rewarded.show();


  // возобновление игрового процесса
  resumeGame();

  // проверка результата и выдача награды
  if (result.reward) {
    addCoins(100);
  }
}

💡

Вызывайте баннер только по явному действию пользователя в игре (например, по нажатию на кнопку показа рекламы в обмен на вознаграждение). Из-за долгого таймера этот тип рекламы сильно влияет на метрики игры и может «убить» удержание игроков и время игровой сессии

Выдача награды

Метод sdk.ads.rewarded.show() возвращает поле reward, указывающее, следует ли выдать пользователю награду.
Значение true возвращается, если пользователь досмотрел рекламу до конца.
Значение false возвращается, если пользователь закрыл окно с рекламой, не дожидаясь окончания таймера, либо если у пользователя установлен блокировщик рекламы.

⚠️

Не выдавайте награду только по факту нажатия на кнопку в игре. Дождитесь результата show() и проверьте флаг reward.

Коды ошибок

Если показ рекламы недоступен в текущий момент, метод show() возвращает rendered: false и код ошибки в поле reason:

Код	Что означает
NOT_SUPPORTED	Формат рекламы не поддерживается в текущем окружении или на устройстве игрока.
IN_PROGRESS	Другой показ рекламы уже идёт.
UI_BUSY	Интерфейс платформы занят другим окном.
COOLDOWN_ACTIVE	Для формата действует ограничение частоты показа.
INVALID_GAME_STATE	Формат вызван не в том состоянии игры: например, preloader после gameStarted().
UNKNOWN	Неизвестная ошибка.

Обработка ошибок и недоступности

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

Рекомендуем:

• не показывать игроку технические ошибки в интерфейсе;
• не оставлять игру на паузе, если реклама не открылась;
• скрывать или делать неактивными рекламные кнопки после неуспешной проверки canShow();
• логировать причину ошибки в консоль или собственную аналитику;
• предусмотреть fallback: обычное продолжение игры, покупка за внутриигровую валюту, ожидание восстановления доступности.

Пример безопасного показа:

async function showFullscreenAdSafely() {
  const canShowAd = await sdk.ads.fullscreen.canShow();

  if (!canShowAd) {
    return false;
  }

  pauseGame();
  const result = await sdk.ads.fullscreen.show();
  resumeGame();

  if (!result.rendered) {
    console.warn('Реклама не показана:', result.reason);
    return false;
  }

  return true;
}

Описание типов

type AdError =
  | 'NOT_SUPPORTED'
  | 'IN_PROGRESS'
  | 'UI_BUSY'
  | 'COOLDOWN_ACTIVE'
  | 'INVALID_GAME_STATE'
  | 'UNKNOWN';

type BaseAdResult =
  | { rendered: true; }
  | { rendered: false; reason: AdError; };

type RewardedAdResult = BaseAdResult & {
  reward: boolean;
};

type AdApi = {
  isSupported: boolean;
  canShow(): Promise<boolean>;
  show(): Promise<BaseAdResult>;
};

type RewardedAdApi = {
  isSupported: boolean;
  canShow(): Promise<boolean>;
  show(): Promise<RewardedAdResult>;
};

type AdsApi = {
  fullscreen: AdApi;
  preloader: AdApi;
  rewarded: RewardedAdApi;
};