Add embeddable component

Install Fullscript Embed

Moving into the frontend work, let’s get Fullscript Embed installed. We offer two functionally equivalent solutions, compiled from the same source:

• a UMD (Universal Module Definition)
• an NPM package (Node Package Manager)

The UMD version is a single JavaScript file packaged for direct consumption by a web browser. The NPM package can be used by any application with a bundler such as Parcel, Webpack etc.

Unless otherwise specified, all instructions work for both the UMD Build and NPM package.

UMD Build

To use the UMD build, include it as a script tag in any page of your app where you plan to host a Fullscript Embed feature:

<script src="https://public-assets.fullscript.com/fullscript.js/2.1.0/fullscript-js.umd.min.js"></script>

NPM Package

To use the NPM package, install it with:

cd your-application-folder
npm install --save @fullscript/fullscript-js

Or if you are using yarn:

cd your-application-folder
yarn add @fullscript/fullscript-js

Load Fullscript Embed

In your app’s frontend code, import or require Fullscript Embed wherever you need.

import { Fullscript } from "@fullscript/fullscript-js";

Or if using CommonJS style imports:

const Fullscript = require("@fullscript/fullscript-js").Fullscript;

Get your app’s public key

When working with Fullscript Embed, your app needs to identify itself to the Fullscript servers. There are two parts to this identification:

• User identification: OAuth access tokens + session grants (configured earlier)
• App identification: Fullscript Embed public key

Each app you configure in the Fullscript API Dashboard gets assigned a unique Fullscript Embed public key. The key is specific to the app and the target Fullscript environment the app works with. For example, the public key for an app configured to use the US Sandbox won’t work for a copy of your app that targets the US Production environment.

To get your public key, go to your app in the Fullscript API Dashboard and select the Fullscript Embed settings tab. There are three things to do on this page.

1. Verify which Fullscript environment your app is targetting. At the top of the page, look for the flag icon and text next to it to identify one of:

   • US Sandbox
   • CA Sandbox
   • US Production
   • CA Production

2. Click the pencil icon next to Origin URI and add the URLs that your integration will be loaded from. For development, this might just be http://localhost/*, but you can add a space-separated list of any URLs needed. URLs added can be full endpoints or just domains, but they must include the protocol (http can be used in sandbox, https must be used for production).

   fyi

   Fullscript protects your integration by only allowing Fullscript Embed to load on pages that come from specific domains. Origin URI is a whitelist of domains that can use Fullscript Embed with your app’s credentials.

3. Hover your mouse over the Reveal button and copy the Fullscript Embed public key for the current target environment.

Initialize Fullscript Embed

Return to your app’s code and initialize Fullscript Embed with the value you just copied as your public key.

const fullscriptClient = Fullscript({
  publicKey: "xxxxx",
  env: "us|ca|us-snd|ca-snd",
});

Set the env attribute to match the Fullscript environment your app targets. During development, use one of our two sandbox environments.

• us - targets US Production
• ca - targets CA Production
• us-snd - targets US Sandbox
• ca-snd - targets CA Sandbox

Add Platform feature

Now that you have a client, you can enable the platform feature on your page to access the full Fullscript experience, including managing treatment plans and patients, browsing the product catalog, and more.

Syntax:

const platformFeature = fullscriptClient.create('platform', <options>);

As you know, Fullscript Embed requires authorization from your users. Your app should initially prompt users for this authorization via OAuth (triggering the backend code you created earlier). On subsequent times, you can directly show them the feature.

Your app must tell Fullscript who is performing the task, and for which patient. Since the current user is logged into your app, you know which practitioner or clinic staff member is performing the operation. Remember that session grant code you implemented earlier in your back end? Go ahead and use that method to get a session grant and related secret token for your user.

It’s OK if you don’t know which Fullscript patient the treatment plan is for. You can pass along information you know about the patient, and Fullscript searches for a match. The feature will show your user a list of patient matches, and give them the option to create a Fullscript patient record one if no match is found or if the practitioner decides none is the correct match.

Initialization parameters

secretToken REQUIRED

A single-use token that is used to authenticate the practitioner or clinic staff member using the platform feature. Retrieved from the Fullscript RESTful API, see Codify user session grants.

patient OBJECT

An object describing the patient. Specify the patient’s id for an exact match, or some of the other parameters to trigger a search. Leave empty to prompt the user to create a new patient.

Child attributes:

• id (string) Fullscript patient id. If specifying the id, there’s no need to specify other attributes - they are ignored, even if they differ from what’s stored with Fullscript.
• firstName (string) The patient’s first name.
• lastName (string) The patient’s last name / family name.
• email (string) The patient’s email address.
• dateOfBirth (string) The patient’s birth date, in the format yyyy-mm-dd.
• biologicalSex (string) The patient’s assigned sex. Options are: male, female, or prefer not to say.
• mobileNumber (string) Patient's mobile number in the format +12223334444.
• discount (number) Patient discount level (in percentage). This discount does not include the clinic discount. Defaults to 0.

Example treatment plan initialization

Let’s look at a couple examples for initializing the treatment plan, and how the feature behaves based on the detail level given for the patient.

Treatment plan with a Fullscript patient id

const platformFeature = fullscriptClient.create("platform", {
  secretToken: "xxxxx",
  patient: {
    id: "xxxxx",
  },
});

If there’s a match on patient id, the patient selection screen is skipped and the treatment plan explicitly sets the patient to the one specified. Unlike other ways to match the patient, this method doesn’t trigger the patient.selected event. If there’s no match on patient id, the patient selector is shown and the user can search for or create a new patient.

Treatment plan with some patient data

const platformFeature = fullscriptClient.create("platform", {
  secretToken: "xxxxx",
  patient: {
    firstName: “Amos”,
    lastName: “Burton”
  },
});

Fullscript tries to find a patient match based on the provided data. If one (or more) is found, suggestions are shown to the user. They can choose a suggested patient or create a new one. If the user creates a new Fullscript patient, the platform feature auto-populates the new patient form with the data you used in your search.

When the patient is selected or created, you’ll receive a patient.selected event with their Fullscript patient id.

Treatment plan with no patient data

const platformFeature = fullscriptClient.create("platform", {
  secretToken: "xxxxx",
});

The user is prompted to create a new patient. You’ll receive a patient.selected event with the new Fullscript patient id.

Mount and unmount

Now that everything is set up you can mount the feature with mount(). This must be done only after your mount point (created above) is loaded. So we suggest mounting it when your app receives the DOMContentLoaded event.

document.addEventListener("DOMContentLoaded", function () {
  platformFeature.mount("fullscript-embed-container");
});

When you’re done with the feature, you can remove it with unmount(), or you can navigate away from the page.

platformFeature.unmount();

Sizing features

Fullscript Embed features fill the parent container’s available space. This means that if the mount point you create has a width and height of 900px, the embedded feature will have a height and width of 900px.

Here’s a fixed size example:

<div style="width: 900px; height: 900px;" id="fullscript-embed-container"></div>

If you want to embed the feature into a modal and your modal has strict sizing, you can set the mount point div to take all available space in the modal with the following:

<div id="my-modal">
  <div style="width: 100%; height: 100%;" id="fullscript-embed-container"></div>
</div>

If you want Fullscript Embed to take the full width and height of your page, you can use the following viewport-based units:

<div style="width: 100vw; height: 100vh;" id="fullscript-embed-container"></div>