Ресурси¶

Ресурси — це ZIP-пакети, що містять кастомний JavaScript (і необов’язкові CSS/медіафайли), які використовуються для показу демонстрації зарахування користувачам, коли вони отримують об’єкт (наприклад: “Подарунок” або “Ключ”). 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() викликається,

об’єкт видимий користувачу під час демонстрації зарахування.