Troubleshooting Embed and Iframe Issues in Empath
This article explains why embedded content may not load in Empath and how iframe restrictions, frame blockers, and permission settings affect external website embedding. It includes troubleshooting steps, testing methods, and alternative approaches when embedding is not possible.
Summary
When you embed external content into an Empath text document using the embed button or iframe tool, you are placing another website inside a small window on the page. Because this process depends on how the external site is configured, certain pages may fail to load, display errors, or remain blank. This KB explains why iframes sometimes fail, how frame blockers work, and what options you have when embedding is not supported. This article does not cover embedding video content.
Understanding How Embeds Work in Empath
When you use the embed tool, Empath inserts an iframe into your lesson.
Key concepts:
-
An iframe is an HTML “window” that displays another webpage inside Empath.
-
Empath does not modify or override the external site.
-
If the external site blocks iframes, Empath cannot force it to load.
-
Your success depends entirely on the security and configuration settings of the website you are embedding.
Scenario 1: The Website Uses a Frame Blocker
A frame blocker prevents a webpage from rendering inside another website.
Common symptoms:
-
The embed area stays blank
-
The embed returns an error page
-
The content appears for a moment and then disappears
Why this happens:
-
The external site includes JavaScript or header rules that explicitly say “do not allow iframe embedding.”
Important notes:
-
There is no workaround inside Empath.
-
Only the owner of the external website can remove the blocker.
-
If you cannot modify the external site’s HTML or policies, the embed will not work.
Scenario 2: Secure Platforms Blocking Embeds by Default
Documentation platforms often block embedding unless permissions are changed.
Common examples:
-
IT Glue
-
Hudu
-
SharePoint
-
Vendor knowledge bases containing PII or internal documentation
Why this happens:
-
These platforms default to restrictive framing policies for security reasons.
Possible solutions:
-
Change the document or page permissions to allow public viewing.
-
Adjust access policies so the site can be displayed inside an iframe.
-
Some platforms allow “public but requires login” while still allowing an embed, but this varies.
What you need to know:
-
If you cannot change the permissions, embedding will not work.
-
This is controlled entirely by the external system, not Empath.
Scenario 3: Testing Whether a Site Can Be Embedded
Use an iframe testing tool before trying to embed in Empath.
How to test:
-
Visit https://iframetester.com
-
Paste the URL you want to embed
-
If it fails there, it will fail in Empath
What this test reveals:
-
Whether the website allows iframe embedding
-
Whether a frame blocker is active
-
Whether your intended configuration is possible
Scenario 4: Embedding Cannot Be Used — What to Do Instead
If embedding is not possible due to security or platform limitations, you still have effective options.
Alternatives:
-
Copy and paste the documentation directly into Empath
-
Link out to the original website inside the lesson
-
Use knowledge checks to validate that external training was completed
Why these alternatives work:
-
They avoid iframe restrictions
-
They still centralize the training experience inside Empath
-
They allow you to track and verify completion even when vendors block embedding
Looking Ahead: API-Based Integrations
As Empath develops API integrations, embedding will become less necessary and more platform-to-platform connections will be supported directly. This will provide a more reliable way to bring external content into Empath without relying on iframes.