@yardstik/embeddable-sdk
v1.3.11
Published
Public SDK for Yardstik customer's embedded views
Downloads
18,272
Readme
@yardstik/embeddable-sdk
|Build Status & Code Coverage| |---| | | |
Description
Public SDK for utilizing Yardstik embeddable views
Installation
The Yardstik embeddable-sdk library is available as an npm package.
with npm
npm i @yardstik/embeddable-sdk
with yarn
yarn add @yardstik/embeddable-sdk
Getting Started
Here is a quick example to get you started, it's all you need:
import { Yardstik } from '@yardstik/embeddable-sdk';
Available Views
Each available page view is a separate method on the exported Yardstik library object. The currently supported views are as follows:
- CandidateReportIframe: Allows the user to view and interact with a candidate report.
- AccountDisclosuresIframe: Allows the user to view and agree to account level agreements and terms.
Creating an Instance of an Available View
To create an instance of the desired view, which will be attached to a specified container on your page, call the applicable method and pass in the configuration object. For example:
const yardstikReport = new Yardstik.CandidateReportIframe(
{
token: myToken,
reportId: myReportId,
container: containerRef.current,
domain: myDomain
}
);
CandidateReportIframe
The config object for the CandidateReportIframe takes the following parameters:
token: string
- JWT for authorization
reportId: string
- The ID of the report that you would like to review
container: HTMLElement
- Container to which the iframe will be attached.
domain: string
- Yardstik domain that you would like to call.
width?: string
- Optional width of the iframe
height?: string
- Optional height of the iframe
fullScreen?: boolean
- Optional, if true, iframe will fill the entire page
AccountDisclosureIframe
The config object for the CandidateReportIframe takes the following parameters:
token: string
- JWT for authorization
accountId: string
- The ID of the account that you would like to review
container: HTMLElement
- Container to which the iframe will be attached.
domain: string
- Yardstik domain that you would like to call.
width?: string
- Optional width of the iframe
height?: string
- Optional height of the iframe
fullScreen?: boolean
- Optional, if true, iframe will fill the entire page
Obtaining JWT
To obtain a JWT to include in the config object, in your backend, post a request to the relevant Yardstik API route, using your API token for authorization. See the Yardstik developer documents for more information.
Shared Methods For Use By Parent Page
Each view has a shared method that can be called by the parent page and utilized for customization and performance.
destroy: When called, the destroy method will remove the iframe from its parent container. This method can be used by the parent page for clean-up.
yardstikReport.destroy()
Message Events
Each iframe view is set up to post certain message events to the parent page in which it is contained in order to allow the parent to take action.
loaded: Each iframe instance will post a 'loaded' message event when the iframe content has fully loaded. The parent page could listen for this event to trigger an action, such as rendering the iframe visible or turning off a loading animation. For example:
yardstikReport.on('loaded', () => {
console.log("The iframe is ready.");
setIframeReady(true)
;})
expiration: Each iframe instance will post an 'expiration' message event when the authorization token has expired. The parent can listen for this event to trigger an action, such as requesting a new JWT from your backend to refresh the session or instructing the user to refresh the page, so that a new token is generated. For example:
yardstikReport.on('expiration', () => {
console.log("The JWT has expired.");
setTokenExpired(true);
})