Configuration

CDN

<script src="https://unpkg.com/@ubox-lib/ubox-data-xpace/ubox-data-xpace.min.js"></script>

Quick start

const client = connectUboxClient({
  debug: true, // Show debug messages on the console
  session: false, // Utilize session instances
  appName: "app_name",
  expName: "xperience_name",
});

const cstmsg = client.cstmsg; // Receive messages if you're using a physical player.

The connectUboxClient function returns a {UboxClientHandle} Object. Once it’s used, your Ubox Player is connected to the Xpace and will start receiving messages which will be dispatched as Custom Events in the application window context. It’s also possible to send messages through the sendMsg method.

ClientOptions

An object to configure the client's behavior. All properties except for appName and expName are optional.

| Property | Type | Default | Description | | :------------- | :---------------------- | :--------- | :------------------------------------------------------------------------------------------------------------------ | | debug | boolean | false | If true, logs incoming and outgoing messages to the console. | | onlineStatus | boolean | true | Dispatch an “Online status” message when connected. | | session | boolean \| string | true | If true, a new session ID is generated. If a string, it is used as the session ID. If false, no session ID is used. | | event | boolean | true | If true, dispatches a CustomEvent for each received message. | | message | boolean | true | If true, the sendMsg method is included in the returned object. | | rule | Array<string> | [] | A list of keywords. Messages are accepted regardless of session if their command starts with one of these keywords. | | callback | function | null | A callback function to be executed for each received message. | | physical | boolean | false | If true, the client attempts to connect to a physical device (e.g., Arduino) instead of a Ubox server. | | appName | string | — | The name of the application. Required for variable sharing. | | expName | string | — | The name of the experience. Required for variable sharing. | | userID | string | auto-gen | A unique ID for the user. Defaults to a generated ID. | | variables | Array<VarDeclaration> | [] | A list of variables to declare on connect. See VarDeclaration Object. |

VarDeclaration Object

This library can manage variables between applications within the same Xpace. One of the methods to create such variables is through the Client configuration object with the variables property. It receives a list of objects defined in the table bellow:

| Property | Type | Default | Description | | ------------ | -------------------- | ------------ | ----------------------------------------------------------------------- | | name | {string} | | Variable name. Must be unique and non-empty. | | value | {any} | | The initial value of the variable. | | read | {boolean} | true | Can this variable be read by other applications? | | readAccess | {Array<string>} | [”all”] | A list of appNames, aside from the origin, that can read this variable. | | edit | {boolean} | false | Can it be edited by other applications? | | editAccess | {Array<string>} | [”all”] | A list of appNames, aside from the origin, that can edit this variable. | | onchange | {function(Object)} | ( ) => { } | Callback function for when the variable value is changed. |

Example

const client = connectUboxClient({
  // ...client's other configuration properties
  variables: [
    {
      name: "time",
      value: 90,
      edit: true,
      onchange: (varObj) => {
        console.log("New Time is: " + varObj.value);
      },
    },
  ],
});

The function passed to onchange receives an object representing the updated variable:

{
  name: "time",        // Variable name
  value: 60,           // The new value
  origin: "abc123",    // The userID of the app where the variable was first created
  originName: "app_b", // The appName of the app where the variable was first created
}

NOTE

Variables instantiated at the client object declaration will be automatically shared to all online applications within the Xpace.

UboxClientHandle

Represents the connected UboxClient with its associated functionalities.

Properties

| Property | Type | Description | | :---------- | :--------------- | :---------------------------------------------------------------------- | | client | Object \| null | The instance of the UboxClient, or null if the connection is physical. | | session | string | The session ID, if one was used. | | userID | string | The user ID. | | appName | string | The application name. | | expName | string | The Phygital Experience name. | | variables | Object | Object containing all variables. The variable key is equal to its name. |

Methods

| Method | Parameters | Description | | ------------------------------------------------- | -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | | sendMsg | (Object<msg_object>) | A function to send a custom event. This function's behavior changes based on the physical option. | | cstmsg | (string<JSON_string>) | A helper function to parse and route messages from a physical device. Only available in physical mode. | | getVariable | (string<variable_name>) | Get the value of a variable. | | setVariable | (string<variable_name> , any<new_value>) | Set the value of a variable (only if it's owned by this app). | | requestVariable | (string<variable_name>) | Request the access to a variable from other applications. Once it's granted, the variable's value will auto-update. | | requestVariableChange | (string<variable_name>, any<new_value>) | Request to change the value of a variable owned by another application. | | declareVariable | (Object<varDeclaration>) | Declare a new variable. |

