@terminal-api/link-react

Terminal Link React SDK

Welcome to the Terminal Link React SDK! This package provides a React hook, useTerminalLink, that allows you to seamlessly integrate and interact with Terminal's link component in your React application.

Getting Started

Installation

To install the Terminal Link React SDK, run the following command in your project directory:

npm install @terminal-api/link-react

Prerequisites

This package is built using React hooks, so you need to have React version 16.8.0 or later in your project.

How to Use

Here's a simple example of how to use the useTerminalLink hook in your React component:

import React from 'react';
import { useTerminalLink } from '@terminal-api/link-react';

const MyComponent = () => {
  const api = useYourBackendApi();

  // if you are defining the function inside the component
  // make sure to wrap it in useCallback
  const exchangeToken = useCallback(
    async ({ publicToken }: { publicToken: string }) => {
      // Send the public token to your backend to exchange for a connection token
      // and store it in your database.
      return await api.post('/api/terminal', { publicToken });
    },
    [api]
  );

  const terminal = useTerminalLink({
    // production or sandbox publishable key from the Terminal dashboard
    publishableKey: process.env.REACT_APP_TERMINAL_PUBLISHABLE_KEY,
    onSuccess: exchangeToken,
    params: {
      // optional parameters to pass to the link
      // see https://docs.withterminal.com/link-component for more details
      externalId: '1234'
    }
  });

  return (
    <>
      <button onClick={() => terminal.open()} disabled={terminal.isOpen}>
        Setup Telematics Integration
      </button>
      <button onClick={() => terminal.close()} disabled={!terminal.isOpen}>
        Close Terminal Link
      </button>
      <button
        onClick={() => terminal.open({ params: { provider: 'geotab' } })}
        disabled={terminal.isOpen}
      >
        Setup Geotab Integration
      </button>
      <button
        onClick={() => terminal.open({ params: { externalId: '1234' } })}
        disabled={terminal.isOpen}
      >
        Setup Integration with Custom Parameters
      </button>
    </>
  );
};

export default MyComponent;

In this example, useTerminalLink is used to create a terminal object. This object is then used to open the Terminal link when the button is clicked.

Documentation

Can reference the Terminal Link documentation section for more details on how to use the SDK.

Callbacks

To prevent infinite re-renders, wrap onSuccess and other callbacks passed to useTerminalLink with useCallback like we do above. Alternatively, if your function doesn't need any additional parameters you can define the function outside of the component to avoid the need for useCallback. This is mandatory to ensure the callback function's identity remains stable.