...
Should that not be the case however, a JavaScript-framework is also provided to allow for further customisation. It allows you to start a BankID session in the same manner as the HTML-version, but simply provides a URL to the helper script instead so that you may make your own version of Test your BankID. The framework is used by the HTML-version itself to assure the same experience across merchant sites except for any parameters you may provide.
HTML-version
...
The HTML-version of the tool is available at tools.bankid.no and merchants may embed this page as part of their web site through the use of an iframe or by linking directly to it.
...
Below is an overview of all the URL-parameters:
Parameter | Explanation | Default | Example |
---|---|---|---|
locale | Specifies the language to be used throughout the tool and the BankID Web-client. Currently, only Norwegian bokmål (nb) and English (en) are supported. | Norwegian bokmål (nb) | https://tools.bankid.no/bankid-test?locale=nb |
width | Specifies the width to be used in the BankID Web-client, in pixels. Minimum is 320 pixels. | None (Full width adjusted to the parent container.) | https://tools.bankid.no/bankid-test?width=640 |
height | Specifies the height to be used in the BankID Web-client, in pixels. Minimum is 200 pixels. | None (Full height adjusted to the parent container.) | https://tools.bankid.no/bankid-test?height=480 |
docDisplayMode | Determines the user-experience for document signing. Options:
| interior | https://tools.bankid.no/bankid-test?docDisplayMode=interior |
merchantFEAncestors | A space separated list of ancestor domains where any iframes other than the iframe in merchantFEDomain itself, will be listed. | None | https://tools.bankid.no/bankid-test?merchantFEAncestors=http://www.bankid.no |
JavaScript-API (bid-client-test.js
...
)
The framework comes in the form of bid-client-test.js which exposes an API for Test your BankID through the bidClientTest-object. This section describes how this can be used for programmatically starting a BankID session so that you may implement your own version of the tool.
...
Below is an overview of the possible parameters to the init-methods:
Parameter | Explanation |
---|---|
success | Callback that is called once a BankID-session has been successfully established and a helper script is ready to be used. |
error | Callback that is called if a BankID-session could not be established or if the user's browser is blacklisted. |
errorURL | The errorURL-parameter is mostly a technicality required as a fallback redirect in case something went wrong during the whole authentication process, including after the BankID Web-client has been started. |
frontEndDomain | The frontEndDomain-parameter must be set to the domain of the merchant web site (you) as seen in the address bar of the browser. This is used to secure cross-document messaging (XDM) between the BankID Web-client and the helper script. Note that loop-back addresses such as localhost or 127.0.0.1 are not allowed, although the domain need not be visible over the Internet. Example: https://example.com |
docType | Either pdf, txt, or xml. Lets you specify which type of example document that should be used in case initSign was called. The documents presented are simple dummy documents with little text. |
frameMode | Determines the BankID client location. Options:
|
docDisplayMode | Determines the user-experience for document signing. Options:
|
merchantFEAncestors | A space separated list of ancestor domains where any iframes other than the iframe in merchantFEDomain itself, will be listed. |
Below is an overview of the startupObject given to the success-callback:
Field | Explanation |
---|---|
helperURL | After a BankID-session has been established, a helper script for loading a unique instance of the BankID Web-client has been prepared by the BankID COI. The startupObject returned from the init-methods contains the URL to this helper script, which may in turn be loaded by the browser and used to start the BankID Web-client (see example below). |
clientID | The unique client ID associated with the BankID Web-client. Must be passed to the init-method of the helper script. |
Once the helper URL has been retrieved, it can be injected into the DOM-tree using a script-tag. Once done loading, the global variable bankidhelper may be used to initialise the BankID Web-client and start the authentication or signing process.
...
Below is an overview of the response object given to the error-callback:
Field | Explanation |
---|---|
status | The status code of the error, which has only two possible outcomes: 1 indicates an unexpected error such as server failure. 2 indicates that the user's browser is blacklisted for use with the BankID Web-client. |
statusText | A descriptive hint as to what went wrong. |
Example:
function startupError(response) { if (response.status === 2) { alert("Your browser is blocked for use with the BankID Web-client. Please upgrade your browser."); } else { alert("Something went wrong: " + response.statusText); } }
...