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);
  }
});

Customising the hub style

You can add hub styling to the start options via the styles property:

// Example of styles object
const styles = {
  inline: { // Removes the dropshadow and z-index from the iframe
    containerId: 'my-container-id', // Your page container where the iframe will be appended to
    height: '500px', // Height of the Hub
    width: '300px', // Width of the Hub
  },
  options: {
    back: false, // Removes the back arrow from the Hub
    close: false, // Removes the close button from the Hub
    bgColor: 'white', // The background color of the Hub (This only changes the background, 
    									// the font color will remain the same, so be aware of that)
  },
};

Default look of the Hub

Customised Style Hub (with Inline and custom width)

This can be very helpful if you want the hub to be inline on your page, disable back/close buttons, etc. All of these properties are optional so you can customize the best user experience for your users.