Assets¶

Assets are ZIP packages that contain custom JavaScript (and optional CSS/media files) used to show a deposit demonstration to users when they receive an object (for example: a “Gift” or a “Key”). The UI runs the Asset script in the browser to display animations/notifications and other visual effects.

Objects without an Asset are not shown to the user in the deposit demonstration flow.

Steps¶

Go to Gamification → Assets.
Create an Asset and upload a .zip package.
Ensure the zip contains a required entry file: index.js.
Link/assign the Asset to the object that must be visible to users (example: Gift / Key).
Trigger a deposit of this object (reward/achievement/quest/event) and verify that the user sees the demonstration.

JS documentation¶

What runs and when (runtime scenario)¶

A user action (or system event) causes the platform to deposit one or more objects to the user (reward, achievement completion, quest step, etc.).
The client checks deposited objects and selects those that have an Asset attached.
For each matching object, the client loads the Asset package files and executes index.js.
Scripts are executed through a queue (one script at a time).
The script must call GameObjectAssetScript.complete() when finished so the next script can run.

Asset package structure¶

The uploaded Asset is a .zip file with the following structure:

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

Rules: - index.js must be in the root of the zip.
- Any additional files can be organized into folders.
- Use helper APIs to load CSS/JS and to resolve URLs to media files inside the Asset.

Script lifecycle¶

The client loads and executes the script from index.js.
The script reads the current event data via GameObjectAssetScript.getContext().
The script performs UI actions (notifications/animations/etc.).
The script finishes by calling GameObjectAssetScript.complete().

If complete() is not called, the script queue is blocked and subsequent scripts will not run.

Context object¶

Use GameObjectAssetScript.getContext() to access information about the current run.

Example:

(function () {
  "use strict";

  const context = GameObjectAssetScript.getContext();

  // context may include:
  // - object info (what was deposited / withdrawn)
  // - user info (current user)
  // - event info (what triggered the script)
  // Exact fields depend on the platform event.

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

  // Always finish the script:
  GameObjectAssetScript.complete();
})();

Script queue system¶

Asset scripts are executed sequentially. The platform runs one script and waits for it to finish before starting the next.

Required rule: - Always call GameObjectAssetScript.complete() exactly once (even if there was an error).

Recommended pattern:

(function () {
  "use strict";

  try {
    // your logic here
  } catch (e) {
    console.error("Asset script error:", e);
  } finally {
    GameObjectAssetScript.complete();
  }
})();

API methods¶

`GameObjectAssetScript.getContext()`¶

Returns the context object for the current script execution.

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

`GameObjectAssetScript.complete()`¶

Signals that the script finished. This is mandatory.

GameObjectAssetScript.complete();

`GameObjectAssetScript.addCssFile(path)`¶

Loads a CSS file from the Asset package and injects it into the page.

GameObjectAssetScript.addCssFile("style.css");

`GameObjectAssetScript.addJsFile(path)`¶

Loads an additional JS file from the Asset package.

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

`GameObjectAssetScript.getFileUrl(path)`¶

Returns a URL to a file inside the Asset package (useful for images/audio).

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

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

Shows a user notification.

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

Examples¶

Example 1 — Simple notification¶

(function () {
  "use strict";

  try {
    const context = GameObjectAssetScript.getContext();

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

Example 2 — Script with external files (CSS + image)¶

(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();
  }
})();

Common mistakes¶

Missing index.js in the zip root.
Using wrong file paths (example: calling getFileUrl("gift.png") when the file is images/gift.png).
Not calling GameObjectAssetScript.complete() (blocks the queue).
Not wrapping logic with try/finally (errors prevent complete() call).

Developer workflow (recommended)¶

Create a folder for the Asset (example: gift-demo/).
Add index.js (required) and any optional resources (style.css, images/, sounds/, data/).
Zip the folder contents so that index.js is at the root of the zip (not inside an extra parent folder).
Upload the zip in Gamification → Assets.
Assign the Asset to the target object (Gift/Key).
Trigger a deposit event and validate: - the script executes, - the UI is shown, - complete() is called, - the object is visible to the user during the deposit demonstration.