API Feedback / Clarification

[lenkan]

I find the usage of the API a bit unclear. The docs specify something like this for a react app:

import { requestAid } from "polaris-web";

export function Component() {
   return <button onClick={requestAid}>Request AID</button>
}

I find it a bit confusing what to do with this. I understand there is some sort of subscription that should be done as well. I am wondering if this can be done as part of the polaris library somehow. Something like this would be simpler to use in my opinion.

import { requestAid } from "polaris-web";

export function Component() {
   async function handleRequestAid() {
       const result = await requestAid();
       console.log("App received this AID: ", result)
   }
   
   return <button onClick={requestAid}>Request AID</button>
}

Do you have any thoughts?

[HunnySajid]

I find the usage of the API a bit unclear. The docs specify something like this for a react app:

import { requestAid } from "polaris-web";

export function Component() {
   return <button onClick={requestAid}>Request AID</button>
}

I find it a bit confusing what to do with this. I understand there is some sort of subscription that should be done as well. I am wondering if this can be done as part of the polaris library somehow. Something like this would be simpler to use in my opinion.

import { requestAid } from "polaris-web";

export function Component() {
   async function handleRequestAid() {
       const result = await requestAid();
       console.log("App received this AID: ", result)
   }
   
   return <button onClick={requestAid}>Request AID</button>
}

Do you have any thoughts?

Hi, I agree that it might feel a bit confusing initially.
Let's try to look into more details.

There are three main actors:

• web script (which is signify-polaris-web)
• content script (The content script is part of extension that is running in context of web page)
• background script (It is a part of extension and can communicate with content script)

Web script communicates with content script in an event-based fashion.

When we call requestAid / requestCredential / requestAidOrCredential from web page it uses
window.postMessage API to broadcast events like select-identifier, select-credential or select-aid-or-credential.
We can not await requestAid because the workflow continues in the extension and data is not returned immediately.

Regarding subscription

Before making any call like requestAid / requestCredential / requestAidOrCredential, subscribeToSignature needs to be called as it receives a call back that contains data with headers.

Communication Flow

web script -> extension-content-script -> extension-service-worker

Please review signify-polaris-web. I am open to discuss if there is a better way to implement this. Let's continue the discussion under this thread. 🧵

[2byrds]

@HunnySajid I had a discussion with @lenkan today about the event pub/sub design. Is there a need for having an id with each request so that you know which response matches your request? Does window.postMessage help with that?
Daniel agrees that examples will be helpful. No need to dig into the details of what signify-ts returns, he's very familiar with that. But improving the documentation with examples and flow charts will be great to continue improving this discussion and the 'api'.

[HunnySajid]

@2byrds @lenkan

I have created a sequence diagram to elaborate the workflow.

Also, created a video to walkthrough the sequence diagram. (Please turn subtitles on if inaudible)

I tried to elaborate on the workflow. Let me know your feedback about it.

Also, We can add unique IDs with requests to identify.
In our example app, we did not find/consider a use case where unique IDs can be required but it would be a good addition.

[2byrds]

That's great @HunnySajid. I believe we need to update the architecture diagram to have the flow go through the content script first before it reaches the background (service worker) script. Do you agree?
https://github.com/WebOfTrust/signify-browser-extension/blob/main/arch_diagram.md

[rodolfomiranda]

sequence diagram look correct. I think you can publish to the documentation. We can add the calls to keria in a next version.

[lenkan]

I think the new additions is addressing my concerns for this specific discussion. Looks great!