Integrating multiple services into your web app is now easier with the StackOne Hub.

stackone integration hub (credentials form)

This guide will walk you through the process of adding the StackOne Hub to if you're using React (using the @stackone/react-hub package) or by using directly the underlying StackOne "Connect" library.

Using React

Step 1: Install the Package

First, add the @stackone/react-hub package to your project using either npm or yarn

Using npm

npm install --save @stackone/react-hub

Using Yarn

yarn add @stackone/react-hub

Step 2: Implement a function to retrieve the connect session token

The React Hub needs to retrieve a connect session token to be able to securely communicate with the StackOne Portal. This is achieved by making a POST request to StackOne API /connect_sessions endpoint.

Since this involves sending the API Key and other sensitive data, the recommended approach is to make this request through your application backend avoiding the need for exposing credentials in the frontend code.

As an example, assuming that the application backend already has that endpoint a function to retrieve the connection session token could be as simple as:

export const retrieveConnectSessionToken = async ({ username, provider }) => {
  const payload = {
    originUsername: username, // eg: [email protected] (the username trying to connect)
    provider, // optional - (specifying a provider will make the stackone hub load directly the  provider's connection screen and bypass the integrations listing screen)
  };

  const headers = {
    'Content-Type': 'application/json',
  };

  const connectSessionResponse = await fetch(
    'https://your-application.com/stackone_connect_session', // your back-end implementation for forwarding the request with the relevant API key to StackOne's /connect_sessions endpoint
    {
      method: 'POST',
      headers,
      body: JSON.stringify(payload),
    },
  );

  const response = await connectSessionResponse.json();

  return { token: response.token };
};

This example is only calling the endpoint that will communicate with the StackOne API and getting the token from the response so that it can be used in the react hub hook in the next step.

For instructions on how to build the backend endpoint that communicates with the StackOne API please refer to the guide to connect your backend with StackOne API.

Customising the hub behaviour

Per the Connect Sessions documentation and the associated back-end implementation example Connect your Backend with StackOne, you can specify a provider property so the integration hub will directly filter or load the given provider or category instead of displaying a list of all integrations enabled.

Step 3: Create a Link Account Button

Create a button component that users can click to link their accounts. The button will utilize the useStackOneHub hook to initiate the Connect flow.

import { useStackOneHub } from '@stackone/react-hub';

const LinkAccountButton = () => {  
  const { startConnect } = useStackOneHub();

  const startFlow = useCallback(async () => {  
    const sessionToken = await retrieveConnectSessionToken({ username: '[email protected]' });  
    startConnect({ sessionToken });  
  }, [startConnect]);

  return (  
    <button onClick={startFlow}>Connect Account</button>  
  );  
};

Your application is now ready to start connecting accounts!

Using the Connect Library

Step 1 - load the script on the page

You should insert the a script tag wherever you intend to display the StackOne hub.

This can be done one of two ways

Adding the following script in the <body> of your page:

<script src="https://app.stackone.com/stackone/connect.js"></script>

Alternatively you can also add the script tag via javascript, for example via the following code:

const script = document.createElement('script');
script.src = 'https://app.stackone.com/stackone/connect.js';
document.body.appendChild(script);

Step 2 - Implement the function to generate a session token

To use the Connect library, you will also need to generate a session token. Refer to the documented step here.

Step 3 - Use the connect library


const connectSessionToken = await retrieveConnectSessionToken();

// The code below will open the StackOne Hub
// Depending on the session token generated - the hub can be opened on the listing page or directly on the set-up screen of a specified provider.
// The onSuccess callback will be called if the user interacting with the StackOne Hub sucessfully links an account
Connect.start({
  sessionToken: connectSessionToken,
  onSuccess: (e) => {
    console.log('> stackone - new account linking', e);
  }
});