Sync Widget Javascript SDK

The Sync Widget JavaScript SDK makes it easy to integrate Data Synchronization into your application, enabling users to effortlessly manage their data in the Portabl Passport™.

⚠️

This guide assumes that all prerequisite steps are applied and configured as mentioned in the Data Sync tutorial.

Installation

  npm install --save @portabl/js-sync-with-portabl

Add the root element

Add a <div> element to the location where you would like the widget to render. This <div> should be placed inside the body of your HTML file (i.e. <body> tag) with an id attribute equal to "portabl-sync-root" or a custom value that you can reference when initializing the widget.

<div id="portabl-backup-root"></div>

Initialization

Initialize the Sync Widget SDK with the necessary properties to render it into the root element created above.

Load the Sync Widget as an ES Module

  import { createSyncWithPortabl } from '@portabl/js-sync-with-portabl'
  
  await createSyncWithPortabl({
    // #portabl-sync-root is the default value for the root selector. 
    // If you set a different id on the div above you should change 
    // this value to match.
    rootSelector: '#portabl-sync-root', 
    widgetBaseUrl: 'https://widgets.getportabl.com',
    getSyncContext: async () => {
      const { data } = await axios.get(`http://localhost:3001/sync-context`);
 
      return data;
    },
    prepareSync: async () => {
      const { data } = await axios.post(`http://localhost:3001/prepare-sync`);
 
      return {
        invitationUrl: data.invitationUrl,
        isLinked: data.isLinked,
      };
    },
  });

Manually load the Sync Widget script

Alternatively, if you installed the widget via CDN you can initialize it manually.

<script>
  await Portabl.sync.createSyncWithPortabl({
    // #portabl-sync-root is the default value for the root selector. 
    // If you set a different id on the div above you should change 
    // this value to match.
    root: '#portabl-sync-root', 
    widgetBaseUrl: 'https://widgets.getportabl.com',
    getSyncContext: async () => {
      const { data } = await axios.get(`http://localhost:3001/sync-context`);
 
      return data;
    },
    prepareSync: async () => {
      const { data } = await axios.post(`http://localhost:3001/prepare-sync`);
 
      return {
        invitationUrl: data.invitationUrl,
        isLinked: data.isLinked,
      };
    },
  });
</script>

Options

Option	Type	Default	Description
root	string \| HTMLElement	#portabl-sync-root	The element or selector of the `<div>` that the sript will render the widget to.
widgetBaseUrl	string	https://widgets.getportabl.com	The url from which to load the widget
getSyncContext	() => Promise<{ isSyncOn: boolean; isSessionEstablished: boolean; datapoints: string[]; issuerDIDs: string[]; }>		function that calls the Sync Context api endpoint and returns the response
prepareSync	() => Promise<{ isLinked: boolean; invitationUrl?: string; }>		function that calls the Prepare Sync api endpoint and returns the response

📕 Terminology React