@agru/sdk

Мост между iframe игры и ag.ru

Установка

# npm
npm i @agru/sdk
# yarn
yarn add @agru/sdk
# pnpm
pnpm add @agru/sdk

Установка используя CDN

Внимание
Скрипт необходимо вставить перед вашим основным скриптом игры!

<script src="https://unpkg.com/@agru/sdk/dist/umd/index.min.js"></script>

Начало работы

import { AgRuSdk } from '@agru/sdk';

const sdk = new AgRuSdk({
  // ...
});

Используя CDN версию, класс AgRuSdk доступен глобально.

const sdk = new AgRuSdk({
  // ...
});

API

Параметры, которые ag.ru автоматически передает в настройки.

• app_id - Идентификатор игры
• auth_key - Зашифрованная строка в HMAC SHA256 16-бит: "{app_id}._.{player_id}._.{game_sid}"
• game_sid - Идентификатор игровой сессии
• invite - Идентификатор приглашения игрока, если передать в ссылке к игре: https://ag.ru/games/my-game?invite=xxx
• player_id - Идентификатор игрока

options

Объект с настройками SDK.

{
  app_id: string;
  auth_key: string;
  invite: string;
  game_sid: string;
  player_id: string;
}

Методы SDK

enum AgRuSdkMethods {
  Authorize = 'agru-authorize',
  GetSaveData = 'agru-getSaveData',
  GetUsers = 'agru-getUsers',
  IsAppUser = 'agru-isAppUser',
  SayHello = 'agru-sayHello',
  ShowCampaign = 'agru-showCampaign',
  ShowPayment = 'agru-showPayment',
  SetSaveData = 'agru-setSaveData',
  ToggleFullscreen = 'agru-toggleFullscreen',
}

authorize

Вызвать диалоговое окно авторизации. Метод вернет ответ, как только окно авторизации откроется, не дожидаясь самой авторизации!

const [[data, error]] = await sdk.authorize();

или

sdk.authorize(([data, error]) => {
  // ...
});

Пример ответа:

true

authorizeAndWait

Вызвать диалоговое окно авторизации и ждать ответа.

const [[data, error]] = await sdk.authorizeAndWait();

или

sdk.authorizeAndWait(([data, error]) => {
  // ...
});

Пример ответа:

true

getSaveData

Получить игровые данные пользователя с сервера.

const [[data, error]] = await sdk.getSaveData();

или

sdk.getSaveData(([data, error]) => {
  // ...
});

Пример ответа:

{
  "ключ": "значение"
}

getUsers

Получить информацию о пользователях.

Необходимо передать массив ID пользователей (максимум 10).

const [[data, error]] = await sdk.getUsers(['aa6b41ff51004c3890321606db6d4c69', '33c1c11404fcda000000000', '56bc75e2d63100000']);

или

sdk.getUsers(['aa6b41ff51004c3890321606db6d4c69', '33c1c11404fcda000000000', '56bc75e2d63100000'], ([data, error]) => {
  // ...
});

Пример ответа:

{
  /**
   * Ссылка на аватар пользователя.
   */
  avatar: string;

  /**
   * Полное имя пользователя.
   */
  fullname: string;

  /**
   * Идентификатор пользователя.
   */
  id: number;

  /**
   * Никнейм пользователя.
   */
  username: string;
}

isAppUser

Относится ли пользователь к данной игре.

Необходимо передать ID пользователя.

const [[data, error]] = await sdk.isAppUser(1001);

или

sdk.isAppUser(1001, ([data, error]) => {
  // ...
});

Пример ответа:

true;

off

Перестать слушать событие и обрабатывать.

Необходимо передать ключ метода или ключ события и обработчик.

import { AgRuSdkMethods } from '@agru/sdk';

function handleHello((data, error) => {
  if (data == 42) {
    sdk.off(AgRuSdkMethods.SayHello, handleHello); // перестаем слушать.
  }
})

sdk.on(AgRuSdkMethods.SayHello, handleHello);

или используя CDN версию

function handleHello((data, error) => {
  if (data == 42) {
    sdk.off(AgRuSdkMethods.SayHello, handleHello); // перестаем слушать.
  }
})

sdk.on(AgRuSdkMethods.SayHello, handleHello);

on

Слушать событие и обрабатывать.

Необходимо передать ключ метода или ключ события и обработчик.

import { AgRuSdkMethods } from '@agru/sdk';

sdk.on(AgRuSdkMethods.SayHello, (data, error) => {
  // ...
});

