Embed UI components

​

Project setup

​

Prerequisites

The Ampersand UI library requires React v18+.

​

Install the Ampersand React library

In your repo, use npm to install the package:

npm install @amp-labs/react

If you are using yarn, you’ll have to explicitly install the peer dependencies.

yarn add @amp-labs/react @chakra-ui/react @emotion/react @emotion/styled framer-motion

​

Credentials

This library requires your components to be wrapped in the <AmpersandProvider/> context. <AmpersandProvider /> takes these props:

• apiKey: an API key to access Ampersand services. If you don’t have one yet, create one on the API keys page of Ampersand Dashboard.
• project: your Ampersand project name or ID. You can find it on your project’s General Settings page.

​

Example

Here’s an example:

import { AmpersandProvider } from '@amp-labs/react';

const options = {
  project: 'PROJECT', // Your Ampersand project name or ID.
  apiKey: 'API_KEY',// Your Ampersand API key.
};

function App() {
  return (
    // Wrap all your components inside AmpersandProvider.
    // You can either do this at the App level,
    // or further down in the component tree.
    <AmpersandProvider options={options}>
        // You can use any of the Ampersand components here.
        ...
    </AmpersandProvider>
  )
}

​

Components

​

Install integration

The InstallIntegration component asks your customer for their SaaS credentials, and then guides them through the installation flow for an integration. If they’ve already installed this integration, then the component will display the current configuration of the integration and allow them to update it.

Please note that each group is able to install the integration once, so if someone else with the same groupRef has already installed the integration, then the user will not be able to install the same integration again.

The parameters of the component are:

• integration (string): the name of an integration that you’ve defined in amp.yaml. See Defining integrations.
• consumerRef (string): the ID that your app uses to identify this end user.
• consumerName (string, optional): the display name for this end user.
• groupRef (string): the ID that your app uses to identify a company, team, or workspace. See group.
• groupName (string, optional): the display name for this group.
• onInstallSuccess (function, optional): a callback function that gets invoked after a consumer successfully installs the integration.
• onUpdateSuccess (function, optional): a callback function that gets invoked after a consumer successfully updates an existing integration with the new configuration.
• onUninstallSuccess (function, optional): a callback function that gets invoked after a consumer successfully uninstalls the integration.

Both onInstallSuccess and onUpdateSuccess should be functions with the following signature: (installationId: string, config: Config) => void

 <InstallIntegration 
  integration = {myIntegrationName}
  consumerRef = {userId}
  consumerName = {userFullName}
  groupRef = {teamId}
  groupName = {teamName}
  onInstallSuccess = {(installationId, configObject) =>
    console.log(`Successfully installed ${installationId}`
      + `with configuration ${JSON.stringify(configObject, null, 2)}`)
  }
  onUpdateSuccess = {(installationId, configObject) =>
    console.log(`Successfully updated ${installationId}`
      + ` with configuration ${JSON.stringify(configObject, null, 2)}`)
  }
  onUninstallSuccess = {(installationId) =>
    console.log(`Successfully uninstalled ${installationId}`)
  }
/>

​

Connect provider

The ConnectProvider component allows your customer to put in their SaaS credential, but does not lead them through the installation flow. After their SaaS credential is persisted by Ampersand, you can then make an API request to the CreateInstallation endpoint.

The parameters of the component are:

• provider (string): the name SaaS provider, such as “salesforce”.
• consumerRef (string): the ID that your app uses to identify this end user.
• consumerName (string, optional): the display name for this end user.
• groupRef (string): the ID that your app uses to identify a company, team, or workspace. See group.
• groupName (string, optional): the display name for this group.
• redirectUrl (string, optional): if provided, the page will be redirected to this URL once a consumer successfully connects. This can either be an absolute or relative URL.
• onSuccess (function, optional): a callback function that gets invoked after a consumer successfully connects, it should have the signature (connectionID: string) => void.

 <ConnectProvider 
  provider = "salesforce"
  consumerRef = {userId}
  consumerName = {userFullName}
  groupRef = {teamId}
  groupName = {teamName}
  redirectUrl = "/connection-success"
  onSuccess = {connectionId =>
    console.log(`Successfully created connection ${connectionId}`)
  }
/>

​

Hooks

​

Check if integration is installed

We provide a hook useIsIntegrationInstalled to check if an integration has been installed yet for this group. It takes in 2 parameters:

• integration (string): the name of an integration that you’ve defined in amp.yaml. See Defining integrations.
• groupRef (string): the ID that your app uses to identify a company, team, or workspace. See group.

It returns an object with fields isLoadedchecking if API call is resolved and isIntegrationInstalled indicating whether the integration has already been installed by somebody in the group.

const {
  isLoaded,
  isIntegrationInstalled
} = useIsIntegrationInstalled("read-salesforce", groupRef);