Connect your Front-End via the StackOne React Hub
Integrating multiple services into your web app is now easier with the StackOne Hub.
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.
Updated about 2 months ago