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.
- Node 8 or above
$ npm i @digime/digime-js-sdk
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. Configuring the SDK
The SDK will initialise to point to our production environment, however you also have the ability to override the default behaviour and specify some options.
const init = (sdkOptions?: Partial<DMESDKConfiguration>);
See Initialise SDK for more details
3. Establishing a session
To start requesting or returning data to the user, you will need to first establish a session.
Initialise a session with digi.me API which returns a session object.
const establishSession = async ( appId: string, contractId: string, scope: CAScope ): Promise<Session>;
See Establish Session for more details on configuration options available when establishing a session.
4. Requesting Consent
In digi.me we provide two different ways to prompt user for consent
Existing users who already have the digi.me application installed - Use the
getAuthorizeUrlmethod to get a Url which can be used to trigger the digi.me client to open on their desktop, Android or iOS devices. The callbackUrl you pass in will be the Url the digi.me client will call once the user has given consent. Given the session id, the client will know the details of the contract and ask for the user's permission on only the data the contract needs.
const getAuthorizeUrl = ( appId: string, session: Session, callbackUrl: string ): string;
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
getGuestAuthorizeUrlmethod to get a Url which when opened will ask user for consent.
const getGuestAuthorizeUrl = ( session: Session, callbackUrl: string ): string;
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
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 we 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
onFileError which will be triggered whenever a user data file is processed or if the fetch errored out.
This function will return a promise and which will resolve when all the files are fetched and a function which you can trigger to stop the data fetch process.
const getSessionData = ( sessionId: string, privateKey: NodeRSA.Key, onFileData: FileSuccessHandler, onFileError: FileErrorHandler ): GetSessionDataResponse;
See here for more details
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.
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.