Privacy Iframe

Adding embed codes directly to your website can be a security/privacy concern since they are provided by third parties and may include Javascript that can be used for tracking or other malicious purposes. Using a cross-origin iframe is the best way to prevent access to the parent window and protect your users' privacy.

Cross-Origin Iframe

Why Cross-Origin Iframe is the Best Method to Sandbox Content?

We have tested multiple methods to sandbox iframe content and found that using a cross-origin iframe is the best way (you can still other methods if you want):

  • Using srcdoc: Using iframe srcdoc for content provides a seperate about: origin for the iframe content, but multiple platforms (Reddit, X) do not support it correctly.
  • Using data URLs: Using data URLs for iframe content has the same problems as srcdoc. Many platforms do not support it.
  • Same-origin iframe: We could use a same-origin iframe with the sandbox attribute, but most embeds fail without the allow-same-origin attribute, which defeats the purpose of sandboxing.
  • Cross-origin iframe: Using a cross-origin iframe with the sandbox and allow-same-origin attributes is the best way to sandbox content. It gives the embed access to local storage, etc. but in a seperate context, so it cannot access the parent window's local storage or other sensitive information. All currently supported platforms in Hyvor Unfold are compatible with this method.

What is a Cross-Origin Iframe?

If your website is on example.org, you can use a subdomain, unfold.example.org, or another domain, example.net, for the iframe endpoint. This makes the iframe cross-origin by default. The content inside the iframe cannot access the parent window, and the parent window cannot access the content inside the iframe.

Docker Image

If you are using the Docker image, the iframe endpoint is already included. On your website, use iframes with src set to /iframe?url=my-url to embed content.

<iframe
    src="https://unfold.example.org/iframe?url=https://url-to-embed.com"
    sandbox="allow-scripts allow-same-origin allow-popups"
	allow="fullscreen;accelerometer;clipboard-write;encrypted-media;gyroscope;picture-in-picture;web-share;"
></iframe>

See the sandbox and allow attributes for more information.

PHP Library

If you are using the PHP Library, you have to set up an endpoint within your website for the iframe. Here is an example with Laravel, but you can use any PHP framework.

Route::get('/unfold-iframe', 'IframeController@getIframe');
use Hyvor\Unfold\Unfold;
use Hyvor\Unfold\Exceptions\UnfoldException;
use Hyvor\Unfold\Embed\Iframe\PrivacyIframe;
use Illuminate\Http\Request;

class IframeController
{

    public function getIframe(Request $request)
    {
        $url = $request->input('url');

        try {
            $data = Unfold::unfold($url, UnfoldMethod::EMBED);
        } catch (UnfoldException) {
            // handle the exception
        }

        return PrivacyIframe::wrap($data->embed);
    }

}

The PrivacyIframe::wrap method will wrap the embed code in a full HTML document with sensible defaults. It will also include the necessary Javascript for resizing the iframe based on the content.

You can then use the iframe in your website like this:

<iframe 
    src="/unfold-iframe?url=https://url-to-embed.com"
    sandbox="allow-scripts allow-modals allow-popups"
></iframe>

Resizing the iframe

Iframe resizing is a common problem when embedding content. The content inside the iframe may change its height based on user interactions. Since Javascript inside the iframe cannot access the parent window, we need to use a postMessage to communicate between the parent and child windows.

When you call the PrivacyIframe::wrap method, it will include child.js script that will send the height of the content to the parent window.

On your website, you have to include the parent.js script. This script will listen to the messages from the child window and resize the iframe accordingly.

<script src="/parent.js"></script>

Or, since the code is pretty small, feel free to copy it to your source code directly.

Sandbox and Cross-Origin

Cross-Origin Iframe

Our recommendation: Keep the unfold iframe endpoint on a separate subdomain (e.g. unfold.example.org) from your main website (e.g. example.org). This makes the iframe cross origin by default and prevents access to the parent window.

This is the minimal setup required for the iframe to work cross-domain:

sandbox="allow-scripts allow-same-origin allow-popups allow-presentation"
  • allow-scripts: Allows the content inside the iframe to execute scripts.
  • allow-same-origin: Gives access to local storage, etc. in a seperate context (it cannot access the parent window's local storage).
  • allow-popups: Allows the content to open popups.

Same-Origin Iframe

If your website (e.g. example.org) and the unfold iframe endpoint (e.g. example.org/unfold-iframe) are on the same domain, you can use the following sandbox attribute:

Allow Attribute

The allow attribute is used to enable certain features in the iframe. We recommend the following to make sure embeds, especially video players, work correctly:

allow="fullscreen;accelerometer;clipboard-write;encrypted-media;gyroscope;picture-in-picture;web-share;"