Privacy Iframe

Adding embed codes directly to your website is a privacy concern since they may include Javascript that can be used for tracking. Using an iframe to wrap the embed code is the best way to prevent this.

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;"