ux4iot
  • Introduction
  • Quickstart
  • Concepts
  • How Ux4iot works
  • REST API Reference
  • Configuration Options
  • Create your ux4iot Instance
  • EventHub / IoTHub
    • Configure your existing IoT Hub
    • Create IoT Hub and linked ux4iot
    • Using a separate Event Hub
  • ux4iot-react
    • Initialization
    • Hooks
    • Grant Request Function
    • Tutorial using create-react-app
  • Implementing your custom security backend
    • Introduction
    • Security Backend
    • Security Backend Example - Azure Function
    • ux4iot-admin-node
  • Resources
    • Pricing
    • Performance
    • Limitations
    • Known Bugs & Nice to know's
    • Changelog
  • Made with ❤️ at Device Insight
Powered by GitBook
On this page
  • Development Mode
  • Production Mode
  • reconnectTimeout & maxReconnectTimeout
  • onSocketConnectionUpdate

Was this helpful?

  1. ux4iot-react

Initialization

Developing web apps with React

PreviousUsing a separate Event HubNextHooks

Last updated 1 year ago

Was this helpful?

We provide React hooks and context providers out of the box. The library can be found on .

First, install the ux4iot-react library:

npm install ux4iot-react
yarn add ux4iot-react

You initialize the ux4iot React library by wrapping your components with a Ux4iotContext

import {Ux4iotContextProvider} from "ux4iot-react";
...
function App() {
  return (
    <div className="App">
      <Ux4iotContextProvider 
          options={options}
      >
          <MyView />
      </Ux4iotContextProvider>
    </div>
  );
}

There are two modes of operations for the library: Development mode and production mode. The initialization differs between the two modes.

ConfigurationOptions

type InitializationOptions = {
	onSocketConnectionUpdate?: ConnectionUpdateFunction;
	reconnectTimeout?: number;
	maxReconnectTimeout?: number;
} & (InitializeDevOptions | InitializeProdOptions);

type InitializeDevOptions = {
	adminConnectionString: string;
};

type InitializeProdOptions = {
	ux4iotURL: string;
	grantRequestFunction: GrantRequestFunctionType;
};

Option
description

onSocketConnectionUpdate

event listener on socket connection updates

reconnectTimeout

initial timeout in milliseconds when to reconnect after a session couldn't be established

maxReconnectTimeout

maximum timeout in milliseconds of the reconnect interval after incrementation

adminConnectionString

The connection string of ux4iot-server

ux4iotUrl

the websocket url of ux4iot-server

grandRequestFunction

custom function to send grant requests to your custom security backend

Development Mode

const UX4IOT_ADMIN_CONNECTION_STRING = "Endpoint=...SharedAccessKey=...";

const devOptions: InitializeDevOptions = {
   adminConnectionString: UX4IOT_ADMIN_CONNECTION_STRING 
};

...
  <Ux4iotContextProvider options={devOptions}>
  ...
  </Ux4iotContextProvider>
...

The value of the adminConnectionString option can be retrieved via the Azure portal:

You can select either the Primary or the Secondary connection string.

Usage of Development Mode

Under no circumstances should you publish your web application in development mode. It allows anyone with access to the web application to perform any requests towards your IoT devices and it also exposes the admin connection string that must be kept secret.

Production Mode

const UX4IOT_WEBSOCKET_URL 'https://ux4iot-xxx.westeurope.azurecontainer.io';

const prodOptions: InitializeProdOptions = {
   ux4iotURL: UX4IOT_WEBSOCKET_URL
   grantRequestFunction: customGrantRequestFunction
};

...
  <Ux4iotContextProvider options={prodOptions}>
  ...
  </Ux4iotContextProvider>
...

The value for the ux4iotURL parameter is available on your ux4iot instance in the Azure portal:

reconnectTimeout & maxReconnectTimeout

When you render a Ux4iotContextProvider, it tries to establish a session by calling the /session endpoint of ux4iot. If this request fails, it will retry again after the milliseconds defined in reconnectTimeout. If the retry fails it will double the timeout and retry again after the doubled timeout or maxReconnectTimeout if maxReconnectTimeout is larger.

Example reconnectTimeout = 5000, maxReconnectTimeout = 50000

Ux4iot fails to connect to ux4iot and fails. Retries afterwards at 5, 10, 20, 40, 50, 50, 50,... seconds

Retries will not stop retrying until the session is established. The defaults are reconnectTimeout = 5000, maxReconnectTimeout = 30000

onSocketConnectionUpdate

In both Development and Production mode you can pass a function to the options of the Ux4iotContextProvider

const devOptions: InitializeDevOptions = {
   adminConnectionString: UX4IOT_ADMIN_CONNECTION_STRING
   onSocketConnectionUpdate: (reason, description) => { /* handle update */ }
};
const prodOptions: InitializeProdOptions = {
   ux4iotURL: UX4IOT_WEBSOCKET_URL
   grantRequestFunction: customGrantRequestFunction
   onSocketConnectionUpdate: (reason, description) => { /* handle update */ }
};

It takes two arguments:

  • reason - can be one of four strings:

    • socket_connect - called when the socket is established with the server

    • socket_connect_error called when the client throws an error when establishing the socket

    • socket_disconnect - called when the socket is disconnected

    • ux4iot_unreachable - called when a sessionId cannot be fetched from the ux4iot instance

  • description - string | undefined : error explanation provided in socket_connect_error, socket_disconnect and ux4iot_unreachable

The full function type you need to provide is

export type ConnectionUpdateReason =
	| 'socket_connect'
	| 'socket_connect_error'
	| 'socket_disconnect'
	| 'ux4iot_unreachable';

export type ConnectionUpdateFunction = (
  reason: ConnectionUpdateReason,
  description?: string
) => void;

You can see a complete example in the .

In production mode the admin connection string is used by the , but as there is no Security Backend in development mode, the frontend accesses the Admin API on its own. For this reason the frontend requires the admin connection string.

For production mode you need to provide a security backend for managing access permissions. You also need a that acts as an adapter between the ux4iot library and this backend.

For detailed information on how to implement the Grant Request Function, see .

Every reason except for ux4iot_unreachable originates from socket.io and is documented here:

GitHub
tutorial using create-react-app
Security Backend
Grant Request Function
the dedicated chapter
https://socket.io/docs/v4/client-api/#event-connect