[Integration - Getting started] How to integrate API PD Measurement?

Requirements and options to integrate PD Measurement API

Requirements

PD Measurement requires a unique apiKey.

If we did not provide you with your apiKey, please contact our customer support.

Integration

This integration can be used on any type of page.

Add the script in to the page :

<head>
...
  <script src="https://msrt-integration-api.fittingbox.com/index.js" type="text/javascript"></script>
</head>

Add an element with the following id to the page that will contain PD Measurement when open :
```
<div id="msrt-container"></div>
```
This element will receive an iframe with PD Measurement, so it must have a size, for example :
```
#msrt-container { width: 400px; height: 740px; }
```

Once the script at step 1 is loaded, it will expose a variable called Msrt on the page, use it to open PD Measurement when needed via the function createWidget :

window.addEventListener("load", function () { // This example load the API PD Measurement on the page. to open thanks to a button for example please refer to https://www.fittingbox.com/en/resources/help-center/fc-how-do-i-integrate-the-tool-on-my-website
  Msrt.createWidget("msrt-container", {
    apiKey: "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" // This is an example apiKey and must be updated with your own apiKey
  });
});

- The first parameter is the id of the PD Measurement container from step 2.
- The second parameter is an object containing the PD Measurement options.

To learn more about container size : https://www.fittingbox.com/en/resources/help-center/container-size

Example of Popup integration : https://www.fittingbox.com/en/resources/help-center/fc-how-do-i-integrate-the-tool-on-my-website

Example of integration with results automatically filled : https://www.fittingbox.com/en/resources/help-center/fc-how-do-i-export-measurement-results-to-my-site

Options

param	type	description	example
apiKey (required)	string	The apiKey allowing the use of PD Measurement	Msrt.createWidget("msrt-container", { apiKey: "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", // This is an example apiKey and must be updated with your own apiKey });
pdCopyClipboard default: false	boolean	Add a button to copy the results to clipboard at the end of the experience. Usefull when the results are not programmatically retreived via onGetResultPd (see below)	Msrt.createWidget("msrt-container", { apiKey: "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", // This is an example apiKey and must be updated with your own apiKey pdCopyClipboard: true, });
onGetResultPd	callback function (result: { pd: number, left?: number, right?: number }) => {}	A callback function containing the PD result once the user has finished. The left and right values can be empty if the user does not have glasses, it is a single PD. Otherwise we have the single PD + left and right mono PDs.	Msrt.createWidget("msrt-container", { apiKey: "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", onGetResultPd: (result) => { console.log('Pupillary distance', result.pd); console.log('Left', result.left); console.log('Right', result.right); }, })
onTooManyErrors	callback function () => {}	A callback function triggered when the user has failed 3 times the experience. Can be used to know when contacting a user having trouble to get PD measure.	Msrt.createWidget("msrt-container", { apiKey: "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", onTooManyErrors: () => { console.log('Too many errors'); }, })
onClose	callback function () => {}	A callback used to notify when the experience is over, after clicking the close button in the top right corner or the “Finish“ button at the end of the experience.	Msrt.createWidget("msrt-container", { apiKey: "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", onClose: () => { console.log('Closed, hide the msrt-container'); }, })
darkMode default: false	boolean	Set background theme colors as dark. if value is false, original light colors theme is displayed see CodePen exemple : here	Msrt.createWidget("msrt-container", { apiKey: "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", // This is an example apiKey and must be updated with your own apiKey darkMode: true, });
theme	string	Set color values for specific area (Hexadecimal) if any param missing, default value is displayed. see article : how to customize colors see CodePen exemple : here	theme: { mainColor: mainColor.value, buttonTextColor: buttonTextColor.value, // #181B1C default dark mode instructionColor: instructionColor.value, // #FFFFFF default dark mode colorWrong: colorWrong.value, colorMid: colorMid.value, colorValid: colorValid.value, },
disableNpsRating default: false	boolean	Disable user rating step by setting parameter to true	Msrt.createWidget("msrt-container", { apiKey: "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", // This is an example apiKey and must be updated with your own apiKey disableNpsRating: true, });