Skip to main content

Embedded Model

Unified Consent supports cross-domain subject integration through the embedded model.

The embedded model allows to render either a custom experience or the built-in CUI consent manager in an iframe. Using an iframe, it is possible to share subject's consents and preferences across different domains.

NOTE: the current implementation only supports subject sharing across subdomains of the same top level domain. Support for different top level domains is planned for future releases.

Getting Started​

If you want to integrate an existing CUI page into your site, you need to add the following code snippet:

<body>
  <iframe id="embedded-cui" src="https://unifiedconsent.osano.com/{pageId}/welcome"></iframe> 
  <script type="text/javascript">
    const { UnifiedConsentByOsanoSDK } = window.unifiedConsentJsSdk
      
    UnifiedConsentByOsanoSDK.initEmbeddedParent({
      targetIframe: document.getElementById('embedded-cui')
    })
  </script>
</body>

This initialization code will connect your site with CUI. Your subjects will be able to set consents and preferences that will be shared across the domains that implement this code.

NOTE: the Osano Unified Consent SDK must be available in the global context. Please, check the documentation to learn the different ways to include the SDK in your site.

Architecture​

Embedded Rendering Figure 1. Rendering architecture diagram.

This diagram shows the overall architecture of the Unified Consent Embedded Model rendering process. The rendering process opens a connection between the parent window and the iframe (child window), and once ready it will initialize a channel to send and receive messages from both ends.

In the handshake process, the parent waits until the child is ready. Once UnifiedConsentByOsanoSDK.initEmbeddedParent() is called, the parent will send messages to the child until it responds back with the acknowledgment message. This happens when the child window invokes the UnifiedConsentByOsanoSDK.initEmbeddedChild() method. If the child window never calls the initialization method, the parent will throw an error after a configured timeout.

Once the handshake is confirmed in both ends, the parent sends a message to the child with the stored subject (if any), the sessionId query parameter (if any), and the domain. The child overrides its own subject if provided by the parent, and it uses the parent domain to make the validation. If the domain validation succeeded, the child will render CUI in the context of the parent's subject.

The last step in the rendering process is a message from the child to the parent providing the resolved subject, so the parent updates the cookie for the domain. It will ensure the parent will have the last resolved subject from the child.

Common Issues​

The iframe is not loading​

Misconfiguration​

Go back to the Configuration at the top of this page. Ensure the domain name matches the URL you see in the browser.

Content Security Policy​

The parent page's Content Security Policy can prevent the iframe from loading. Read more about CSP here, paying special attention to the attribute frame-src.

This is an example of a CSP that would prevent the iFrame from loading. Below that is a fix.

Content-Security-Policy: frame-src self

The following is the fix for the CSP:

Content-Security-Policy: frame-src self unifiedconsent.osano.com