Interacting with Welshare Profiles from Your Application

We deliberately keep all private and most of the correlatable information separated. Applications should not interact with private (or derived) keys of users, and users should not learn more about an application than what they absolutely must know to establish a trust relationship - as any data that they store with a particular application will automatically be shared with that application.

At the moment, web applications interact with a dialog frame that runs on the welshare.app domain and is secured by browser domain boundaries. We're finetuning the security aspects of this (quite common) solution at the moment. In case you want to try it out, make very sure not to promise anything to your test users that we cannot hold.

Try our Demo Apps

• Findrisc: https://findrisc.diabetesdao.com/ submits Fhir QuestionnaireResponses for the LOINC panel implementation of the Finnish Findrisc Diabetes Risk Score specification. Public repo: https://github.com/welshare/diabetesdao-findrisc
• Reflex: https://reflex.welshare.app/ uses a custom proprietary data schema to store data that behaves like Wearables. Public repo: https://github.com/elmariachi111/reflex-master

Install the library

The public integration library contains plain React code and doesn't contain or expose cryptographic features or Nillion connectivity. It's a plain implementation of a conversational message passing layer that orchestrates applications and the Welshare wallet:

(use npm, yarn, bun, whatever you fancy, we use pnpm: )

pnpm add @welshare/react

Configuration Prerequisites

• To integrate this, you need to register a new application id. We're referring to this as VITE_APP_ID in the code example. This id is public.

• When you're submitting a questionnaire response, you fist must register a new questionnaire with your app.

• Your app is responsible of transforming any form data to valid QuestionnaireResponses that validate against your schema. Then you use the common QuestionnaireResponse schema id provided by Welshare to the submitData function (b14b538f-7de3-4767-ad77-464d755d78bd).

• Your response must include a reference to the questionnaire that it responds to. Set your QuestionnaireResponse's questionnaire field to the questionnaire id that you've received when you created it. We're referring to this id as VITE_QUESTIONNAIRE_ID in the code example.

Submit Data to Welshare

submit-data.tsx

import { ConnectWelshareButton, Schemas, useWelshare } from "@welshare/react";

export function QuestionnaireForm() {
  const { isConnected, openWallet, submitData } = useWelshare({
    applicationId: VITE_APP_ID,
    environment: "development", //optional, at the moment the environment is always development
    callbacks: {
      onUploaded: (payload) => console.log('Data uploaded:', payload),
      onError: (error) => console.error('Error:', error),
      onSessionReady: (storageKey) => console.log('Session ready:', storageKey),
    }
  });

  const handleSubmit = () => {
    //response is a QuestionnaireResponse compatible object.
    //make sure its `questionnaire` property refers to your questionnaire definition 
    submitData(Schemas.QuestionnaireResponse, {...response, questionnaire: import.meta.env.VITE_QUESTIONNAIRE_ID});
  };

  // using the `ConnectWelshareButton` is not mandatory. Use your own buttons if you feel like it.
  return (
    <div>
      {!isConnected ? (
        <ConnectWelshareButton openWallet={openWallet}>
          Connect to Welshare
        </ConnectWelshareButton>
      ) : (
        <form>
          {/* ... some form that collects your response data ... */}
          <button onClick={() => handleSubmit(response)} disabled={isSubmitting}>
            {isSubmitting ? 'Submitting...' : 'Submit Data'}
          </button>
        </form>
      )}
    </div>
  );
}