Using the Onboarding Client
This page is part of the Developer Documentation and zooms in on how you can use the Onboarding Client of JoinData. The Onboarding Client is a javascript library that you can integrate into your website or mobile app which helps you ask consent of the farmer and thus create mandates. In short, it generates an iframe which you can embed.
Context
The Onboarding Client is part of the Purpose Registry and takes care of getting consent of a farmer for a specific participation of a purpose. To read more on these concepts, please see the Developer Documentation: Using the Purpose Registry. There is an example web app located at https://integration.join-data.net/onboarding-example/ which demonstrates the usage. View its source to see in full how it works.
Before we begin
You should already have your client account credentials that you need. Specifically, you need the client id that represents your application.
On our integration environment, by default your client will be configured to allow for a redirect to one of the following url patterns:
If you require other url’s for testing, let us know! When you are ready for production, please provide us with the production url’s.
There are two possible scenarios. We have a participation id or a purpose id.
- Scenario 1: I have a participation id.
- Scenario 2: I only have a purpose id.
Depending on your use case, you can choose either of these scenario’s.
In Scenario 1, you need to create the purpose and the participation (as described in Using the Purpose Registry). The purpose typically is registered during development time of your app. If you already know your customer (or more specifically his company identification such as his KVK), you can create the participation for that farmer up front. This can be triggered e.g. directly from your CRM system. By creating the participation yourself you also have more control over restrictions specific for that farmer. Location restrictions for example can be placed on the participation.
In Scenario 2, you only need to register the purpose. The onboarding client will help your user to log in, retrieve its company identification (e.g. the kvk in the Netherlands), create a participation and redirect the user. While this is convenient, it gives you less control over the participation of the farmer.
Scenario 1: I Have a Participation id.
Before we begin, the following requirements must be met in order to proceed.
- You should have a html page with a script element (
<script src="https://integration.join-data.net/onboarding/assets/scripts/mjd.js"></script>
) for setting up the connection.Based on the environment of your product, use the following URL’s for the appropriate environment: - Configuration details, which are the following:
- A client id which identifies your application.
- An option for mobile vs desktop.
- A participation id.
You should use the script for the correct environment; there are configuration differences between integration and production environments so you cannot use the same scripts.
The clientId has to belong to the same company as the one that has registered the purpose and participation.
The participation id is the id that was returned when registering the participation. See Developer Documentation: Using the Purpose Registry for more information.
First we need to create a configuration object with details like the following:
Config
var config = { participationId: 'cc3d7a5b-ed5b-47c2-9480-4b570b7f575f', // This is a participation id of the logged in user. desktop: false, // True for desktop mode, false for mobile mode. clientId: 'yourClientId' } ; // This is the client id of your application.
Next we are going to define a function to handle initialization errors that might occur. For now we keep it simple and just throw the error.
Error handler.
function handleError(error) { // For example purposes we just throw the error. // We could introduce some logging here and show // an appropriate message to the user. throw error; } After that we define a function to handle the initialization:
After initialization handler
function afterInit(app) { // First we check whether we are logged in if (app.isLoggedIn) { // Here we can retrieve the login token using app.token, if we need it. // If we only want to use the login token and do not want the onboarding component, // we can access app.token here and omit the rest of the example code in this body. // Add a handler to the app to receive response // about the result of the onboarding process. app.onReceiveResponse(handleOnboardingResponse); // We can now create the onboarding component. var iframe = app.createOnboardingComponent(); // Set our own custom properties. iframe.id = 'onboarding'; iframe.style.width = '375px'; iframe.style.height = '812px'; // Append it anywhere to our website. // For example purposes, we add it to the body. document.body.appendChild(iframe); } else { // We are not logged in, so we should initiate the login flow. // This call could, for example, also be wrapped inside a button press. app.login(); } }
To handle responses from the app we define the following function:
Onboarding response handler
function handleOnboardingResponse(response) { // This function will receive // communication from the onboarding app. if (response.granted) { // The participation has been granted by the user // and now we are ready to retrieve the accepted mandates. alert('granted: ' + response.message); } else if (response.refused) { // The participation has been refused by the user. alert('refused: ' + response.message); } else { // An unprocessable response has been received. alert('unknown: ' + response.message); } }
Finally, all we have to do is start the initialization process by calling the following function of the library:
Start initialization
// This will actually intialize the app. MyJoinData.App.initialize(config, afterInit, handleError);
Scenario 2: I Only Have a Purpose id
Before we begin, the following requirements must be met in order to proceed.
- You should have a html page with a script element (
<script src="https://integration.join-data.net/onboarding/assets/scripts/mjd.js">
) for setting up the connection, based on the environment of your product, use the following URL’s for the appropriate environment: - Configuration details, which are the following:
- A client id which identifies your application.
- An option for mobile vs desktop.
- A purpose id.
You should use the script for the correct environment; there are configuration differences between integration and production environments so you cannot use the same scripts.
The clientId has to belong to the same company as the one that has registered the purpose.
The purpose id is the id that was returned when registering the purpose. See Developer Documentation: Using the Purpose Registry for more information.
First we need to create a configuration object with details like the following:
Config
var config = { purposeId: 'cc3d7a5b-ed5b-47c2-9480-4b570b7f575f', // This the purpose id of your app. desktop: false, // True for desktop mode, false for mobile mode. clientId: 'yourClientId' // This is the client id of your application. } ;
Next we are going to define a function to handle initialization errors that might occur. For now we keep it simple and just throw the error.
Error handler
function handleError(error) { // For example purposes we just throw the error. // We could introduce some logging here and show // an appropriate message to the user. throw error; }
After that we define a function to handle the initialization:
After initialization handler
function afterInit(app) { // First we check whether we are logged in if (app.isLoggedIn) { // We can access several properties for more information about our current state. // We have access to: // - app.token (The jwt token information for the current login). // - app.applicationCompany (The company information for the current client). // - app.userCompany (The company information for the current user). console.log(app.token); console.log(app.applicationCompany); console.log(app.userCompany); // Add a handler to the app to receive response // about the result of the onboarding process. app.onReceiveResponse(handleOnboardingResponse); // If you do not have a participation id, follow the code to see how you can create or retrieve one for the user. if (app.participationId) { // We have a participation id. // Let's create the onboarding component. initializeUi(app); } else { // Let's find or create a participation. this.findOrCreateParticipation(app); } } else { // We are not logged in, so we should initiate the login flow. // This call could, for example, also be wrapped inside a button press. app.login(); } }
Let’s create a function that handles the UI initialisation so we can reuse it:
User Interface Initialisation
function initializeUi(app) { var iframe = app.createOnboardingComponent(); // Set our own custom properties. iframe.id = 'onboarding'; iframe.style.width = '375px'; iframe.style.height = '812px'; // Append it anywhere to our website // For example purposes, we add it to the body. document.body.appendChild(iframe); }
We need to know if there is a participation available, otherwise we need to create it:
Find or Create a Participation
function findOrCreateParticipation(app) { // First, let's try to get a participation. // Please bear in mind that the following functions look like Promises, but are not actual promises. // This is to prevent implementing functionallity that is not supported in every browser. app.getParticipation().then(function (participation) { if (participation) { // We have a participation, now start the onboarding process. // NOTE: Invoking the function 'getParticipation()' also // informs the app state of the found participation id // and automatically stores it for reuse in app.participationId. initializeUi(app); } else { createParticipation(app); } }).catch(function (error) { console.error(error); });} function createParticipation(app) { app.createParticipation().then(function (participation) { // We can access the participation here if we are interested. // We created a participation, now start the onboarding process. // NOTE: Invoking the function 'createParticipation()' also // informs the app state of the new participation id // and automatically stores it for reuse in app.participationId. initializeUi(app); }).catch(function (error) { console.error(error); }); }
To handle responses from the app we define the following function:
Onboarding response handler
function handleOnboardingResponse(response) { // This function will receieve // communication from the onboarding app. if (response.granted) { // The participation has been granted by the user // and now we are ready to retrieve the accepted mandates. alert('granted: ' + response.message); } else if (response.refused) { // The participation has been refused by the user. alert('refused: ' + response.message); } else { // An unprocessable response has been received. alert('unknown: ' + response.message); } }
Finally, all we have to do is start the initialization process by calling the following function of the library:
Start initialization
// This will actually intialize the app. MyJoinData.App.initialize(config, afterInit, handleError);