QuickStart for JavaScript

The digi.me private sharing platform empowers developers to make use of user data from thousands of sources in a way that fully respects a user’s privacy, and whilst conforming to GDPR. Our consent driven solution allows you to define exactly what terms you want data by, and the user to see these completely transparently, allowing them to make an informed choice as to whether to grant consent or not.

This SDK is a server side Node library that allows seamless authentication with the digi.me private sharing service written for JavaScript/TypeScript.

Requirements

Development

  • Node 10.16 or above
  • (Optional, if using TypeScript) TypeScript 3.8 or above

Installation

Using npm:

$ npm i @digime/digime-js-sdk

Example Application

You can check out an example application which uses the Digi.me SDK.

Getting Started - 5 Simple Steps!

We have taken the most common use case for the digi.me Private Sharing SDK and compiled a quick start guide, which you can find below. Nonetheless, we recommend you explore the documentation further.

This example will show you how to configure the SDK, and get you up and running with retrieving user data.

1. Obtaining your Contract ID, Application ID & Private Key:

To access the digi.me platform, you need to obtain an AppID for your application. You can get yours by filling out the registration form here.

In a production environment, you will also be required to obtain your own Contract ID and Private Key from digi.me support. However, for demo purposes, we provide example values. You can find example keys in our example application.

2. Starting out

By default, the SDK exports functions that have been pre-configured with out production environment. You can import them directly from the module:

import { establishSession } from "@digime/digime-js-sdk";

Should you need to alter the defaults, you can do so manually. See Initialise SDK for more details.

3. Establishing a session

To start requesting or pushing data, you will need to establish a session:

import { establishSession } from "@digime/digime-js-sdk";

const session = establishSession({
    "applicationId": "YOUR_APP_ID", 
    "contractId": "YOUR_CONTRACT_ID"
});

See Establish Session for more details on configuration options available when establishing a session.

In digi.me we provide two different ways to prompt user for consent

  1. Existing users who already have the digi.me application installed

    Use the authorize.once.getPrivateShareConsentUrl function to get a URL which can be used to trigger the digi.me client to open on their desktop, Android or iOS devices.

    
     import { establishSession, authorize } from "@digime/digime-js-sdk";
    
     const session = establishSession({
         "applicationId": "YOUR_APP_ID", 
         "contractId": "YOUR_CONTRACT_ID"
     });
     const redirectUrl = authorize.once.getPrivateShareConsentUrl({
         "applicationId": "YOUR_APP_ID", 
         "session": session,
         "callbackUrl": "YOUR_CALLBACK_URL"
     });
    

    With the provided session, the client will know the details of the contract and ask for the user’s permission on only the data the contract needs.

    The callbackUrl you pass in will be the URL the digi.me client will call once the user has given consent.

  2. Guest consent

    This is a demo feature which allows the user to consent and onboard to digi.me using the browser. To trigger this onboard mode, you can call the getGuestAuthorizeUrl method to get a URL which when opened will ask user for consent.

      import { establishSession, authorize } from "@digime/digime-js-sdk";
    
     const session = establishSession({
         "applicationId": "YOUR_APP_ID", 
         "contractId": "YOUR_CONTRACT_ID"
     });
     const redirectUrl = authorize.once.getPrivateShareAsGuestUrl({
         "session": session,
         "callbackUrl": "YOUR_CALLBACK_URL"
     });
    

Regardless of which mode above you trigger, the callbackUrl will be triggered once the user has authorised the consent. The callbackUrl will be triggered with a new param result where the value will either be SUCCESS, ERROR or CANCEL.

5. Fetching Data

Upon user consent you can now request user’s files. To fetch all available data for your contract you can call getSessionData to start your data fetch. You’ll need to provide us with a private key with which the SDK will try and decrypt user data. The private key is linked to the contract which you would have received when you obtained the contract ID. In addition you can pass callbacks onFileData and onFileError which will be triggered whenever a user data file is processed or if the fetch errored out.

This function will return an object containing a promise which will resolve when all the files are fetched and a function which you can trigger to stop the data fetch process.

import { pull } from "@digime/digime-js-sdk";

// Triggered when an individual file is retrieved
const fileReceivedHandler = () => console.log("File received");

// Triggered on file error
const fileErrorHandler = () => console.log("File error");

// Start fetching data
const getSessionDataObject = pull.getSessionData(
    sessionKey: SESSION_ID, // Session ID for your transaction
    privateKey: YOUR_PRIVATE_KEY, // Private key for your contract
    onFileData: fileReceivedHandler,
    onFileError: fileErrorHandler
);

// No more data to process
getSessionDataObject.filePromise.then(() => {
    console.log("Data complete");
});

See here for more details

Contributions

digi.me prides itself in offering our SDKs completely open source, under the Apache 2.0 Licence; we welcome contributions from all developers.

We ask that when contributing, you ensure your changes meet our contribution guidelines before submitting a pull request.

Further Reading

The topics discussed under Quick Start are just a small part of the power digi.me Private Sharing gives to data consumers such as yourself. We highly encourage you to explore the full documentation for more in-depth examples and guides, as well as troubleshooting advice and showcases of the capabilities on offer.

Additionally, there are a number of example apps built on digi.me. Feel free to have a look at those to get an insight into the power of Private Sharing.