RTSDK
    Preparing search index...

    Class Ecosystem

    Create an instance of Ecosystem class with optional session credentials

    import { Ecosystem } from "utils/topiaInit.ts";

    const ecosystem = await Ecosystem.create({
      credentials: { interactivePublicKey: "examplePublicKey", interactiveNonce: "exampleNonce", assetId: "exampleDroppedAssetId", visitorId: 1, urlSlug: "exampleUrlSlug" }
    });

    Hierarchy (View Summary)

    Index

    Data Objects

    fetchDataObject incrementDataObjectValue setDataObject updateDataObject

    Inventory

    fetchInventoryItems

    Moderation

    checkIsBannedString

    Other

    constructor credentials dataObject? jwt? requestOptions topia inventoryItems errorHandler topiaPublicApi

    Data Objects

    • Retrieves the data object for a Topia ecosystem. Requires canUpdateEcosystemDataObjects permission to be set to true for the public key.

      Parameters

      • OptionalappPublicKey: string
      • OptionalappJWT: string
      • OptionalsharedAppPublicKey: string
      • OptionalsharedAppJWT: string

      Returns Promise<void | ResponseType>

      Populates the dataObject property with ecosystem-wide data, or returns an error response.

      get, fetch, retrieve, load, ecosystem, data, object, state, global, platform

      const dataObject = await ecosystem.fetchDataObject("exampleAppPublicKey", "exampleAppPublicKeyJWT");

    • Increments a specific value in the data object for a Topia ecosystem by the amount specified. Must have valid interactive credentials from a visitor in the world.

      Parameters

      • path: string
      • amount: number
      • options: {
            analytics?: AnalyticType[];
            appJWT?: string;
            appPublicKey?: string;
            lock?: { lockId: string; releaseLock?: boolean };
            sharedAppJWT?: string;
            sharedAppPublicKey?: string;
        } = {}

      Returns Promise<void | ResponseType>

      Returns success or an error response.

      This method also allows you to increment a data object value on behalf of another Public Key. It requires canUpdateEcosystemDataObjects permission to be set to true for the Public Key.

      Optionally, a lock can be provided with this request to ensure only one update happens at a time between all updates that share the same lock id

      increment, increase, add, count, ecosystem, data, object, state, global, platform

      await ecosystem.incrementDataObjectValue("key", 1, {
        sharedAppPublicKey: "exampleAppPublicKey",
        sharedAppJWT: "exampleAppPublicKeyJWT",}
      });

    • Sets the data object for a Topia ecosystem.

      Parameters

      • dataObject: undefined | null | object
      • options: {
            analytics?: AnalyticType[];
            appJWT?: string;
            appPublicKey?: string;
            lock?: { lockId: string; releaseLock?: boolean };
            sharedAppJWT?: string;
            sharedAppPublicKey?: string;
        } = {}

      Returns Promise<void | ResponseType>

      Returns success or an error response.

      This method also allows you to set a data object on behalf of another Public Key. It requires canUpdateEcosystemDataObjects permission to be set to true for the Public Key.

      Optionally, a lock can be provided with this request to ensure only one update happens at a time between all updates that share the same lock id

      set, assign, store, save, ecosystem, data, object, state, global, platform

      await ecosystem.setDataObject({ "exampleKey": "exampleValue" }, {
        sharedAppPublicKey: "exampleAppPublicKey",
        sharedAppJWT: "exampleAppPublicKeyJWT",}
      });
      const { exampleKey } = ecosystem.dataObject;

    • Updates the data object for a Topia ecosystem.

      Parameters

      • dataObject: object
      • options: {
            analytics?: AnalyticType[];
            appJWT?: string;
            appPublicKey?: string;
            lock?: { lockId: string; releaseLock?: boolean };
            sharedAppJWT?: string;
            sharedAppPublicKey?: string;
        } = {}

      Returns Promise<void | ResponseType>

      Returns success or an error response.

      This method also allows you to update a data object on behalf of another Public Key. It requires canUpdateEcosystemDataObjects permission to be set to true for the Public Key.

      Optionally, a lock can be provided with this request to ensure only one update happens at a time between all updates that share the same lock id

      update, modify, change, edit, alter, ecosystem, data, object, state, global, platform

      await ecosystem.updateDataObject({
         [`profiles.${profileId}.itemsCollectedByUser`]: { [dateKey]: { count: 1 }, total: 1 },
         [`profileMapper.${profileId}`]: username,
       }, {
         sharedAppPublicKey: "exampleAppPublicKey",
         sharedAppJWT: "exampleAppPublicKeyJWT",
         analytics: [{ analyticName: "itemCollected", profileId, uniqueKey: profileId, urlSlug } ],
         lock: { lockId: `${assetId}-${resetCount}-${new Date(Math.round(new Date().getTime() / 10000) * 10000)}` },
       }
      });
      const { exampleKey } = ecosystem.dataObject;

    Inventory

    • Retrieves all inventory items for a given keyholder (app public key).

      Returns Promise<void>

      Populates the inventoryItems property with an array of InventoryItem objects.

      get, fetch, retrieve, list, inventory, items, keyholder, ecosystem, catalog

      await ecosystem.fetchInventoryItems();
      const items = ecosystem.inventoryItems;

    Moderation

    • Checks a string against the platform's banned words, sentences and emojis.

      Parameters

      • text: string

      Returns Promise<boolean>

      True when the text matches a banned word, sentence or emoji. Empty input is never banned.

      Use this to screen user generated content — a display name, a chat line, a submitted answer — before sending it on, so the app can give immediate feedback instead of having the platform reject it later.

      This applies the same matcher the server uses, so a result here should agree with the platform's own check. It is still a courtesy check, not a replacement: the server screens independently and remains the authority.

      Matching is by whole word, not substring, so classic is not flagged by a banned ass. Leetspeak (d4rn), spelled-out words (d.a.r.n) and padded endings (go awayyy) are all caught.

      The lists are fetched once and cached on first use, so calling this per keystroke costs nothing after the first call. The platform caches them for up to 24 hours, so a change made in HQ may take that long to appear.

      check, test, validate, screen, filter, banned, blocked, profanity, moderation, words, strings, ecosystem, platform

      if (await ecosystem.checkIsBannedString(displayName)) {
        return res.status(400).json({ message: "Please choose a different name." });
      }

    Other

    credentials: undefined | InteractiveCredentials
    dataObject?: null | object
    jwt?: string
    requestOptions: object
    topia: Topia

    • Standardized error handler for all SDK operations.

      Parameters

      • __namedParameters: { error?: unknown; message?: string; params?: object; sdkMethod?: string }

      Returns {
          data: {};
          message: string;
          method: string;
          params: object;
          sdkMethod: undefined | string;
          stack: string;
          stackTrace: Error;
          status: number;
          success: boolean;
          url: string;
      }

      Standardized error object with properties: data, message, method, params, sdkMethod, stack, status, success, url

      This method processes errors from API calls and formats them consistently across the SDK. It extracts relevant error information including:

      • HTTP status codes and response data
      • Error messages from API responses
      • Stack traces for debugging
      • Request details (URL, method, parameters)

      All errors thrown by SDK methods flow through this handler to ensure consistent error format.

      error, exception, handler, debugging, api error, http error

    • Returns the configured Axios instance for making API calls to Topia's Public API.

      Returns AxiosInstance

      The configured Axios client instance with authentication headers.

      All HTTP requests to the Topia API should use this method to ensure proper authentication headers and base URL configuration are applied.

      api, axios, http, request, client, public api

    Settings

    Member Visibility

    On This Page

    Data Objects
    Inventory
    Moderation
    Other