Embedding Prismatic in Your App

Embedding lets your customers find, configure, and manage integrations from inside your app, signed in with their existing credentials. You can embed Prismatic in two ways:

• Headless: The headless SDK (Solis) supplies integration data and actions, and your app renders every card, form, and button with its own components.
• Hosted: The embedded SDK displays Prismatic's marketplace and config wizard in an iframe, which you theme to match your app.

Headless: Build with your own UI

Use the headless SDK (Solis) to render the marketplace and configuration experiences with your app's own components.

Best for: Native-feeling, fully custom configuration experiences that match your design system.

Hosted: Embed Prismatic's UI

Use the embedded SDK to display Prismatic's marketplace and config wizard in an iframe, themed to match your app.

Best for: Getting integrations in front of customers quickly with minimal frontend code.

Choosing headless or hosted

Both options authenticate users the same way and deploy the same integrations. They differ in who builds the UI and how much control you have over it.

Topic	Headless (Solis)	Hosted (embedded SDK)
UI	Your app's own components, so integrations look and behave like the rest of your app	Prismatic's screens in an iframe, styled with theming
Configuration	Any experience your frontend can build: field mappers with live previews, multi-step flows, inline validation, and more	Config wizards you design in Prismatic's config wizard designer
Configuration inputs	Any data your app or the integration's server functions provide	Prismatic's input types and data sources
Per-integration effort	You typically build each integration's configuration experience in your frontend	None in your frontend: new integrations and config changes appear without a code change in your app
Setup effort	Higher: you build and maintain the UI	Low: a few lines of code embed the marketplace
Additional screens	Build your own with instance and connection data	Embed Prismatic's dashboard, connections, and logs screens

Choose headless when the configuration experience is part of your product and should feel native to your app, or when an integration's configuration needs data and interactions that a config wizard can't express.

Choose hosted when you want customers deploying integrations quickly, and a themed version of Prismatic's marketplace and config wizard fits your app. Hosted is also the faster way to launch many integrations, because each one's configuration experience lives in Prismatic rather than in your frontend.

You don't have to choose one for everything. Solis includes a HostedConfiguration component that opens Prismatic's config wizard, so a headless marketplace can configure some integrations with your own forms and others with hosted config wizards.

The embedded workflow builder is hosted

The embedded workflow builder, which lets your customers build their own workflows, is available through the embedded SDK.

How embedding works

Whichever option you choose, embedding involves three steps:

1. Authenticate embedded users through your existing authentication system, so they don't need separate Prismatic credentials. Your backend signs a JWT for the signed-in user, and both SDKs accept the same token.
2. Install the SDK: the headless SDK or the embedded SDK.
3. Build your experience: your own marketplace and configuration UI, or the embedded marketplace themed to match your app.

Testing the embedded experience

The fastest way to test the hosted experience is to use the embedded playground, which is a React application that you can run from within Prismatic. Open your organization settings and then select the Embedded tab. Under Embedded Preview select Launch.

From there, you can test the embedded marketplace and (if enabled) the embedded workflow builder.

To see headless examples, run the example embedded app, which includes a custom marketplace, a one-click connect list, and configuration presentation modes built with Solis.