Skip to main content

Installing the Embedded SDK

Installing Prismatic's SDK​

To embed Prismatic in your app, you must include Prismatic JavaScript code with your client application. You have two choices for incorporating this code: install the @prismatic-io/embedded NPM package in your web application Node.js project, or build the package from source and include it in your app through a <script> tag. We strongly recommend installing the SDK via NPM for 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 built with Node.js, you can include Prismatic's JavaScript code as a Node.js import. Install the Prismatic Embedded Node.js package from NPM using 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, import 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 suitable for prototyping and testing, but for production use we recommend installing Embedded through NPM. The TypeScript NPM package provides advanced features, including 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 use.

You can also download 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, execute the init function:

prismatic.init();

If you use a custom white-label domain (something like https://integrations.my-example-company.com), or if your Prismatic tenant is hosted in a different region (like EU or Australia), you can direct the embedded SDK to an alternative endpoint by specifying a prismaticUrl:

Optional endpoint config for Prismatic's SDK
prismatic.init({
  prismaticUrl: "https://integrations.my-example-company.com",
});

// or

prismatic.init({
  prismaticUrl: "https://app.eu-west-1.prismatic.io",
});

For a complete list of public endpoints, see Deployment Regions.