Skip to main content
Version: v3

Upgrade to the latest SDK

The Client SDK for Portal 3 contains a number of exciting changes. After finishing this guide, you will enjoy an updated Flatfile implementation.


How to upgrade

info

Portal 3 installs the Client SDK from @flatfile/sdk.
Portal 2 installed the Client SDK from @flatfile/adapter.

Using npm:

npm install @flatfile/sdk

Using unpkg:

<script src="https://unpkg.com/@flatfile/sdk/dist/index.js"></script>

What's new

Import and initialization

flatfileImporter() function no longer should be used to initialize the Flatfile Import. We added the Flatfile class that would allow you to create an instance with all additional configurations.

Note: Embeds created in production mode have to be authenticated. See below

import { Flatfile } from '@flatfile/sdk'

const flatfile = new Flatfile({
embedId: 'YOUR_EMBED_ID', // Embed ID created in developer mode
user: { id: 1, name: 'Max', email: 'max@flatfile.com' },
company: { id: 1, name: 'Flatfile Inc' }
}

Requesting and processing data from user

document.querySelector('button').addEventListener('click', async () => {
...
flatfile.requestDataFromUser((chunk, next) => {
// do something
chunk.records.forEach(console.log)
next()
}, { chunkSize: 100 })
})

Promise

This method is NOT recommended due to inefficiency of fetching all data at once. Large imports may take a long time.

document.querySelector('button').addEventListener('click', async () => {
...
flatfile.requestDataFromUser().then(async response => {
const records = await response.data() // this will fetch all the records
records.forEach(console.log)
})
})

Authenticating users

Once you're ready to move to production, we require server-side authentication to provide the most secure import for your customers.

How to generate Flatfile token

onAuth will be executed as soon as .requestDataFromUser() is called. We will display the "Authenticating" loader dialog while you're generating the token.

import { Flatfile } from "@flatfile/sdk";

const flatfile = new Flatfile({
// onAuth will automatically display "Authenticating" loader dialog
onAuth: async () => {
// Fetch the JWT from your server
const response = await fetch("/auth-flatfile", {
method: "POST",
headers: { "Content-Type": "application/json" },
});
const { token } = await response.json();

return token;
},
embedId: "YOUR_EMBED_ID",
user: { id: 1, name: "Max", email: "max@flatfile.com" },
company: { id: 1, name: "Flatfile Inc" },
});

Pre-generated JWT

import { Flatfile } from "@flatfile/sdk";

const response = await fetch("/auth-flatfile", {
method: "POST",
headers: { "Content-Type": "application/json" },
});
const { token } = await response.json();

const flatfile = new Flatfile({
token, // Initialize Flatfile with the generated JWt
embedId: "YOUR_EMBED_ID",
user: { id: 1, name: "Max", email: "max@flatfile.com" },
company: { id: 1, name: "Flatfile Inc" },
});