@digica/trust-id

v0.1.7

Published

2 months ago

Trust ID is a JS client library to work with user identification for web applications.

0High
0Medium
0Low

olegkireev

renkohens

Trust ID

Trust ID is a JS client library to work with user identification for web applications.

Two ways to use Trust ID

Frontend frameworks (React, vue, etc.)

If your application uses a bundler or node.js, you should install TrustID by npm/yarn/pnpm:

npm install @digica/trust-id

Now you can use TrustID in your application:

// CommonJS
const { TrustID } = require('@digica/trust-id');
// or ESM
import { TrustID } from '@digica/trust-id';

// Create instance of TrustID class and initialize
const trust = new TrustID({ publisherId: 42 });

Web pages without bundler and node.js

If you don't use a bundler or node.js, you can load TrustID from CDN:

<html>
  <head>
    <!-- Load TrustID library from unpkg CDN -->
    <script
      src="https://unpkg.com/@digica/trust-id"
      async
    ></script>
    <!-- OR jsdelivr -->
    <script
      src="https://cdn.jsdelivr.net/npm/@digica/trust-id"
      async
    ></script>
  </head>
  <body>
    <!-- ... Your markup ... -->
    <script>
      // Custom event that fires when TrustID is ready to be used
      document.addEventListener('TrustIDLoaded', function () {
        // You can reach TrustID from global 'window' object
        const trust = window.TrustID;
        // Initialization TrustID
        trust.init({ publisherId: 42 });
      });
    </script>
  </body>
</html>

Usage

After installation and initialization, Trustid is ready for use. The first step is to decide where to look for the user identifier. There are three ways to do this:

Get textContent of DOM element
Get value of URL query parameter
Execute a callback in any place of your application

1. DOM-Element

You should provide the ID of DOM element that you want to get the user identifier from. It'll be observed for changes, and when the element appears in DOM, the textContent of the element will be processed by library.

<script>
  // Custom event that fires when TrustID is ready to be used
  document.addEventListener('TrustIDLoaded', function () {
    // You can reach TrustID from global 'window' object
    const trust = window.TrustID;
    // Initialization TrustID
    trust.init({ publisherId: 42 });
    // "#phone-element" - is the ID of DOM element
    trust.observeDomNode('#phone-element');
  });
</script>

2. URL query parameter

You should provide the name of the URL query parameter where you can find the user identifier. The library will observe the change in the parameter, when it appears in the URL, the value will be processed by the library.

<script>
  // Custom event that fires when TrustID is ready to be used
  document.addEventListener('TrustIDLoaded', function () {
    // You can reach TrustID from global 'window' object
    const trust = window.TrustID;
    // Initialization TrustID
    trust.init({ publisherId: 42 });
    // "phone" - is the name of URL query parameter
    trust.observeQueryParam('phone');
  });
</script>

3. Callback

You can execute the callback function in any place of your application by yourself, and pass the user identifier as a parameter.

<body>
  <!-- ... Your markup ... -->
  <!-- Custom button to send user identifier -->
  <button
    id="send-user-identifier-button"
    data-user-id="+79999999999"
  >
    Send user identifier
  </button>
  <script>
    // ... TrustID initialization ...

    const button = document.getElementById('send-user-identifier-button');
    button.addEventListener('click', (event) => {
      // Get user identifier from data-attribute
      const userId = event.target.dataset['user-id'];
      // Sending user identifier
      window.trust.setUserIdentifier(userId);
    });
  </script>
</body>

Web applications

All the above methods can be used in web applications.

React example

import { TrustID } from '@digica/trust-id';

// Create instance of TrustID, initialize and export it for access from other components
// You don't have to execute "init" method, just pass config in constructor
export const trust = new TrustID({ publisherId: 42 });

function App() {
  const [userIdentifier, setUserIdentifier] = useState('');

  const handleButtonClick = () => {
    trust.setUserIdentifier(userIdentifier);
  };

  return (
    <div>
      <input onChange={(e) => setUserIdentifier(e.target.value)} />
      <button onClick={handleButtonClick}>Process user identifier</button>
    </div>
  );
}

Debug mode

There isn't any debug logs by default, but you can turn them on by setting debug option to true in initialization. After that, you can see logs in your browser console.

<script>
  document.addEventListener('TrustIDLoaded', function () {
    const trust = window.TrustID;
    // Enable "debug" mode
    trust.init({ publisherId: 42, debug: true });
  });
</script>