или используя CDN версию

sdk.on(AgRuSdkMethods.SayHello, (data, error) => {
  // ...
});

Возвращает метод отписки от прослушивания события.

const unlistenHello = sdk.on(AgRuSdkMethods.SayHello, (data, error) => {
  // ...
});

sdk.on(AgRuSdkMethods.SayHello, (data, error) => {
  // этот код продолжит выполняться
});

// в любом месте в коде
unlistenHello() // перестаем слушать SayHello

once

Слушать событие и обработать один раз.

Необходимо передать ключ метода или ключ события и обработчик.

import { AgRuSdkMethods } from '@agru/sdk';

sdk.once(AgRuSdkMethods.SayHello, (data, error) => {
  // ...
});

или используя CDN версию

sdk.once(AgRuSdkMethods.SayHello, (data, error) => {
  // ...
});

sayHello

Вывести приветственную фразу. Показывает, что инициализация прошла успешно.

const [[data, error]] = await sdk.sayHello();

или

sdk.sayHello(([data, error]) => {
  // ...
});

Пример ответа:

"And here's Johnny";

showCampaign

Показать рекламную кампанию.

const [[data, error]] = await sdk.showCampaign('default');

или

sdk.showCampaign('default', ([data, error]) => {
  // ...
});

Пример ответа:

{
  status: true,
  type: 'default',
};

Показать мотивированную рекламу (rewarded video).

const [[data, error]] = await sdk.showCampaign('rewarded');

или

sdk.showCampaign('rewarded', ([data, error]) => {
  // ...
});

Пример ответа:

{
  // Становится "true", когда пользователь досмотрел до конца рекламу.
  reward: false,

  status: true,
  type: 'rewarded',
};

Пример отслеживания состояния:

let isCampaignVisible = false;

sdk.on(AgRuSdkMethods.ShowCampaign, ({ status, type }) => {
  if (type === 'rewarded') {
    // Проверка на rewarded video.
  }

  isCampaignVisible = status;
});

// Показываем баннер.
sdk.showCampaign('default');

// Показываем видео рекламу.
sdk.showCampaign('rewarded');

showPayment

Показать окно оплаты.

const [[data, error]] = await sdk.showPayment('token');

или

sdk.showPayment('token', ([data, error]) => {
  // ...
});

Пример ответа:

{
  info: {
    // подробнее о статусах: https://developers.xsolla.com/doc/pay-station/integration-guide/open-payment-ui/
    status: 'delivering',
    email: '[email protected]',
    invoice: 9999999999,
    virtualCurrencyAmount: null,
    userId: "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    discount: null
  },

  // статус отображения окна оплаты.
  status: true,
};

Пример отслеживания состояния:

let isPaymentVisible = false;

sdk.on(AgRuSdkMethods.ShowPayment, ({ info, status }) => {
  isPaymentVisible = status;

  // Не выполняем код ниже, пока окно оплаты отображается.
  if (status) {
    return;
  }

  // Если человек закрыл окно оплаты, то не выполняем код ниже.
  if (info == null) {
    return;
  }

  if (info.invoiceId) {
    // проверяем у себя на сервере прошла оплата или нет.
  }
});

sdk.showPayment('token');

setSaveData

Сохранить игровые данные пользователя на сервер.

const [[data, error]] = await sdk.setSaveData({
  ключ: 'значение',
});

или

sdk.setSaveData(
  {
    ключ: 'значение',
  },
  ([data, error]) => {
    // ...
  }
);

Пример ответа:

true;

toggleFullscreen

Переключить режим полного экрана.

await sdk.toggleFullscreen();

или

sdk.toggleFullscreen();

Пример ответа:

true;

События SDK

enum AgRuSdkEvents {
  OptionsUpdates = 'agru-optionsUpdates',
}

OptionsUpdates

Вызывается, когда AG обновляет параметры игры в реальном времени, к примеру после авторизации.

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

// Какое-то глобальное состояние игры.
const state = {
  user: { ... },
};

sdk.on(AgRuSdkEvents.OptionsUpdates, async (newOptions) => {
  // Обновляем параметры SDK.
  sdk.options = { ...sdk.options, ...newOptions };

  // Проверяем поменялся ли ID игрока.
  if (sdk.options.player_id == state.user.id) {
    return;
  }

  // Если ID поменялся, получаем новые данные и обновляем.
  const [[data]] = await sdk.getUsers([sdk.options.player_id]);
  state.user = data[0];
});