> For the complete documentation index, see [llms.txt](https://docs.transactionlink.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.transactionlink.io/docs/workflows/js-api.md).

# Widget

## How to communicate with widget?

You can interact with our widget using java script api in real-time, without the need to develop complex backend integration.

TransactionLink's JS API is available in a global variable named

{% code title="JavaScript" overflow="wrap" lineNumbers="true" %}

```javascript
window.transactionlink
```

{% endcode %}

### How to implement widget communication

To ensure the correct functioning of the widget:

1. Define `<transactionlink-widget />` element in the DOM.
2. Define `window.transactionlink_ready` method. It is called when the widget and widget API are ready to use.

   ```javascript
   window.transactionlink_ready = () => {
       transactionlink.setOptions({ token })
       transactionlink.open()
   }
   ```
3. Link `https://widget.transactionlink.io/transactionlink-widget.umd.js` to the file:
   * It should be located at the end of the file
   * Or added dynamically after completing points 1 and 2.

     ```javascript
     // Create a script element
     const script = document.createElement('script');

     // Set the source attribute to the URL of the script
     script.src = 'https://widget.transactionlink.io/transactionlink-widget.umd.js';

     // Append the script element to the document's head
     document.head.appendChild(script);
     ```

#### Simple code example:

```html
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Verification</title>
  </head>
  <body>
    <div id="transactionlink-widget"/>

    <script>
        window.transactionlink_ready = () => {
            transactionlink.setOptions({ token })
            transactionlink.open()
        }
    </script>

    <script type="text/javascript" src="https://widget.transactionlink.io/transactionlink-widget.umd.js"></script>
  </body>
</html>
```

#### Advanced code example:

```html
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Add Widget on Button Click</title>
</head>
<body>

<!-- Button to trigger the addition of the widget -->
<button id="open-widget">Open Widget</button>

<transactionlink-widget />

<script>
let transactionLinkReady = false

function openWidget() {
    if (!transactionLinkReady) {
        window.transactionlink_ready = () => {
            transactionLinkReady = true
            transactionlink.setOptions({ token })
            transactionlink.open()
        }

        const script = document.createElement('script');
        script.src = 'https://widget.transactionlink.io/transactionlink-widget.umd.js';
        document.head.appendChild(script);
    } else {
        transactionlink.setOptions({ token })
        transactionlink.open()
    }
}

// Get the button element
const addButton = document.getElementById('open-widget');

// Add a click event listener to the button
addButton.addEventListener('click', openWidget);
</script>

</body>
</html>
```

## Content Security Policy

To enhance security, include the following Content Security Policy (CSP) directive headers in the `index.html` file, within the tag:

```
Content-Security-Policy default-src 'self' *.transactionlink.io;
connect-src 'self' *.transactionlink.io wss://*.transactionlink.io *.sentry.io;
script-src 'self' *.transactionlink.io;
img-src blob: 'self' *.transactionlink.io data:;
frame-src 'self' *.transactionlink.io;
style-src 'self' *.transactionlink.io fonts.googleapis.com;
font-src 'self' *.transactionlink.io fonts.gstatic.com data:
```

## WebView Support

The widget can run inside a WebView in a mobile app, such as Android WebView, iOS WKWebView or React Native. Document upload and identity verification with the camera need access to device features. A WebView gives a page this access only when the host app allows it, so configure your WebView as described below.

{% hint style="info" %}
Example apps for native Android and React Native are available in the [transactionlink/examples](https://github.com/transactionlink/examples/tree/main/client) repository.
{% endhint %}

### Document upload

* **Android:** implement `WebChromeClient.onShowFileChooser` and open a file picker. Always call `onReceiveValue`, also with `null` when the user cancels. Otherwise the WebView does not open the file picker again.
* **iOS:** WKWebView shows the file picker natively. Add `NSPhotoLibraryUsageDescription` and `NSCameraUsageDescription` to `Info.plist`.

### Camera

Load the widget from HTTPS. When you load the page from a string, use `https://widget.transactionlink.io` as the base URL. The camera works only on a secure origin.

**Android**

* Declare `CAMERA`, `RECORD_AUDIO` and `MODIFY_AUDIO_SETTINGS` in `AndroidManifest.xml` and request them at runtime.
* Override `WebChromeClient.onPermissionRequest`. Grant `RESOURCE_VIDEO_CAPTURE` and `RESOURCE_AUDIO_CAPTURE` after the user allows the Android permission. Answer every request with `grant()` or `deny()`, because the widget and the provider can ask at the same time.
* Set `mediaPlaybackRequiresUserGesture` to `false`. The camera preview is a video that starts automatically.
* Give the WebView a fixed or `MATCH_PARENT` height. With `WRAP_CONTENT`, the default for Jetpack Compose `AndroidView`, the camera step has zero height.
* React Native (`react-native-webview`): add the permissions to `android.permissions` in `app.json` and set `mediaPlaybackRequiresUserAction={false}`. The library grants permission requests when the app has the permissions.

**iOS**

* Add `NSCameraUsageDescription` and `NSMicrophoneUsageDescription` to `Info.plist`.
* In `WKWebViewConfiguration`, set `allowsInlineMediaPlayback` to `true` and `mediaTypesRequiringUserActionForPlayback` to `[]`.
* On iOS 15 and later, implement `WKUIDelegate.webView(_:requestMediaCapturePermissionFor:initiatedByFrame:type:decisionHandler:)` and grant the request.
