# Embedding Singpass JS

We provide a **core JavaScript library** (Singpass JS) to enable seamless integration with the Singpass Digital Signing Service (DSS). It facilitates transaction signing workflows for Relying Party (RP) applications, covering steps **2.1 to 5.3** in the flow diagram.

**Key Functionalities**

* **Initialisation**: Singpass JS is initialised in the RP’s frontend to set up the transaction signing process.
* **Session Management**: Starts the signing session with transaction details (Step 2.1).
* **QR Code Rendering**: Generates and displays the QR code for the user to scan via SingPass Mobile App (Step 2.2).
* **Status Handling**: Tracks user actions, returning the CHALLENGED status when the QR code is scanned (Step 3.2).
* **Success Confirmation**: Confirms the signed challenge response and returns the success status with the sign code (Step 5.3).

RPs shall embed this Javascript in your front end application. 

## **URLs**

<table><thead><tr><th width="178">Environment</th><th width="576">URL</th></tr></thead><tbody><tr><td>Staging</td><td><p><a href="https://static.staging.sign.singpass.gov.sg/static/ndi_txn_sign.js">https://static.staging.sign.singpass.gov.sg/static/ndi_txn_sign.js</a><br>OR</p><p><a href="https://stg-id.singpass.gov.sg/static/ndi_txn_sign.js">https://stg-id.singpass.gov.sg/static/ndi_txn_sign.js</a> <mark style="color:red;">(Deprecated)</mark></p></td></tr><tr><td>Production</td><td><a href="https://static.app.sign.singpass.gov.sg/static/ndi_txn_sign.js">https://static.app.sign.singpass.gov.sg/static/ndi_txn_sign.js</a><br>OR<br><a href="https://id.singpass.gov.sg/static/ndi_txn_sign.js">https://id.singpass.gov.sg/static/ndi_txn_sign.js</a> <mark style="color:red;">(Deprecated)</mark></td></tr></tbody></table>

{% hint style="warning" %}
You **must provide your frontend origin** during onboarding to allow communication with us.
{% endhint %}

## Content Security Policy (CSP) Requirements <a href="#content_security_policy_csp_requirements" id="content_security_policy_csp_requirements"></a>

This section is important if the RP’s website (where Singpass JS is embedded) uses a Content Security Policy (CSP) header. For Singpass JS to fully function, please ensure that the following CSP attributes are set/added:

* `script-src` [`https://*.singpass.gov.sg`](https://*.singpass.gov.sg/)`;`
* `connect-src` [`https://*.singpass.gov.sg`](https://*.singpass.gov.sg/)`;`
* `style-src` [`https://*.singpass.gov.sg`](https://*.singpass.gov.sg/)`;`
* `img-src` [`https://*.singpass.gov.sg`](https://*.singpass.gov.sg/) `data:;`
* `font-src` [`https://fonts.gstatic.com`](https://fonts.gstatic.com/)`;`

Sample CSP header:&#x20;

{% code overflow="wrap" %}

```
content-security-policy: default-src 'self'; script-src 'self' https://*.singpass.gov.sg; connect-src'self' https://*.singpass.gov.sg; style-src 'self' https://*.singpass.gov.sg; img-src 'self' https://*.singpass.gov.sg data:; font-src https://fonts.gstatic.com;
```

{% endcode %}

{% hint style="info" %}
It is not necessary to set/add any CSP attributes if the **RP’s website does not use a CSP header** or has **less strict policies** for all the attributes mentioned above.
{% endhint %}

## UI dimensions <a href="#ui_dimensions" id="ui_dimensions"></a>

The HTML elements will be rendered in a rectangular area with a fixed size with these dimensions, depending on the mode specified via the `additionalOptions` parameter:

| Mode                                 | Dimensions (width by height) |
| ------------------------------------ | ---------------------------- |
| Basic QR with no additional elements | 298px by 367px               |
| QR with download link                | 298px by 416px               |

{% hint style="danger" %}
The RP must allot a minimum space according to these dimensions for the transaction signing UI element to be rendered properly.
{% endhint %}

## UI Reference <a href="#ui_reference" id="ui_reference"></a>

For RP’s reference, this section displays the screens that Singpass JS renders during the transaction signing process. RPs can refer to these screens to get a better idea of how integrating with Singpass JS will look like on their website.

The green border indicates the [`minimum expected size of the DOMElementID`](#ui_dimensions) provided by the RP.

<table><thead><tr><th width="355">Description</th><th>Screen</th></tr></thead><tbody><tr><td>Session initialisation success</td><td><img src="https://372330916-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FXnljQgt54HuOtH3cKCRP%2Fuploads%2F4oG4eVvRtnDMqaWRYEM7%2Fimage.png?alt=media&#x26;token=3f64a5c5-bb7f-48c2-8248-922ab27e9ee5" alt=""></td></tr><tr><td>User scanned the QR code using SPM</td><td><img src="https://372330916-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FXnljQgt54HuOtH3cKCRP%2Fuploads%2FUEblKDIzNSFrrscSzcHY%2Fimage.png?alt=media&#x26;token=4493e3c5-7e9d-4e0a-a832-f835450add2d" alt="" data-size="original"></td></tr><tr><td>Session expired (Before QR code was scanned)</td><td><img src="https://372330916-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FXnljQgt54HuOtH3cKCRP%2Fuploads%2F2mjFVYkf8IEyGe3wC02F%2Fimage.png?alt=media&#x26;token=4014fc5b-914d-4ea0-9cb6-fc630e0c8347" alt="" data-size="original"></td></tr><tr><td>Session expired (After QR code was scanned)</td><td><img src="https://372330916-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FXnljQgt54HuOtH3cKCRP%2Fuploads%2FbTrsr4CQLbKdOtQcmSyD%2Fimage.png?alt=media&#x26;token=b0179de3-6971-47bd-8b79-5cab3de4712e" alt="" data-size="original"></td></tr><tr><td>Retryable error occurred <br><br>Users are only allowed to retry up to 1 time. This is to prevent excessive retries on the Singpass server because automated retries are already in place for such API calls.</td><td><img src="https://372330916-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FXnljQgt54HuOtH3cKCRP%2Fuploads%2FVuqGOeBgGQUxwjDLdWQ8%2Fimage.png?alt=media&#x26;token=d4e6760b-d19f-4d3f-9a34-fa2648882d63" alt="" data-size="original"></td></tr><tr><td><p>Unretryable error occurred<br></p><p>Examples of possible scenarios:</p><ul><li>Error occurred when invoking transactionParamsSupplier </li><li>Pre-flight checks have failed (ie. RP invoked .initTxnSigning() with invalid parameters) </li><li>Retries exhausted Malformed response from Singpass server, which cannot be recovered by retrying </li><li>Client side errors returned from Singpass server </li><li>In the situation where a corresponding erroneous HTTP status code is received, it will be displayed in brackets.</li></ul></td><td><img src="https://372330916-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FXnljQgt54HuOtH3cKCRP%2Fuploads%2FxturGTxLExqaBRVi7bog%2Fimage.png?alt=media&#x26;token=14743daa-b902-4e36-8684-dcd6867e0f8b" alt="" data-size="original"></td></tr><tr><td>Service unavailable. This screen will be displayed if transaction signing service is toggled off on Singpass.</td><td><img src="https://372330916-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FXnljQgt54HuOtH3cKCRP%2Fuploads%2FeA6NSttHrJcHDwvbjhl4%2Fimage.png?alt=media&#x26;token=4ad7db66-a69e-4134-8203-a921d6d0907c" alt="" data-size="original"></td></tr><tr><td><p>Browser unsupported.<br><br>This screen will be displayed if the end-user’s browser/user-agent is not supported by Singpass JS.</p><p><br>Singpass JS supports recent versions of major browsers, including but not limited to Chrome, Firefox, Edge, Safari, SamsungBrowser and IE 11.</p></td><td><img src="https://372330916-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FXnljQgt54HuOtH3cKCRP%2Fuploads%2F1u5vcT9BvriDlFcslYcU%2Fimage.png?alt=media&#x26;token=1332b498-6164-47ab-a1a9-288972f71c5f" alt="" data-size="original"></td></tr><tr><td>Transaction Cancelled. This screen will be displayed if RP invoked .cancelTxnSigningSession()</td><td><img src="https://372330916-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FXnljQgt54HuOtH3cKCRP%2Fuploads%2Fxfk7Ioyc6BCsykbW9MhP%2Fimage.png?alt=media&#x26;token=81cb2a47-1d43-4f9b-81dc-61a95e9baf7e" alt="" data-size="original"></td></tr></tbody></table>