Skip to content
DigiMe javascript SDK
TypeScript
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github/ISSUE_TEMPLATE
certificates
docs
fixtures/network
src
tools
utils
.gitignore
.npmignore
.npmrc
CONTRIBUTING.md
Jenkinsfile
LICENSE
README.md
jest-config.json
package-lock.json
package.json
tsconfig.dist.json
tsconfig.json
tsconfig.module.json
tslint.json

README.md

Developer Chat Apache 2.0 License Typescript Web


Introduction

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 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. 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

  1. Existing users who already have the digi.me application installed - Use the getAuthorizeUrl method 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;
  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.

    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 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 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 onFileData and 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

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.

You can’t perform that action at this time.