Documentation


Introduction


Welcome to Dataships. The following instructions will allow you to set up your company’s data access gateway.

The widget and admin panel work together to bring you a complete solution for managing data access requests under GDPR and the management of data subjects personal data.

The admin panel is used by the company to bring all your sources of data together in one place. This is accessible only to those within your company.

The company’s data subjects can then access their individual personal data through the widget which sits on the company’s website. They are only able to see data that the company holds on them specifically.

The Admin Panel allows you to:

  • Define the data you wish to collect from your customers or users in the Data Access Gateway
  • Upload existing Customer Data to database
  • Integrate your existing data sources
  • Manage, organize, change and export your customer data

The widget allows your data subjects to exercise their rights under GDPR. They can:

  • Sign up to your website.
  • Login to view the data you currently hold on them
  • View and change the data they wish to share with you
  • Download their data
  • Request to be deleted from your database subject to your confirmation within a 30 day period

Getting Started


There are two types of Dataships widget; one for sites with login functionality and one for those without.

If your website DOES NOT have a signup/login area for your customers/users, follow the steps below

  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

Alternatively, if your website DOES currently have a signup/login area for your customers/users on your website, follow the steps below

  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

Add Widget

Below are steps that can be taken to customize the position and look of the widget on your site.

px
px

Copy this code, and then paste it into the homepage of your website's HTML code before the closing </body> tag

                      
                      <script src="https://dataships.io/widget/dag_widget.js?api_key=YOUR_API_KEY&position=%7B%22right%22%3A20%2C%22top%22%3A20%7D&makeAuthorization=true"></script>
                    

Completing these steps should allow you to customize the widget. However, if you are still having trouble please Contact us for help.

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

};