Data Access Gateway (v1)


Last modified: June 06 2019 11:01. UTC

Introduction

If your website currently have a signup/login area for your customers/users on your website, follow the steps below to get started:

  1. Insert your website URL on the Profile Data tab of the Data Access Gateway page and click Save
  2. customize the widget and generate your code automatically
  3. Copy the code generated and insert it into your web-page
  4. Organize interactions with the widget using its APIs

If your web-site performs user authorization (signup and login), then you must transfer the logged-in user's data to the widget using its APIs.
After the user successfully logs in, the widget will call the JavaScript call back function DataAccessGateway.success("login", userData) to handle the user's login and transfer the data. See Examples

DEVELOPMENT

Functions

The global object window.DataAccessGateway contains the methods necessary for data exchange and management of the widget:

  • DataAccessGateway.signup(data: object, directSave: boolean)

    Parameters:

    1. data: object cotaining the data of the authorized user (required)

      userId
      (string)
      Unique User ID, which you must generate and store. E.g. "123e4567-e89b-12d3-a456-426655440000"
      formData
      (array)
      Contains data entered by the user during registration, each of fields must be in the following format: {name: string, value: string}
    2. directSave: the direct data saving flag (optional)

      true tells the widget to store the transmitted data without user confirmation.
      false the widget will show the users a form to confirm their details before saving.
  • DataAccessGateway.logon(UUID)

    This will get the widget to load their data from the Data Access Gateway. The widget will then show their data which they can edit/delete.

  • DataAccessGateway.logout()

    They will no longer be able to change their data through the widget. The widget will request them to login to your website in order to manage their data.

Events

The following predefined events are available to use through the window.DataAccessGateway object:

init initialization of the widget
create creates a new record in the database (after call DataAccessGateway.signup() function)
update modification of authorized data by the user (after click on "Proceed" button)
delete deletion of the user from the Data Access Gateway system (after click on "Be forgotten")
login authorize user via widget
logout logs out user via widget

Event Handlers

Once the code for the widget has been injected into your website, the window.DataAccessGateway object can be used.

For each events above, you can define two event handlers within your custom script:
DataAccessGateway.success(event, data)
DataAccessGateway.error(event, error)

After loading the widget, an initialization event will occur in it and the widget will call the DataAccessGateway.success("init", data) method. This event should serve as your a signal that the widget is ready to work and your custom code should be placed inside this method. Only then, your custom script can call the other widget methods.
If an error occurred during the initialization, any further work with the widget will be impossible. Use the DataAccessGateway.error("init", data) method to get details on the error. Please contact Dataships Support for further assistance.

Parameters:

event the name of the event that occurred in the widget. A complete list of events are given.
data the user data. They contain the user ID and the scheme of fields, tables and tick-boxes, which was defined in the Admin Panel. If there is no authorized user at the time of data transfer, then within the data the user ID will be null, and the data values in the fields and user table will be empty.
                             {
  // uuid of user in the Data Access Gateway system
  id: "ee71ee7d-b14e-4a01-8e79-10ff1ff6c884",
  // user data according to the fields set by you in the Admin Panel
  data: [
    {
      id: 1,
      name: "e-mail",
      value: "username@example.com",
      is_allow: true
    },
    ...
  ]
}
                           
error the Javascript ERROR object.

These methods are automatically called by the widget. They can be used to inform your website of the widget condition or to pass the user's data to your website. You can also pass data from your website to the widget through the DataAccessGateway object.

User Actions:

  • After the user clicks the "Proceed" button in the widget panel, the widget will save the user data and, if successful, call the DataAccessGateway.success("update", data) method.
  • After the user clicks the "Be forgotten" button in the widget panel, the widget will delete all user data and, if successful, call the DataAccessGateway.success("delete", data) method.

The widget has the functionality for self-authorization of users, including Sign Up, Sign In, Log Out and Password Recovery. When the user logs in or logs out, the widget reports this to the website using the "login" and "logout" events, respectively.

When the user is signed in to the widget, the widget loads its data, then calls the DataAccessGateway.success("login", data) method.

In case of an error, the DataAccessGateway.error("login", error) method will be called.

When the user logs out, the widget clears their data in its memory, then calls the DataAccessGateway.success("logout", data) method.

In case of an error, the DataAccessGateway.error("logout", error) method will be called.

                    
                    
window.DataAccessGateway.success = function(event, data) {
  if (event === "login") {
    // widget login success
    console.log("login function");
  }
  if (event === "logout") {
    // widget logout success
    console.log("logout function");
  }
  // handle other events

};

window.DataAccessGateway.error = function(event, error) {
  if (event === "login") {
    // widget login error
    console.log("login error");
  }
  if (event === "logout") {
    // widget logout error
    console.log("logout error");
  }
  // handle other event errors

};