vyyer-sdk v1.1.5

Widget SDK

The widget SDK is a set of fully functional, customizable and reusable UI components that can be installed and imported by anyone that wants to use the document scanning technology provided by Vyyer Technologies. By using the Widget SDK, programmers don't have to worry about designing themselves UI elements when integrating the services. Instead, they benefit from the abstraction provided by the developers at Vyyer Technologies.

For more information on how to integrate the Widget SDK into your wap application, please read the instructions below. Make sure you read the latest CHANGELOG.md file to see the most recent changes and improvements.

Please contact Vyyer Technologies at Contact Address.

Architecture

The widget is structured in a modular form with 2 principal components :

1. The Widget-Client which is integrated by the client into the UI. It includes different utility functions that can be very useful when using the Widget.
2. The Widget-Server which is hosted by Vyyer and served by the Widget-Client via an iframe and it's where all the processing happens.

Integration

Requirements

The integration of the widget assumes a React application with Node version 16.x and upper and npx 7.x and upper. The current widget is React specific. For other frameworks, the architectural information presented further allows a straightforward integration.

Step by step integration

1. Initialize a React application. To initialize a React application, you can follow the instructions at Create React App.
2. Install the vyyer-sdk package

    npm install vyyer-sdk

3. Contact Vyyer to provide you with an API_KEY. This key is used to identify your company by Widget-Server.

4. Create a component and generate a UID for your user. (You may not want to generate it if you already have a way to identify your users. You can use it and it will be fine)

   import React from "react";
   import VyyerWidget, { generate_uid, register_uid } from "vyyer-sdk";
   
   function BigComponent() {
     // The widget sends back an answer to the BigComponent
     // that allows you to act based on the scan result
     // although and answer is passed to the parent's
     // server callback.
     const [verdict, setVerdict] = React.useState(null);
   
     const UID = generate_uid(true);
     const API_KEY = process.env.API_KEY;
   
     React.useEffect(() => {
       // Registering the UID with Widget-Server
       (async () => {
         await register_uid(UID);
       })();
     }, []);
   
     return (
       <SomeWrapperComponent>
         {/* There you can process the verdict. By example, you can choose to display it in this component */}
         <SomeComponent result={verdict} />
         <VyyerWidget
           uid={UID}
           parent_callback={setVerdict}
           api_key={API_KEY}
         />
         <SomeOtherComponent />
       </SomeWrapperComponent>
     );
   }
   
   export default BigComponent;

5. You have a fully functional Widget integrated.

Utilities

A set of utilities are provided in this package. The role of the utilities is to help you in the process of integrating the Widget-Client. They are all used in our example App in Gitlab, in case you would like to have more contextual information

1. generate_uid : This function can be imported and generates a new UID for the client's user. It uses the user's local storage to store the UID.

   import { generate_uid } from "vyyer-sdk";
   
   const newUid = generate_uid(true);
   console.log(newUid); // ex: 6ba99e62-b4dc-421e-9f5c-12517b37fad6

2. register_uid : This function registers the UID of the user.

   import { register_uid } from "vyyer-sdk";
   
   const result = await register_uid(newUid);
   console.log(result);

3. clear_user : This function clears the user's previous results without erasing the registered UID. The user's browser is still recognized by Vyyer but all previous scans are deleted

   import { clear_user } from "vyyer-sdk";
   
   const result = await clear_user(someUID);
   console.log(result);

4. delete_user : This function deletes entirely the user's data including the previously registered UID.

   import { delete_user } from "vyyer-sdk";
   
   const result = await delete_user(someUID);
   console.log(result);

Vanilla JavaScript and other frameworks

The Widget-Client is a layer of abstraction on top of the mechanism of calling inside of an iframe the Widget-Server. Therefore, the same action can be accomplished in any framework that offers this facility. Here is an example of integration in a Vanilla JavaScript project:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta http-equiv="X-UA-Compatible" content="IE=edge" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Document</title>
  </head>
  <body>
    <div id="root">
      <button id="widget" onclick="show_widget()">Log in</button>
    </div>

    <script>
      import { generate_uid, register_uid } from "vyyer-sdk";

      const show_widget = () => {
        const api_key = process.env.API_KEY;
        root_element = document.getElementById("root");

        // Generate a new UID. If passed with false, the
        // newly generated uid will the same string each time
        const UID = generate_uid(true)(
          // Registering the UID with Widget-Server
          async () => {
            await register_uid(UID);
          }
        )();

        root_element.innerHTML = `
                <iframe
                  class="iframe"
                  height="100%"
                  width="100%"
                  title="Vyyer"
                  allow="camera *"
                  id="iframe"
                  allowFullScreen
                  scrolling="no"
                  src="https://dev.vyyer.id?uid=${UID}&api_key=${api_key}&file=index.html"
                />
            `;
      };
    </script>
  </body>
</html>