Custom Connection UI

You can open the prebuilt connection UI for a specific integration with:

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

This guide shows you how you can implement a custom connection UI

1. Get Auth Options

To get information about what to ask the user in order to create a connection, fetch auth options from the connector:

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

// Fetch auth options from the connector
const authOptions = await membrane.post(
  `/connectors/${integration.connectorId}/generate-options`,
  { connectorParameters: {} } // Pass connector parameters if needed
)

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

Each auth option contains:

key – Unique identifier for this auth option (pass to authOptionKey when connecting)
type – The authentication type (e.g., 'oauth2', 'client-credentials')
title – Human-readable name for this auth option
description – Description explaining this auth method
inputSchema – Data Schema of the parameters required to create a connection. It will be empty if parameters are not required.

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 membrane
  .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 membrane
  .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, useEffect } from 'react'
import { useIntegration, useIntegrationApp } from '@membranehq/react'

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

  const { integration, error } = useIntegration(integrationKey)

  const [authOptions, setAuthOptions] = useState(null)
  const [connectionInput, setConnectionInput] = useState({})
  const [connecting, setConnecting] = useState(false)
  const [connection, setConnection] = useState(null)

  // Fetch auth options from connector
  useEffect(() => {
    if (!integration?.connectorId) return

    membrane.post(`/connectors/${integration.connectorId}/generate-options`, {
      connectorParameters: {}
    }).then(setAuthOptions)
  }, [integration?.connectorId, membrane])

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

  // Wait until the spec and auth options load
  if (!integration || !authOptions) {
    return <p>Loading...</p>
  }

  // Display only the first auth option
  const authOption = authOptions[0]

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

  // Get connection parameters schema from inputSchema
  const schema = authOption.inputSchema

  // 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 membrane
        .integration(integrationKey)
        .connect({
          input: connectionInput,
          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={connectionInput[field] || ''}
                onChange={(e) =>
                  setConnectionInput({
                    ...connectionInput,
                    [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 membrane
  .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.