@phygrid/signals-react v4.4.6

@phygrid/signals-react

A React library for integrating Phygrid Signals into your react applications.

Installation

Use either yarn or npm to install the package:

# Using yarn
yarn install @phygrid/signals-react

# Using npm
npm install @phygrid/signals-react

Usage

Basic Integration

The simplest way to integrate Signals into your React application is using the useGridSignals hook:

import React, { useEffect } from 'react';
import './App.css';
import { useGridSignals } from "@phygrid/signals-react";

function App() {
  const { isReady, signalsService } = useGridSignals();
  
  useEffect(() => {
    if (isReady) {
      // Example of sending an event
      signalsService.sendEvent(...);
    }
  }, [isReady, signalsService]);

  return (
    <div className="App">
      <p>Hello Signals</p>
    </div>
  );
}

export default App;

Custom Parameters

For more control, you can initialize the signals service with custom parameters using the useGridSignalsWithExternalParams hook:

import React, { useEffect } from 'react';
import './App.css';
import { useGridSignalsWithExternalParams } from "@phygrid/signals-react";

function App() {
  const initParams = {
    "deviceId": "device-12345",
    "installationId": "install-67890",
    "spaceId": "space-abcdef",
    "tenantId": "tenant-xyz",
    "appVersion": "1.0.0",
    "appId": "com.example.app",
    "environment": "production",
    "dataResidency": "EU",
    "country": "SE",
    "installationVersion": "2.3.4",
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR...",
    "clientUserAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)",
    "ip": "192.168.1.100"
  };
  
  const { isReady, signalsService } = useGridSignalsWithExternalParams(initParams);
  
  useEffect(() => {
    if (isReady) {
      // Example of sending an event
      signalsService.sendEvent(...);
    }
  }, [isReady, signalsService]);

  return (
    <div className="App">
      <p>Hello Signals</p>
    </div>
  );
}

export default App;

API Reference

Hooks

useGridSignals()

Initializes the signals service with default parameters.

Returns:

• isReady (boolean): Indicates whether the signals service is initialized and ready to use
• signalsService (object): The signals service instance for sending events

useGridSignalsWithExternalParams(initParams)

Initializes the signals service with custom parameters.

Parameters:

• initParams (object): Configuration object with the following properties:
  • deviceId (string): Unique identifier for the device
  • installationId (string): Unique identifier for the installation
  • spaceId (string): Identifier for the space
  • tenantId (string): Identifier for the tenant
  • appVersion (string): Version of the application
  • appId (string): Identifier for the application
  • environment (string): Environment (e.g., "production", "development")
  • dataResidency (string): Location for data residency
  • country (string): Country code
  • installationVersion (string): Version of the installation
  • accessToken (string): JWT or other access token
  • clientUserAgent (string): User agent string
  • ip (string): IP address

Returns:

• isReady (boolean): Indicates whether the signals service is initialized and ready to use
• signalsService (object): The signals service instance for sending events

Available Methods

Complete details regarding the available methods in signalsService can be found in here

Troubleshooting

If you find any errors when importing the package, make sure that 1. config-overrides.js is setup properly, an example is given below:

const webpack = require('webpack');
const path = require('path');

module.exports = function override(config, env) {
  config.module.rules.push({
    test: /\.(ts|tsx)$/,
    loader: 'ts-loader',
    options: {
      transpileOnly: true,
      compilerOptions: {
        module: 'esnext',
        moduleResolution: 'node',
      },
    },
    exclude: /node_modules/,
  });

  delete config.externals;

  config.plugins.push(
    new webpack.IgnorePlugin({ resourceRegExp: /^https-proxy-agent$/ }),
    new webpack.IgnorePlugin({ resourceRegExp: /^http-proxy-agent$/ })
  );

  config.resolve.fallback = {
    assert: require.resolve('assert/'),
    buffer: require.resolve('buffer/'),
    stream: require.resolve('stream-browserify'),
    util: require.resolve('util/'),
    net: false,
    tls: false,
    fs: false,
    child_process: false,
    http: false,
    https: false,
    os: false,
    url: false,
  };

  config.module.rules.push({
    test: /abort-controller/,
    resolve: { fullySpecified: false },
  });

  config.resolve.alias = {
    ...config.resolve.alias,
    'react': path.resolve('./node_modules/react'),
    'react-dom': path.resolve('./node_modules/react-dom')
  };

  return config;
};

2. Make sure that your webpack.config.js is setup properly, for example:

const webpack = require('webpack');
const path = require('path');

module.exports = function override(config, env) {
  // Add React resolution alias
  config.resolve.alias = {
    ...config.resolve.alias,
    'react': path.resolve('./node_modules/react'),
    'react-dom': path.resolve('./node_modules/react-dom')
  };

  // Add externals configuration
  config.externals = {
    ...config.externals,
    react: 'React',
    'react-dom': 'ReactDOM'
  };

  // Existing fallbacks for node.js core modules
  config.resolve.fallback = {
    http: require.resolve('stream-http'),
    https: require.resolve('https-browserify'),
    stream: require.resolve('stream-browserify'),
    util: require.resolve('util/'),
    os: require.resolve('os-browserify/browser'),
    assert: require.resolve('assert/'),
    net: false,
    tls: false,
  };
  
  config.plugins.push(
    new webpack.ProvidePlugin({
      process: 'process/browser',
      Buffer: ['buffer', 'Buffer'],
    })
  );
  
  return config;
};

3. If you are using typescript, make sure you have tsconfig.json setup properly, for example:

{
  "compilerOptions": {
    "target": "es5",
    "lib": [
      "dom",
      "dom.iterable",
      "esnext"
    ],
    "allowJs": true,
    "skipLibCheck": true,
    "esModuleInterop": true,
    "allowSyntheticDefaultImports": true,
    "strict": true,
    "forceConsistentCasingInFileNames": true,
    "module": "esnext",
    "moduleResolution": "node",
    "resolveJsonModule": true,
    "isolatedModules": true,
    "noEmit": true,
    "jsx": "react",
    "baseUrl": "src"
  },
  "include": [
    "src"
  ]
}

4. For react version related issues, make sure you add following in your package.json file:

{
  "resolutions": {
      "react": "^18.0.0",
      "react-dom": "^18.0.0"
    },
}