Custom Connection UI

Pre-built connection UI looks like this:

await integrationApp.integration('hubspot').openNewConnection()

You can implement a custom version of this UI using this guide.

1. Get Integration

To get information about what to ask the user in order to create a connection, you need to get integration data:

const integration = await integrationApp.integration('hubspot').get()

Integration will have one or more authOptions that can be used to create a connection.

For simplicity, we'll assume that integration has only one authOption. If it has more, you can use the same logic for each of them.
If integration has zero authOptions, it means authentication is not configured and you need to edit or change the connector used for the integration.

Let's look at the ui property of the auth option. It contains the following fields:

schema – Data Schema of the parameters required to create a connection. It will be empty if parameters are not required.
description – a human-readable description explaining the parameters.
helpUri – link to documentation explaining how to get the parameters.

2. Connection Parameters UI

You can use your preferred way of converting JSON Schema into a form.
For example, you can extract a list of fields from the schema and simply display an input for each:

function ConnectionForm() {
  const [parameters, setParameters] = useState({})

  const schema = {
    type: 'object',
    properties: {
      email: { type: 'string' },
      apiKey: { type: 'string' },
    },
  }

  const fields = Object.keys(schema.properties)

  return (
    <>
      {fields.map((field) => (
        <div key={field}>
          <label>{field}</label>
          <input
            type='text'
            className='p-1 border rounded'
            value={parameters[field] || ''}
            onChange={(e) =>
              setParameters({ ...parameters, [field]: e.target.value })
            }
          />
        </div>
      ))}
    </>
  )
}

If a connection doesn't have parameters, you can skip this step.

3. Creating a Connection

When you have collected connection parameters, you can create a connection:

const integration = await integrationApp
  .integration('hubspot')
  .connect({ parameters })

This code may open a new window if it is required by the authentication process.
Make sure this code runs inside a user action handler (e.g. onClick), otherwise the browser may block the new window.

Redirect instead of a new window

When you need to avoid opening a new window, you can use redirect instead.
Pass sameWindow: true and redirectUri options. The URI will be used for redirection after the connection is created or fails.

Added query parameters:

For successful creation, the connectionId will be added
For failures, error will contain the error message and errorData will contain the JSON stringified error payload

const integration = await integrationApp
  .integration('hubspot')
  .connect({
    parameters,
    sameWindow: true,
    redirectUri: window.location.href
  })

4. Putting it all together

Here is a simple UI component that displays the connection parameters and creates a new connection:

import { useState } from 'react'
import { userIntegration, useIntegrationApp } from '@integration-app/react'

function Component({ parameters }) {
  // For this to work, don't forget to wrap this component into <IntegrationAppProvider/>
  const integrationApp = useIntegrationApp()

  const { integration, error } = useIntegration(parameters.INTEGRATION_KEY)

  const [connectionParameters, setConnectionParameters] = useState({})
  const [connecting, setConnecting] = useState(false)
  const [connection, setConnection] = useState(null)

  // If something bad happened - show the error
  if (error) {
    return <p>Error: {error.message}</p>
  }

  // Wait until the spec loads
  if (!integration) {
    return <p>Loading...</p>
  }

  // Display only the first auth option
  const authOption = integration!.authOptions?.[0]

  if (!authOption) {
    return <p>No auth options found for this integration</p>
  }

  // Get connection parameters schema
  const schema = authOption.ui?.schema

  // Simplified way to get the list of connection parameters.
  const fields = schema ? Object.keys(schema.properties ?? {}) : []

  async function connect() {
    setConnecting(true)
    try {
      const connection = await integrationApp
        .integration(parameters.INTEGRATION_KEY)
        .connect({
          parameters: connectionParameters,
          authOptionKey: authOption.key,
        })
      setConnection(connection)
    } finally {
      setConnecting(false)
    }
  }

  return (
    <div>
      {fields.length > 0 && (
        <div>
          <strong>Connection Parameters:</strong>
          {fields.map((field) => (
            <div key={field}>
              <label>{field}</label>
              <input
                type='text'
                value={connectionParameters[field] || ''}
                onChange={(e) =>
                  setConnectionParameters({
                    ...connectionParameters,
                    [field]: e.target.value,
                  })
                }
              />
            </div>
          ))}
        </div>
      )}

      {connecting ? (
        <span>Connecting...</span>
      ) : (
        <button onClick={connect}>Connect</button>
      )}

      {connection && (
        <div>
          <strong>Connected!</strong>
          <br />
          Connection Id: {connection.id}
        </div>
      )}
    </div>
}

5. Re-connecting

When a connection becomes disconnected, you can re-connect it using the same code as when creating a new connection:

const integration = await integrationApp
  .integration('hubspot')
  .connect({ parameters })

Multiple Connections for the same Integration

If you want to let your customers create multiple connections for the same integration,
set the allowMultipleConnections option of the connect method call to true.