Skip to main content

         This documentation site is for previous versions. Visit our new documentation site for current releases.      

Troubleshooting web embeds

Updated on June 30, 2022
Applicable to Cosmos React applications

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.


When you deploy the web embed on a host page, the web embed formatting includes the styles of the host page (style bleed-through).


  • 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.


After a five second delay, a pop-up window appears and then quickly disappears before the web embed content is displayed.


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.


  • 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, and navigate-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 or DENY. 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.

Have a question? Get answers now.

Visit the Support Center to ask questions, engage in discussions, share ideas, and help others.

Did you find this content helpful?

Want to help us improve this content?

We'd prefer it if you saw us at our best. is not optimized for Internet Explorer. For the optimal experience, please use:

Close Deprecation Notice
Contact us