.. _integration: How to Integrate ================ Introduction to Integration ---------------------------- Integrating UTU into your app enables users to share their feedback and endorsements with other users in your and other apps. For this purpose, UTU provides an easy to use Web SDK and an API. This chapter describes all the required steps. Using the UTU Web SDK --------------------- UTU provides SDKs to easily integrate the UTU Trust Engine into client apps. This includes showing relevant recommendations and providing user feedback after they used a service or bought a product or asset. Currently, the SDK supports any Javascript-enabled web app, including React, Vue.js, Angular (all versions), php or vanilla html. Support for mobile apps (Android, iOS) will be added soon. SDK Initialization and Wallet Authentication ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ As described above, UTU takes feedback from users and shows personalized feedback about services and products. This means that the UTU Trust Engine deals with user-specific and, in some cases, sensitive data. In the future, this will be handled by zero-knowledge methods. For now, this information is stored in UTU's backend. Authentication for the same is based on the user signing-in with their web3 wallet and works as follows: 1. **Connect the Wallet**: The user initiates the process by selecting to connect their web3 wallet within the application, as is usual in typical web3 d-apps. See our example apps for how this can be done, e.g. using `web3modal `_ from a `"Connect to Wallet" button in the React example app `_. 2. **Sign a Message**: An authentication message is generated by the UTU SDK using the SDK's `addressSignatureVerification()` function. The user signs this message using their private key within the web3 wallet. This step can be triggered automatically after the wallet is connected, or by the user clicking a button. See our example apps for how this can be done, e.g. the `"Connect to UTU" button in the React example app `_. 3. **Verify the Signature**: After the user signs the message in the previous step, the SDK automatically sends it to the UTU backend, which verifies the signature against the user's public address. This ensures that the user is the owner of the web3 wallet. The resulting `AuthData`-type response is returned asynchronously from `addressSignatureVerification()`. See e.g. the `addressSignatureVerification() call in the React example app `_. 4. **Token Generation**: Upon successful verification, the returned `AuthData` contains a user-specific and time-limited token (JWT) generated by the UTU API. This token authorizes the user's access to the UTU Trust Engine for a limited time. In the future, the SDK will automatically store this. For now, the token needs to be passed back to the SDK by dispatching a `utuIdentityDataReady` event, with the `AuthData` set as the value of a `detail` property. See e.g. `dispatching an "utuIdentityDataReady" event in the React example app `_. Informing the UTU Trust Engine about Entities ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ To show relevant feedback about an entity to a user from their own network, the UTU Trust Engine needs to be informed about relationships between users, and about the entities about which feedback is given. This could be tokens, other smart contracts or other entities such as urls, as is done e.g. in the UTU Browser Extention. While relationships are automatically added for users who connect social media platforms -- via the Social Media Connectore -- or who have on-chain transactions -- via the blockchain scanner --, entities need to be added manually. This is done by calling the `POST /entities` service of the :ref:`UTU API `. In the future, we will provide a function in the UTU SDKs which will make this process easier. For now, you can refer to our example apps how this can be done, e.g. `in the React example app `_. There are certain already existing target types in the shared global database, such as "DeFiProtocl" or "Address"; we encourage integrators to enquire with us what best to use here. Getting Recommendations and Providing Feedback ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Having been informed about entities and relationships between them, the UTU Trust Engine can serve social recommendations or other feedback, provided that users give that feedback. For this, the :ref:`UTU API ` provides the `GET /ranking`, `POST /feedback` and `GET /feedbackSummary` services. However, UTU’s frontend SDKs also provide ready-made UI components which can be easily added to the client app and which take care of the invocation of these services automatically (see next section “SDK Usage”). Generally, the user journey through a client platform app, including showing UTU recommendations, feedback details, and providing feedback, looks similar to this sequence: .. Note: when the diagram was changed, find the new file name in _build/html/_plantuml/... and update the link here: .. uml:: UTU API Sequence Ranking and Feedback.puml :caption: `UTU API Sequence Ranking and Feedback <../_plantuml/0d/0d1f70f73e4771d89543c06b070c549f66dd1d9e.svg>`_ :align: center SDK Usage ~~~~~~~~~ Typically, an app will have a page showing a selection of services or products to a user. This could be the app’s start page, or a page with search or filter results. We call this an “offer page”. On this page, UTU’s SDK can be used to show feedback summary, where available, for each offered service or product. We also call feedback summary about an entity a "recommendation". Just import the UTU SDK library, wrap the offers list in an `` element (this triggers loading of relevant recommendations from UTU backend) and put an `` element where UTU's recommendation should be shown. The SDK can also show a button to open a popup view with feedback details, using the `` element, and for asking feedback from the user after a transaction with the `` element. Both are also available as non-popups, to be shown inline e.g. in a service/product detail page and a post-transaction “thank you” or similar page. Detailed information about all UTU web components can be found in the :ref:`Web Components Reference section `. Here is a simple example, showing the use of these elements in an “Offers” function, which is a minimal component to show a list of offers, in a React app: .. code-block:: typescript export default function Offers(props: any) { let offers = props.offers; let _window: any = window; let provider = _window.ethereum; let walletAddress = provider.selectedAddress; // @ts-ignore return (
    { offers.map((offer: any) =>
  • {offer.name}

    • ) }
); } Example Apps ~~~~~~~~~~~~ The full React and other example d-apps can be viewed and cloned from the following repositories: - `utu-trust-sdk-react-example-dapp `_ - `utu-trust-sdk-angular-example-dapp `_ - `utu-trust-sdk-vue-example-dapp `_ - `utu-trust-sdk-vanilla-js-example-dapp `_ .. _web-components-reference: Web Components Reference ~~~~~~~~~~~~~~~~~~~~~~~~ This section describes all the web components provided by the UTU Web SDK. The components are designed to be used in any Javascript-enabled web app. They're provided roughly in the order of a typical integration workflow. x-utu-root ^^^^^^^^^^ Description """"""""""" The ``x-utu-root`` component serves as the main container for the recommendation system. It fetches ranking data from the API and dispatches a "loaded" event with the ranking data. Attributes """"""""""" - ``source-uuid``: (Required) Specifies the source UUID for the ranking. - ``target-type``: (Required) Specifies the target type for the ranking. There are certain already existing target types, such as "DeFiProtocol" or "Address"; we encourage integrators to enquire with us what best to use here. - ``target-uuids``: (Optional) Specifies a space-separated list of target UUIDs, if a predefined list of entities is to be ranked. If this is not provided, the ranking will include all entities of the given type. Example Usage """"""""""""" .. code-block:: html Events """""" - ``loaded``: Dispatched when the ranking data is loaded. The event detail contains the ``data`` property with the ranking items. x-utu-recommendation ^^^^^^^^^^^^^^^^^^^^ Description """"""""""" The ``x-utu-recommendation`` component displays a recommendation based on the ranking data provided by the ``x-utu-root`` component. It listens to the "loaded" event from the ``x-utu-root`` component to get the ranking data and renders the recommendation accordingly. Attributes """"""""""" - ``target-uuid``: (Required) Specifies the target UUID for the recommendation. Example Usage """"""""""""" .. code-block:: html .. _x-utu-feedback-details: x-utu-feedback-details ^^^^^^^^^^^^^^^^^^^^^^ Description """"""""""" The ``x-utu-feedback-details`` component displays detailed feedback information, including videos, star ratings, badges, endorsements, and text reviews. It provides both mobile and desktop views. This is for displaying feedback details inline in other components. If a popup is preferred, use the :ref:`x-utu-feedback-details-popup ` component instead. Attributes """"""""""" - ``source-uuid``: (Required) Specifies the source UUID for the feedback details. - ``target-uuid``: (Required) Specifies the target UUID for the feedback details. Example Usage """"""""""""" .. code-block:: html .. _x-utu-feedback-details-popup: x-utu-feedback-details-popup ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Description """"""""""" The ``x-utu-feedback-details-popup`` component provides a button to display detailed feedback information in a popup window. It includes videos, star ratings, badges, endorsements, and text reviews. This is for displaying feedback details inline in other components. If a popup is preferred, use the :ref:`x-utu-feedback-details-popup ` component instead. Attributes """""""""" - ``source-uuid``: (Required) Specifies the source UUID for the feedback details. Example: "0x123..." - ``target-uuid``: (Required) Specifies the target UUID for the feedback details. Example: "0x456..." - ``btn-color``: (Optional) Specifies the button color. Example Usage """"""""""""" .. code-block:: html utu-feedback-form ^^^^^^^^^^^^^^^^^ Description """"""""""" The ``utu-feedback-form`` component provides a form to collect feedback from users. It includes sections for recording videos, star ratings, badges, text input, and endorsements. Attributes """""""""" - ``source-uuid``: (Required) Specifies the source UUID. - ``target-uuid``: (Required) Specifies the target UUID. - ``transaction-id``: (Optional) Specifies the transaction ID. Example Usage """"""""""""" .. code-block:: html utu-feedback-form-popup """"""""""""""""""""""" Description """"""""""" The ``utu-feedback-form-popup`` component provides a popup form to collect feedback from users. It includes sections for recording videos, star ratings, badges, text input, and endorsements. Attributes """""""""" - ``source-uuid``: (Required) Specifies the source UUID. - ``target-uuid``: (Required) Specifies the target UUID. - ``transaction-id``: (Optional) Specifies the transaction ID. - ``btn-color``: (Optional) Specifies the button color. Example Usage """"""""""""" .. code-block:: html x-utu-header ^^^^^^^^^^^^ Description """"""""""" The ``utu-header`` component provides a simple header "Feedback From Your Network". Example Usage """"""""""""" .. code-block:: html x-utu-app-link ^^^^^^^^^^^^^^ Description """"""""""" The ``x-utu-app-link`` component provides a button that links to the UTU social link URL. Example Usage """"""""""""" .. code-block:: html x-utt-balance ^^^^^^^^^^^^^ Description """"""""""" The ``utt-balance`` component displays the balance of UTT (a specific token) in the user's wallet. It fetches the balance using the connected wallet. A loading indicator is shown while the balance is being fetched. Example Usage """"""""""""" .. code-block:: html x-utu-wallet-connect ^^^^^^^^^^^^^^^^^^^^ Description """"""""""" The ``utu-wallet-connect`` component provides a button to connect a user's wallet. It's designed to interact with Ethereum wallets and displays a prompt to see UTU trust signals from the user's network. This is mostly useful for non-web3 apps that don't provide their own wallet connection but still want to use UTU's trust signals. Example Usage """"""""""""" .. code-block:: html x-utu-disconnect-wallet ^^^^^^^^^^^^^^^^^^^^^^^ Description """"""""""" The ``utu-disconnect-wallet`` component provides a button to disconnect a user's wallet. It's designed to interact with Ethereum wallets and allows the user to disconnect their wallet from the application. This is mostly useful for non-web3 apps that don't provide their own wallet connection but still want to use UTU's trust signals. Example Usage """"""""""""" .. code-block:: html .. _api: Using the UTU API ----------------- The UTU API is a RESTful API which can be used separately or in addition to the UTU SDKs if more fine-grained control is needed. For a summarised list of the API's main concepts (types), see :ref:`Main Concepts ` in the Introduction. OpenAPI Specification ~~~~~~~~~~~~~~~~~~~~~~~ Download the `OpenAPI specification for the UTU API <../_static/api-specs/trustApi.yaml>`_, which can be used to generate client libraries for various languages. Trust API Specification Reference ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. openapi:: ../_static/api-specs/trustApi.yaml :examples: :group: