Embedding Integration Designer

Your customers may want to build integrations for themselves between your product and the other apps and services they use. Embedded designer allows your customers to log in to your app and build integrations using Prismatic's integration designer. You can provision your customers access to private components that you have built, and can provide your customers with "templates" that they can use as a starting point for building their own integrations.

This article covers how to embed the integration designer in your app so that your customers can have a native integration building experience.

For information on how to install the embedded SDK and authenticate customer users, see Installing Embedded SDK. Note: you should include "role": "admin" in JWTs that you sign for customer users who build integrations.

Embedded Designer is an opt-in feature

Embedded designer is enabled on an as-needed basis. Please contact support to discuss enabling embedded designer for your organization.

Enabling embedded designer for a customer

Embedded designer is disabled for all customers by default. To enable embedded designer for a customer, open the customer from the Customers screen and then select the Details tab. Toggle the Allow Embedded Designer option.

Embedded screen configuration

Most embedded screens that show components, integrations, instances, etc., take three properties:

• usePopover is a boolean that determines if the screen should display as a popover. By default, the screen is injected as an iframe into an existing DOM element.
• selector identifies which element in the DOM to inject the iframe into when usePopover is false.
• theme can override custom theming default behavior, and can be set to "LIGHT" or "DARK" mode.

Showing component screens

You can embed the component screens in your app using the prismatic.showComponents and prismatic.showComponent functions respectively. To show all components that are available in your tenant, use the showComponents() function:

Showing all components - ReactJS example

import prismatic from "@prismatic-io/embedded";import { useEffect } from "react";
const id = "my-embedded-builder-div";
function ComponentListView() {  useEffect(() => {    prismatic.showComponents({      selector: `#${id}`,    });  }, []);
  return <div id={id}>Loading...</div>;}
export default ComponentListView;

To show details about a specific component, use the showComponent() function and provide the function with the ID of a component. You will need to query for the ID of the component using prismatic.graphqlRequest function, which you can use to query the Prismatic API:

Showing a specific component

import prismatic from "@prismatic-io/embedded";import { useEffect } from "react";
const id = "my-embedded-builder-div";
const getComponentId = async (key: string) => {  const query = `query getComponentByKey($componentKey: String!) {  components(key: $componentKey) {    nodes {      id    }  }}`;  const result = await prismatic.graphqlRequest({    query,    variables: { componentKey: key },  });  return result.data.components.nodes[0].id;};
function DropboxComponent() {  useEffect(() => {    const showDropbox = async () => {      const componentId = await getComponentId("dropbox");      prismatic.showComponent({        componentId,        selector: `#${id}`,      });    };    showDropbox();  }, []);
  return <div id={id}>Loading...</div>;}
export default DropboxComponent;

Additional documentation on querying the Prismatic API as a customer user from the embedded SDK is available on the Embedded API Requests article.

Showing integrations

The prismatic.showIntegrations function shows the customer user all of the integrations that are owned by their customer. Customers can create their own integrations, or integrations can be assigned to them.

import prismatic from "@prismatic-io/embedded";import { useEffect } from "react";
const id = "integration-list-div";
function IntegrationList() {  useEffect(() => {    prismatic.showIntegrations({ selector: `#${id}` });  }, []);
  return <div id={id}>Loading...</div>;}
export default IntegrationList;

From the showIntegrations screen, customer users will be able to open existing integrations or create new integrations by clicking the +Add integration button (like an organization team member would do).

integrations are scoped to the customer

Integrations are scoped to a customer. If a customer creates a new integration, or if you assign an integration to a customer, only customer users for that customer see that integration.

Assigning an integration to a customer

You can build an integration and assign ownership of it to a customer. To do that, open the integration, select the Details tab on the top of the screen, and select the customer who should own the integration from the Customer dropdown menu.

Opening the integration designer directly

If you know the ID of an integration that you would like to open, you can open an integration directly using prismatic.showDesigner. You will need to query for the ID of the component using prismatic.graphqlRequest function, which you can use to query the Prismatic API:

Open an integration designer directly

import prismatic from "@prismatic-io/embedded";import { useEffect } from "react";
const id = "my-embedded-builder-div";
/** * Get an integration's ID given its name */async function getIntegrationId(integrationName: string) {  const query = `query getMyIntegration($integrationName: String!) {  integrations(name: $integrationName) {    nodes {      id      name    }  }}`;  const variables = { integrationName };  const result = await prismatic.graphqlRequest({ query, variables });  return result.data.integrations.nodes?.[0].id;}
function EmbeddedDesigner() {  useEffect(() => {    const showDesigner = async () => {      const integrationId = await getIntegrationId("Acme Inc");      prismatic.showDesigner({        selector: `#${id}`,        integrationId,        theme: "LIGHT",      });    };    showDesigner();  }, []);  return <div id={id}>Loading...</div>;}
export default EmbeddedDesigner;