The Web-client is versatile and can be integrated and used in many different ways by the merchant application. This is different from the other BankID Clients.
The question of supported browsing contexts for the Web-client must be split in three:

1. The browsing context of the merchant application (also containing the Helper)
2. The browsing context of the Web-client itself
3. The browsing context of a signing-document displayed outside the browsing context of the Client

Regarding (1) the most common use case is a window or tab in a standard browser. BankID Web-client is however also designed to also work with WebViews in native apps. This includes iOS, Android and Win8. Other browsing contexts like widgets, specialized browser, etc. should also work as long as they support the web features required by the Web-client.
A parameter called frameMode (in the set of helperParams Set in initHelper.) governs the browsing context of the Web-client itself (2). Three different options are supported:

• iframe This is already supported in BankID 2.0. The Web-client is loaded in an iframe inside a browsing context that the merchant application sets up, normally an iframe embedded directly in the current page of the merchant application.
• window Support is introduced with BankID 2.1. The Web-client is loaded in a separate browser tab or window (depending on how the browser is configured).
• redirect Support is introduced with BankID 2.1. The browsing context is redirected to a centrally hosted BankID-branded landing page to load the client. Upon completion, the browser is redirected to a page determined by the merchant application.

Figure 1 – The three frameModes available in BankID 2.1 Web-client.
A parameter called docDisplayMode (in the set of clientParams Set in initSession.) governs the browsing context for display of (all) documents to be signed. Three options are supported:

• interior The document to be signed is displayed inside the visual boundary of the browsing context. Already supported in BankID 2.0.
• overlay Introduced with BankID 2.1. The document to be signed is displayed over the Web-client, making use of all available space. This value is suitable for small-screen devices.
• window Introduced wit BankID 2.1. The document to be signed is displayed in a separate reader window. Note that all signing controllers remain within the initial Web-client window, whereas the new window is only concerned with the document presentation itself. This value is suited for large screen windowing devices.

Figure 2 - Possible combinations of frameMode and docDisplayMode.

 

Recommended combinations

 

The table below shows recommendations for combinations of frameMode and docDisplayMode in regard to document size and type. 

 

• Green – recommended
• Yellow – consider other combination
• Red – not recommended

 

Note that any combination of frameMode and docDisplayMode will be the same for all documents to be signed in a multi document signing action. 

 

 

 

 

Browsing contexts – Caveat lector

 

The merchant should be aware that some parameters and parameter combinations must be used with caution in order to avoid potential problems and confusing user experience. These are discussed below.

 

frameMode = window

 

• This parameter value does not work with Internet Explorer (due to XDM-restrictions).
• This parameter value does not work from WebViews (applies to iOS, Android and Windows Phone).
• This parameter value may be in conflict with pop-up blockers. In order to avoid conflicts with pop-up blockers the Web-client should be initialized in response to a user interaction. Typically this can be achieved by allowing the user to click a button which will then execute the initHelper-method.

 

• Unless explicitly set the default size of a new window is 500px by 350px.

 

frameMode = redirect

 

• The externalPageDNA feature is only used on the landing page – not on the merchant's page.
• Tests have shown that using Internet Explorer with frameMode = redirect does not work when IE's Trusted sites security levels are set to High. If Trusted sites security levels are set to Low IE displays a question to the user whether she wants to accept the redirect and then the redirect takes place.

 

docDisplayMode = window

 

• This parameter does not work from WebViews (applies to iOS, Android and Windows Phone).
• When using this parameter value, the user may accidentally "hide" the new window, by activating some other window on his or her computer. The Web-client will inform the user that a second window is open, and provide a button to bring the new window to front.
• This parameter value may be in conflict with pop-up blockers.

 

frameMode = window & docDisplayMode = window

 

The combination of these two values will cause two separate windows to appear on top of the merchant application, and should be avoided.