Skip to main content

Installing the Embedded SDK

Installing Prismatic's SDK​

To embed Prismatic in your app, you must include some Prismatic JavaScript code with your client application. You have two choices for how to incorporate that code: you can add the @prismatic-io/embedded NPM package to your web app Node.js project, or you can build the package from source and include it in your app through a <script> tag. We strongly recommend installing the SDK via NPM so that you have intellisense and TypeScript support.

You can view the source code for the Embedded NPM package on GitHub.

Installing embedded through NPM​

Embedded NPM version

If your web application is written in Node.js, you can include Prismatic's JavaScript code as a Node.js import. Install the Prismatic Embedded Node.js package from NPM with npm or yarn:

npm install @prismatic-io/embedded

# or

yarn add @prismatic-io/embedded

Then, for any page that needs to invoke a prismatic.* function, include the @prismatic-io/embedded package at the top of the file:

import prismatic from "@prismatic-io/embedded";

Installing embedded with a script tag​

We recommend installing embedded through NPM

Installing Embedded through the script tag is great for prototyping and testing, but for production use we recommend installing Embedded through NPM. The TypeScript NPM package gives you advanced features, like code completion and type safety.

To install the Prismatic SDK through a script tag, you will first need to build the @prismatic-io/embedded package. You will need Node.js installed on your machine.

Clone and build the Prismatic SDK
# Clone the @prismatic-io/embedded repository from GitHub
git clone https://github.com/prismatic-io/embedded.git prismatic-embedded

# Install node dependencies
cd prismatic-embedded
npm install

# Build the @prismatic-io/embedded package
npm run build

This will create a directory in prismatic-embedded/ called dist/, which contains index.js (along with some TypeScript files). You can copy that file into your app's static scripts directory and then include it in your HTML with a script tag:

<script src="/static/js/path/to/prismatic/index.js"></script>

Once the script has loaded, prismatic.* functions (described below) are available for you to use.

You can also pull down the built index.js file from a JavaScript CDN like UNPKG: unpkg.com/browse/@prismatic-io/embedded/.

Initialize the Prismatic client​

When Prismatic is embedded in your app, it's presented in an iframe that by default points to Prismatic's application URL (https://app.prismatic.io).

To initialize the Prismatic client, run the init function:

prismatic.init();

If you use a custom white-label domain (something like https://integrations.my-example-company.com), you can point the iframes that you embed your white-label domain instead. To do that, add this snippet of code:

Optional white-label iframe config
prismatic.init({
  prismaticUrl: "https://integrations.my-example-company.com",
});