Ресурсы¶

Ресурсы — это ZIP-пакеты, которые содержат пользовательский JavaScript (и необязательные CSS/медиа-файлы), используемые для показа демонстрации зачисления пользователям, когда они получают объект (например: “Gift” или “Key”). UI запускает скрипт Ресурса в браузере, чтобы отображать анимации/уведомления и другие визуальные эффекты.

Объекты без Ресурса не показываются пользователю в потоке демонстрации зачисления.

Шаги¶

Перейдите в Геймификация → Ресурсы.
Создайте Ресурс и загрузите пакет .zip.
Убедитесь, что zip содержит обязательный входной файл: index.js.
Привяжите/назначьте Ресурс объекту, который должен быть видим пользователям (пример: Gift / Key).
Запустите зачисление этого объекта (награда/достижение/квест/событие) и проверьте, что пользователь видит демонстрацию.

Документация JS¶

Что запускается и когда (сценарий выполнения)¶

Действие пользователя (или системное событие) приводит к тому, что платформа зачисляет пользователю один или несколько объектов (награда, завершение достижения, шаг квеста и т. д.).
Клиент проверяет зачисленные объекты и выбирает те, к которым привязан Ресурс.
Для каждого подходящего объекта клиент загружает файлы пакета Ресурса и выполняет index.js.
Скрипты выполняются через очередь (по одному скрипту за раз).
Скрипт должен вызвать GameObjectAssetScript.complete() по завершении, чтобы мог запуститься следующий скрипт.

Структура пакета Ресурса¶

Загружаемый Ресурс — это .zip файл со следующей структурой:

my-asset.zip
├─ index.js        (required)
├─ style.css       (optional)
├─ images/         (optional)
│  ├─ gift.png
│  └─ key.png
├─ sounds/         (optional)
│  └─ reward.mp3
└─ data/           (optional)
   └─ config.json

Правила:

index.js должен находиться в корне zip.

Любые дополнительные файлы можно организовывать по папкам.

Используйте вспомогательные API для загрузки CSS/JS и для получения URL к медиа-файлам внутри Ассета.

Жизненный цикл скрипта

Клиент загружает и выполняет скрипт из index.js.
Скрипт читает данные текущего события через GameObjectAssetScript.getContext().
Скрипт выполняет UI-действия (уведомления/анимации/и т. д.).
Скрипт завершает работу вызовом GameObjectAssetScript.complete().

Если complete() не вызван, очередь скриптов блокируется и последующие скрипты не запускаются.

Объект контекста¶

Используйте GameObjectAssetScript.getContext() для доступа к информации о текущем запуске.

Пример:

(function () {
  "use strict";

  const context = GameObjectAssetScript.getContext();

  // контекст должен содержать:
  // - информацию об объекте (что было зачислено / списано)
  // - информацию о пользователе (текущий пользователь)
  // - информацию о событии (что запустило скрипт)
  // Точные поля зависят от события платформы.

  console.log("Asset context:", context);

  // Всегда заканчивать скрипт:
  GameObjectAssetScript.complete();
})();

Система очереди скриптов

Скрипты Ресурсов выполняются последовательно. Платформа запускает один скрипт и ждёт его завершения перед стартом следующего.

Обязательное правило:

Всегда вызывайте GameObjectAssetScript.complete() ровно один раз (даже если произошла ошибка).

Рекомендуемый шаблон:

(function () {
  "use strict";

  try {
    // Ваша логика тут
  } catch (e) {
    console.error("Asset script error:", e);
  } finally {
    GameObjectAssetScript.complete();
  }
})();

Методы API¶

`GameObjectAssetScript.getContext()`¶

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

const context = GameObjectAssetScript.getContext();
console.log(context);

`GameObjectAssetScript.complete()`¶

Сигнализирует, что скрипт завершился. Это обязательно.

GameObjectAssetScript.complete();

`GameObjectAssetScript.addCssFile(path)`¶

Загружает CSS-файл из пакета Ресурса и внедряет его на страницу.

GameObjectAssetScript.addCssFile("style.css");

`GameObjectAssetScript.addJsFile(path)`¶

Загружает дополнительный JS-файл из пакета Ресурса.

GameObjectAssetScript.addJsFile("libs/extra.js");

`GameObjectAssetScript.getFileUrl(path)`¶

Возвращает URL к файлу внутри пакета Ресурса (полезно для изображений/аудио).

const imgUrl = GameObjectAssetScript.getFileUrl("images/gift.png");
const audioUrl = GameObjectAssetScript.getFileUrl("sounds/reward.mp3");

`GameObjectAssetScript.notify(title, message, type, durationMs)`¶

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

GameObjectAssetScript.notify(
  "Reward received",
  "You got a Gift!",
  "success",
  5000
);

Примеры¶

Пример 1 — Простое уведомление¶

(function () {
  "use strict";

  try {
    const context = GameObjectAssetScript.getContext();

    GameObjectAssetScript.notify(
      "Reward received",
      "Your reward has been deposited.",
      "success",
      4000
    );
  } finally {
    GameObjectAssetScript.complete();
  }
})();

Пример 2 — Скрипт с внешними файлами (CSS + изображение)

(function () {
  "use strict";

  function renderGift(imgUrl) {
    const wrap = document.createElement("div");
    wrap.style.position = "fixed";
    wrap.style.left = "50%";
    wrap.style.top = "20%";
    wrap.style.transform = "translateX(-50%)";
    wrap.style.zIndex = "99999";

    const img = document.createElement("img");
    img.src = imgUrl;
    img.alt = "Gift";
    img.style.maxWidth = "220px";

    wrap.appendChild(img);
    document.body.appendChild(wrap);

    setTimeout(() => wrap.remove(), 3000);
  }

  try {
    GameObjectAssetScript.addCssFile("style.css");

    const imgUrl = GameObjectAssetScript.getFileUrl("images/gift.png");
    renderGift(imgUrl);

    GameObjectAssetScript.notify("Gift", "A Gift was deposited to you.", "success", 3000);
  } catch (e) {
    console.error(e);
  } finally {
    GameObjectAssetScript.complete();
  }
})();

Частые ошибки¶

Отсутствует index.js в корне zip.

Неверные пути к файлам (пример: вызов getFileUrl("gift.png")), когда файл images/gift.png).

Не вызывается GameObjectAssetScript.complete() (блокирует очередь).

Логика не обёрнута в try/finally (ошибки мешают вызову complete()).

Рабочий процесс разработчика (рекомендуется)¶

Создайте папку для Ресурса (пример: gift-demo/).
Добавьте index.js (обязательно) и любые необязательные ресурсы (style.css, images/, sounds/, data/).
Заархивируйте в zip содержимое папки так, чтобы index.js был в корне zip (не внутри дополнительной родительской папки).
Загрузите zip в Геймификация → Ресурсы.
Назначьте Ресурс целевому объекту (Gift/Key).
Запустите событие зачисления и проверьте:

скрипт выполняется,

UI отображается,

complete() вызывается,

объект видим пользователю во время демонстрации зачисления.