sendMsg

This method sends messages to other applications within the same Xpace. It receives a object and then then sends this object as stringifed JSON.

E.G.

const client = connectUboxClient({
  // ...configuration properties
});

client.sendMsg({
  command: "turn_light",
  value: "on",
  aditionalValue: 20,
});

The object itself can have any value, although it’ll not work if the object is too big, for example the DATA URL of a big image.

The client adds automatically in the message object the following properties from the client: session, userID, appName and expName.

Receiving / Reading messages

The messages sent to a Xpace is received by all aplication within the same Xpace and dispatched locally as a Custom Event. To read the message your application just need to listen to the event.

E.G.

const client = connectUboxClient({
  // ...configuration properties
});

// The event name will be the same string defined at `command` on the `sendMsg` method.
window.addEventListener("turn_light", (e) => {
  msgObject = e.detail;
  console.log("The light was turnned " + msgObject.value);
  if (msgObject.value === "on")
    console.log("At the potency of " + msgObject.aditionalValue);
});

cstmsg

This function is used to turn messages into events in applications used on physical players. You assign it to the global context so the physical player can use it.

E.G.

const cstmsg = client.cstmsg;

getVariable

This method returns the value of the variable requested on the parameter. This works for variables both created by the application or variables requested from others. However it will not find variables that weren’t requested yet.

The parameter for this method is a string with name of the variable you want the value.

E.G.

const client = connectUboxClient({
  // ...client's other configuration properties
  variables: [
    {
      name: "time",
      value: 90,
      edit: true,
      onchange: (varObj) => {
        console.log("New Time is: " + varObj.value);
      },
    },
  ],
});

const timeValue = client.getVariable("time");
console.log("The time is: " + timeValue + "seconds");

setVariable

This method changes the value of a variable owned by the application (created by it). If you need to change the value of a variable created by another application within the same Xpace, refer to the requestVariableChange method.

The first parameter for this method is a string with name of the variable you want the change, while the second parameter can be any type of value.

E.G.

const client = connectUboxClient({
  // ...client's other configuration properties
  variables: [
    {
      name: "time",
      value: 90,
      edit: true,
      onchange: (varObj) => {
        console.log("New Time is: " + varObj.value);
      },
    },
  ],
});

let timeValue = client.getVariable("time"); // Get first value
console.log("The time is: " + timeValue + "seconds"); // "The time is: 90 seconds"

client.setVariable("time", 60); // Set new value

timeValue = client.getVariable("time"); // Get new Value
console.log("The time is: " + timeValue + "seconds"); // "The time is: 60 seconds"

requestVariable

This method asks for all the applications in the same Xpace for a determined variable. The owner of such variable will reply with all data required to store it locally, then every time this same variable has it’s value altered, it’ll automatically change in the local value. However the variable in question must have the read property set to true.

The parameter for this method is a string with name of the variable you want.

E.G.

const client = connectUboxClient({
  // ...client's configuration properties
});

client.requestVariable("time");

Once the variable is requested, if you want to add a onchange function to it, you’ll need to listen to the event of the variable’s creation.

E.G.

// This event is dispatched every time a variable is locally instantiated.
window.addEventListener("XP_var_created", (e) => {
  const key = e.detail.name;

  // Since this event is dispatched for every variable, we need to make sure it's the one
  // we want to add the onchange function.
  // It's recommended to use a switch case for more than one variables.
  if (key !== "time") return;

  // With the variable name you can access it directly
  client.variables[key].onchange = (varObj) => {
    console.log("New Time is: " + varObj.value);
  };
});

requestVariableChange

This method changes the value of a variable owned by another application (created by it). However the variable in question must have the edit property set to true.

The first parameter for this method is a string with name of the variable you want the change, while the second parameter can be any type of value.

E.G.

const client = connectUboxClient({
  // ...client's configuration properties
});

// Request variable
client.requestVariable("time");

// Set it's onchange method
window.addEventListener("XP_var_created", (e) => {
  const key = e.detail.name;
  if (key !== "time") return;

  client.variables[key].onchange = (varObj) => {
    console.log("New Time is: " + varObj.value);
  };
});

client.requestVariableChange("time", 20);

declareVariable

This method can be used to declare a variable outside of the client’s object declaration. This variable is not automatically shared yet.

E.G.

const client = connectUboxClient({
  // ...client's other configuration properties
});

client.declareVariable({
  name: "time",
  value: 90,
  edit: true,
  onchange: (varObj) => {
    console.log("New Time is: " + varObj.value);
  },
});