From 608f1a287265e1b2d31dd2b01c65512c5d439e08 Mon Sep 17 00:00:00 2001 From: Hunain Bin Sajid Date: Mon, 12 Feb 2024 19:23:45 +0500 Subject: [PATCH 1/2] feat: add ui developer and vendor guides --- GETTING_STARTED_VENDOR.md | 84 ++++++++++++++++++++++++++++++++++++++ GETTING_STARTED_WEB_CLI.md | 53 ++++++++++++++++++++++++ 2 files changed, 137 insertions(+) create mode 100644 GETTING_STARTED_VENDOR.md create mode 100644 GETTING_STARTED_WEB_CLI.md diff --git a/GETTING_STARTED_VENDOR.md b/GETTING_STARTED_VENDOR.md new file mode 100644 index 00000000..fa68c783 --- /dev/null +++ b/GETTING_STARTED_VENDOR.md @@ -0,0 +1,84 @@ +## UI Developer | Vendor JSON Guide + +As a vendor the first thing required is to host a json with following structure and provide the link to the customers. + +In this example we have a json hosted at following link: + +Hosted JSON Link: https://www.npoint.io/docs/d59bd3ab0b31de863a20 + +API To fetch JSON: https://api.npoint.io/d59bd3ab0b31de863a20 + +Vendor would provide the API link to their customers. + +Following is the JSON structure + +``` +{ + "title": "Provenant", + "logo": "https://media.licdn.com/dms/image/C4E0BAQG2_zXeSh-Qdw/company-logo_200_200/0/1663180132032/provenant_inc_logo?e=1715212800&v=beta&t=yINW7CaXVG50h3Ay7vu13OpY4mAu30qpijZwJAe5g-I", + "icon":"https://cdn-icons-png.flaticon.com/128/3291/3291695.png", + "theme": { + "colors": { + "primary": "#004DB5", + "secondary": "#F0F6FF", + "error": "#ec576d", + "heading": "#004DB5", + "text": "#333333", + "subtext": "#004DB5", + "white": "#ffffff", + "black": "#373e49", + "bodyBg": "#FBFBFB", + "bodyBorder": "#004DB5", + "bodyColor": "#004DB5", + "cardColor": "#004DB5", + "cardBg": "#E4F3FE" + } + } +} +``` +### title +This attribute is used to indicate the vendor name. + +### logo +This attribute is used to indicate the vendor icon. + +**title** and **logo** are shown at: +- sign in + +Screenshot 2024-02-08 at 4 07 21 AM + +- top of the sidebar + +Screenshot 2024-02-08 at 4 07 47 AM + +- heading of content script dialog + +Screenshot 2024-02-08 at 4 08 08 AM + +### icon +This attribute is used to set the icon provided by the vendor as extension icon. + +### theme +this attribute is the essence of colors (and others e.g. spacing, fonts, etc in the FUTURE) customization. +To keep it simplistic, the colors are designed to work in a two-tone fashion. +- **bodyBg** and **bodyColor** have been used for base colors of screens e.g. sign in, sidebar, and content-script dialog. These should be contrasting and complimenting as these are used for background and text respectively. +- **primary** is primarily used for buttons +- **secondary** is used as a contrasting color to make it distinct from **bodyBg**. It is used for the listings and modal background. +- **cardColor** and **cardBg** are used for the list items e.g. identifier card or credential card. +- **heading**, **text**, and **subtext** have been used for label and value pairs on each listing item. + +## JSON Theme Annotation + +### Sign in +Screenshot 2024-02-08 at 3 23 15 AM + +### Main View +Screenshot 2024-02-08 at 3 23 54 AM + +### Content Script Dialog +Screenshot 2024-02-08 at 3 24 39 AM + +The following set of JSON can be analyzed as multiple vendors (use the bin link provided at the bottom of the page). +- https://www.npoint.io/docs/1d388b8942c4ec3ed763 +- https://www.npoint.io/docs/a75a0383d2820a2153c1 +- https://www.npoint.io/docs/d59bd3ab0b31de863a20 diff --git a/GETTING_STARTED_WEB_CLI.md b/GETTING_STARTED_WEB_CLI.md new file mode 100644 index 00000000..166f6fa3 --- /dev/null +++ b/GETTING_STARTED_WEB_CLI.md @@ -0,0 +1,53 @@ +## UI Developer | Web Cli Guide + +### Installation + +1. Install [polaris-web-extension](EXTENSTION_LINK_HERE) from [Chrome Web Store](https://chromewebstore.google.com/category/extensions) +2. Install [polaris-web](https://www.npmjs.com/package/polaris-web) from npm +`npm install polaris-web --save` + +### Usage +import following methods from `polaris-web` + +``` +import { + requestAid, // call to select aid for signing in + requestCredential, // call to select credential for signing in + requestAidORCred, // call to select either aid of credential + attemptAutoSignin, // call for auto signin +} from "polaris-web"; +``` +### Usage requestAid +`requestAid` is called when authentication with AID is required, e.g: +``` + +``` + +### Usage requestCredential +`requestCredential` is called when authentication with Credential is required, e.g: +``` + +``` + +### Usage requestAidORCred +`requestAidORCred` is called when authentication with either AID or Credential is required, e.g: +``` + +``` + +### Usage attemptAutoSignin +`attemptAutoSignin` is called to auto-signin with an already selected pair. The app asks to select one from the extension if there is no auto sign-in pair exists. +``` +const handleAutoSignin = async () => { + const resp = await attemptAutoSignin(); + if (resp?.data) { + alert( + "Signed headers received\n" + + JSON.stringify(resp?.data.headers, null, 2) + ); + } + }; +``` + +### Example Usage +Visit [example-web/my-app](./example-web/my-app/src/App.js) to see example. From 68aea5b3642315a91b74d62f0d5261be19bd66dd Mon Sep 17 00:00:00 2001 From: Hunain Bin Sajid Date: Mon, 12 Feb 2024 20:08:04 +0500 Subject: [PATCH 2/2] docs: update texts as per pr changes --- GETTING_STARTED_VENDOR.md | 10 ++++++---- GETTING_STARTED_WEB_CLI.md | 4 ++-- 2 files changed, 8 insertions(+), 6 deletions(-) diff --git a/GETTING_STARTED_VENDOR.md b/GETTING_STARTED_VENDOR.md index fa68c783..45edc406 100644 --- a/GETTING_STARTED_VENDOR.md +++ b/GETTING_STARTED_VENDOR.md @@ -1,8 +1,8 @@ -## UI Developer | Vendor JSON Guide +## Vendor customization guide -As a vendor the first thing required is to host a json with following structure and provide the link to the customers. +As a vendor the first thing required is to host a URL that returns JSON with the following structure and provide the link to the customers. -In this example we have a json hosted at following link: +In this example we have a JSON hosted at following link: Hosted JSON Link: https://www.npoint.io/docs/d59bd3ab0b31de863a20 @@ -78,7 +78,9 @@ To keep it simplistic, the colors are designed to work in a two-tone fashion. ### Content Script Dialog Screenshot 2024-02-08 at 3 24 39 AM -The following set of JSON can be analyzed as multiple vendors (use the bin link provided at the bottom of the page). +To compare some examples of different vendor JSON customizations, see these links below: - https://www.npoint.io/docs/1d388b8942c4ec3ed763 - https://www.npoint.io/docs/a75a0383d2820a2153c1 - https://www.npoint.io/docs/d59bd3ab0b31de863a20 + +You can click the 'bin' link at the bottom of those pages to see the raw JSON diff --git a/GETTING_STARTED_WEB_CLI.md b/GETTING_STARTED_WEB_CLI.md index 166f6fa3..c5116d5e 100644 --- a/GETTING_STARTED_WEB_CLI.md +++ b/GETTING_STARTED_WEB_CLI.md @@ -1,8 +1,8 @@ -## UI Developer | Web Cli Guide +## Web application integration guide ### Installation -1. Install [polaris-web-extension](EXTENSTION_LINK_HERE) from [Chrome Web Store](https://chromewebstore.google.com/category/extensions) +1. Install [polaris-web-extension](FUTURE_DEPLOYED_EXTENSION_LINK) from [Chrome Web Store](https://chromewebstore.google.com/category/extensions) 2. Install [polaris-web](https://www.npmjs.com/package/polaris-web) from npm `npm install polaris-web --save`