@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);
})

@yardstik/embeddable-sdk