Troubleshooting web embeds
Ensure that your web embeds work as intended by learning about potential issues and their resolutions.
Web embed displays host page formatting
Including a web embed in a host page may produce formatting issues. To solve the problem, adjust the HTML markup of your host page.
Condition
When you deploy the web embed on a host page, the web embed formatting includes the styles of the host page (style bleed-through).
Remedy
- Wrap the
<pega-embed>
element in a<div>
. - Apply styles directly to the
<pega-embed>
element or the<div>
element that hosts the embed.
Pop-up window flashes in the web embed after a lengthy delay
Web embeds might encounter issues with pop-up windows during authentication.
Condition
After a five second delay, a pop-up window appears and then quickly disappears before the web embed content is displayed.
Cause
The web embed uses a pop-up window to invoke the authorization endpoint to avoid disrupting the content on the host page. When the authentication service is other than Pega, the system assumes the external authentication service uses single sign-on. This means that in most scenarios, the application might not require a login screen. The application first tries to invoke the authorization endpoint by using a hidden iframe. If the authentication succeeds, the pop-up window does not appear.
However, in some cases, the server configuration interferes with the attempt to
authenticate in the hidden iframe. If the authentication does not complete
successfully in five seconds (the initial delay set in the
silentTimeout
attribute) the web embed opens an
authorization endpoint in a visible window. If the user does not have a valid
SSO authentication context, a login screen might appear in the pop-up window for
the user to re-authenticate. If the user has already authenticated in some other
context, no login is required, the authorization code is returned immediately,
and the window closes.
Remedy
- In Chromium-based browsers, ensure that in the Cross-site
Request Forgery system setting, in the Cookie
settings section, the Enable samesite
cookie attribute is checked, and the Sometime
options drop-down list is set to
None.For more information, see Mozilla developer guidance.
- Verify if the Content-Security-Policy header returned by one of the
redirect responses is not stopping the authorization from completing in
the hidden iframe. Values to consider are:
script-src
,frame-src
,sandbox
,frame-ancestors
, andnavigate-to
. - If the redirect sequence to the identity provider is very slow, then increasing the timeout interval might prevent the pop-up window from appearing.
- If the authentication fails in the hidden iframe, ensure that the
server that authorizes the endpoint is not configured to return the
X-Frame-Options header with a response of
SAMEORIGIN
orDENY
. If you fix this configuration, the authentication redirects in the hidden iframe should succeed. Consequently, the pop-up window does not appear.For more information, see Mozilla developer guidance. - Set the
silentTimeout
attribute in the web embed to 0 to prevent the system from attempting the silent authentication in the hidden iframe. This saves authorization time by decreasing the amount of time the application waits before launching a visible pop-up window and re-attempting authentication.
Previous topic Events in web embed Next topic Authentication in web embed