@orestbida/iframemanager

Demo | Features | Installation

![License: MIT](https://opensource.org/licenses/MIT)
!Size
![Stable version](https://github.com/orestbida/iframemanager/releases)

IframeMananger is a lightweight javascript plugin which helps you comply with GDPR by completely removing iframes initially and setting a notice relative to that service. Iframes are loaded only after consent.

_{The plugin was mainly developed to aid CookieConsent with iframe management.}

- Key features
- Installation
- Configuration options & API
- Configuration examples
- youtube
- dailymotion
- vimeo
- twitch
- google maps
- Usage with CookieConsent
- License

Features

- Lightweight
- Complies with GDPR
- Multilanguage support
- Automatic/custom thumbnail support *
- Allows to integrate any service which uses iframes
- Improves website performance:
- lazy-load thumbnails
- lazy-load iframes
- Can be integrated with any consent solution

Installation

1. #### Download the latest release or use via CDN/NPM:

``

bash

    https://cdn.jsdelivr.net/gh/orestbida/iframemanager@1.3.0/dist/iframemanager.js

    https://cdn.jsdelivr.net/gh/orestbida/iframemanager@1.3.0/dist/iframemanager.css



    using

npm

bash

    npm i @orestbida/iframemanager





2. #### Import script + stylesheet:





3. #### Configure and run:

    -

As external script

- Create a .js file (e.g.app.js) and import it in your html markup:`html ...`- Configure iframemanager insideapp.js:`javascript (function(){ const im = iframemanager(); // Example with youtube embed im.run({ currLang: 'en', services : { youtube : { embedUrl: 'https://www.youtube-nocookie.com/embed/{data-id}', thumbnailUrl: 'https://i3.ytimg.com/vi/{data-id}/hqdefault.jpg', iframe : { allow : 'accelerometer; encrypted-media; gyroscope; picture-in-picture; fullscreen;' }, languages : { en : { notice: 'This content is hosted by a third party. By showing the external content you accept the terms and conditions of youtube.com.', loadBtn: 'Load video', loadAllBtn: "Don't ask again" } } } } }); })();`

As inline script

`html ...`





4. #### Create a div with

data-service and data-id

 attributes:

html





Configuration options

All available options for  the

 element:

html

    data-service=""

    data-id=""

    data-params=""

    data-thumbnail=""

    data-autoscale

    data-ratio="">

data-service

 :      [String, Required] name of the service (must also be defined in the config. object)

-

data-id

 :           [String, Required] unique id of the resource (example: video id)

-

data-title

 :        [String] notice title

-

data-params

 :       [String] iframe query parameters

-

data-thumbnail

 :    [String] path to custom thumbnail

-

data-ratio

 :        [String] custom aspect ratio (Available values.)[v1.1.0]

-

data-autoscale

 :    specify for responsive iframe (fill parent width + scale proportionally)

-

data-widget

 :       ignore the default aspect ratio; specify when implementing a custom widget with explicit width and height (twitter, facebook, instagram ...)[v1.2.0]



$3

You can set any attribute by using the following syntax:

-

data-iframe- [String] note: replace

 with a valid attribute name. [v1.1.0]



Example:

html

    data-service="youtube"

    data-id="5b35haQV7tU"

    data-autoscale

    data-iframe-id="myYoutubeEmbed"

    data-iframe-loading="lazy"

    data-iframe-frameborder="0">










All available options for the config. object:

javascript

{

    currLang: 'en',     // current language of the notice (must also be defined in the "languages" object below)

    autoLang: false,    // if enabled => use current client's browser language

                        // instead of currLang [OPTIONAL]



    // callback fired when state changes (a new service is accepted/rejected)

    onChange: ({changedServices, eventSource}) => {

        // changedServices: string[]

        // eventSource.type: 'api' | 'click'

        // eventSource.service: string

        // eventSource.action: 'accept' | 'reject'

    },



    services : {

        myservice : {



            embedUrl: 'https://',



            // set valid url for automatic thumbnails   [OPTIONAL]

            thumbnailUrl: 'https://',



            // global iframe settings (apply to all iframes relative to current service) [OPTIONAL]

            iframe: {

                allow: 'fullscreen',           // iframe's allow attribute

                params: 'mute=1&start=21',     // iframe's url query parameters



                // function run for each iframe configured with current service

                onload: (dataId, setThumbnail) => {

                    console.log(

loaded iframe with data-id=${dataId}

);

                }

            },



            // cookie is set if the current service is accepted

            cookie: {

                name: 'cc_youtube',            // cookie name

                path: '/',                     // cookie path          [OPTIONAL]

                samesite: 'lax',               // cookie samesite      [OPTIONAL]

                domain: location.hostname      // cookie domain        [OPTIONAL]

            },



            languages: {

                en: {

                    notice: 'Html notice message',

                    loadBtn: 'Load video',          // Load only current iframe

                    loadAllBtn: "Don't ask again"   // Load all iframes configured with this service + set cookie

                }

            }

        },



        anotherservice: {

            // ...

        }

    }

}





Any other property specified inside the

iframe object, will be set directly to the iframe

 element as attribute.



Example: add

frameborder and style

 attributes:

javascript

{

    // ...



    services: {

        myservice: {

            // ...



            iframe: {

                // ...



                frameborder: '0',

                style: 'border: 4px solid red;'

            }

        }

    }

}





Note:

thumbnailUrl

 can be static string, dynamic string or a function:



-

static string

 : "https://path_to_image/image.png"

-

dynamic string

 : "https://myservice_embed_url/{data-id}"

-

function

javascript

    thumbnailUrl: (dataId, setThumbnail) => {

        // fetch thumbnail url here based on dataId of the current element ...

        let url = 'fetched_url';



        // pass obtained url to the setThumbnail function

        setThumbnail(url);

    }





Custom Widgets

Some services (e.g. twitter) have their own markup and API to generate the iframe.



Note: this is an example with twitter's widget. Each widget/service will have a slightly different implementation.



1. Place the markup inside a special

data-placeholder div. Remove any script

 tag that comes with the markup. Example:

html

            data-service="twitter"

        data-widget

        style="width: 300px; height: 501px"

    >



        

            Sunsets don't get much better than this one over @GrandTetonNPS. #nature #sunset pic.twitter.com/YuKy2rcjyU
— US Department of the Interior (@Interior) May 5, 2014





2. Create a new service and dynamically load and initialize the widget inside the

onAccept

 callback:

javascript

    im.run({

        services: {

            twitter: {

                onAccept: async (div, setIframe) => {

                    // Using cookieconsent v3

                    await CookieConsent.loadScript('https://platform.twitter.com/widgets.js');



                    // Make sure the "window.twttr" property exists

                    await im.childExists({childProperty: 'twttr'}) && await twttr.widgets.load(div);



                    // Make sure the "iframe" element exists

                    await im.childExists({parent: div}) && setIframe(div.querySelector('iframe'));

                },



                onReject: (iframe) => {

                    iframe && iframe.parentElement.remove();

                }

            }

        }

    })







It is highly recommended to set a fixed

width and height to the main data-service

 div, to avoid the (awful) content jump effect when the iframe is loaded.





Placeholder for non-js browsers

You can set a placeholder visible only if javascript is disabled via a special div:

html





Example:

html

    data-service="youtube"

    data-id="5b35haQV7tU"

    data-autoscale>



    

        I'm visible only if js is disabled





APIs

The plugin exposes the following methods:

-

.run()

.acceptService()

.rejectService()

.getState()

 [v1.2.0+]

-

.getConfig()

 [v1.2.0+]

-

.reset()

 [v1.3.0+]



Example usage:

javascript

// accept specific service only

im.acceptService('youtube');



// accept all services (for example if user has given full consent to cookies)

im.acceptService('all');



// reject specific service

im.rejectService('youtube');



// reject all services (for example when user opts out of cookies)

im.rejectService('all');



// get entire config object

const config = im.getConfig();



// get current state (enabled/disabled services)

const state = im.getState();



// state.services: Map

// state.acceptedServices: string[]



// soft reset, removes internal event listeners

im.reset();



// hard reset, same as above, but also resets each div to its original state (for react frameworks)

im.reset(true);





Both

acceptService and rejectService

 work the same way:

1. set/erase cookie

2. create/remove iframes



Configuration examples

-

Youtube

`javascript im.run({ currLang: 'en', services: { youtube: { embedUrl: 'https://www.youtube-nocookie.com/embed/{data-id}', thumbnailUrl: 'https://i3.ytimg.com/vi/{data-id}/hqdefault.jpg', iframe: { allow: 'accelerometer; encrypted-media; gyroscope; picture-in-picture; fullscreen;', }, languages: { en: { notice: 'This content is hosted by a third party. By showing the external content you accept the terms and conditions of youtube.com.', loadBtn: 'Load video', loadAllBtn: "Don't ask again" } } } } });`Example:`html

        data-service="youtube"

        data-id="5b35haQV7tU"

    >

Dailymotion

`javascript im.run({ currLang: 'en', services: { dailymotion: { embedUrl: 'https://www.dailymotion.com/embed/video/{data-id}', thumbnailUrl: async (dataId, setThumbnail) => { // Use dailymotion's API to fetch the thumbnail const url =https://api.dailymotion.com/video/${dataId}?fields=thumbnail_large_url; const response = await (await fetch(url)).json(); const thumbnailUlr = response?.thumbnail_large_url; thumbnailUlr && setThumbnail(thumbnailUlr); }, iframe: { allow: 'accelerometer; encrypted-media; gyroscope; picture-in-picture; fullscreen;', }, languages: { en: { notice: 'This content is hosted by a third party. By showing the external content you accept the terms and conditions of dailymotion.com.', loadBtn: 'Load video', loadAllBtn: "Don't ask again" } } } } });`

Vimeo

`javascript im.run({ currLang: 'en', services: { vimeo: { embedUrl: 'https://player.vimeo.com/video/{data-id}', iframe: { allow : 'fullscreen; picture-in-picture, allowfullscreen;', }, thumbnailUrl: async (dataId, setThumbnail) => { const url =https://vimeo.com/api/v2/video/${dataId}.json; const response = await (await fetch(url)).json(); const thumbnailUrl = response[0]?.thumbnail_large; thumbnailUrl && setThumbnail(thumbnailUrl); }, languages: { en: { notice: 'This content is hosted by a third party. By showing the external content you accept the terms and conditions of vimeo.com.', loadBtn: 'Load video', loadAllBtn: "Don't ask again" } } } } });`

Twitch

`javascript im.run({ currLang: 'en', services: { twitch: { embedUrl:https://player.twitch.tv/?{data-id}&parent=${location.hostname}, iframe: { allow: 'accelerometer; encrypted-media; gyroscope; picture-in-picture; fullscreen;', }, languages: { en: { notice: 'This content is hosted by a third party. By showing the external content you accept the terms and conditions of twitch.com.', loadBtn: 'Load stream', loadAllBtn: "Don't ask again" } } } } });`

Google Maps

    



    -

With API key

`javascript im.run({ currLang: 'en', services: { googlemaps: { embedUrl: 'https://www.google.com/maps/embed/v1/place?key=API_KEY&q={data-id}', iframe: { allow: 'picture-in-picture; fullscreen;' }, languages: { en: { notice: 'This content is hosted by a third party. By showing the external content you accept the terms and conditions of Google Maps.', loadBtn: 'Load map', loadAllBtn: "Don't ask again" } } } } });`Example:`html

            data-service="GoogleMaps"

            data-id="Space+Needle,Seattle+WA"

            data-autoscale

        >

Without API key

`javascript im.run({ currLang: 'en', services : { googlemaps : { embedUrl: 'https://www.google.com/maps/embed?pb={data-id}', iframe: { allow : 'picture-in-picture; fullscreen;' }, languages : { en : { notice: 'This content is hosted by a third party. By showing the external content you accept the terms and conditions of Google Maps.', loadBtn: 'Load map', loadAllBtn: "Don't ask again" } } } } });`Example usage:`html

            data-service="googlemaps"

            data-id="!1m18!1m12!1m3!1d2659.4482749804133!2d11.644969316034478!3d48.19798087922823!2m3!1f0!2f0!3f0!3m2!1i1024!2i768!4f13.1!3m3!1m2!1s0x479e7499e2d4c67f%3A0x32f7f02c5e77043a!2sM%C3%BCnchner+Str.+123%2C+85774+Unterf%C3%B6hring%2C+Germany!5e0!3m2!1sen!2sin!4v1565347252768!5m2!1sen!2sin"

            data-autoscale

        >





Usage with CookieConsent [v1.2.0+]

You can use the

onChange callback to detect when an iframe is loaded by the loadAllBtn

 button click event and notify CookieConsent to also update its state.



Example:

javascript

im.run({

    currLang: 'en',



    onChange: ({changedServices, eventSource}) => {



        if(eventSource.type === 'click') {

            // Retrieve all accepted services:

            // const allAcceptedServices = im.getState().acceptedServices;



            /**

             * Retrieve array of already accepted services

             * and add the new service

             */

            const servicesToAccept = [

                ...CookieConsent.getUserPreferences().acceptedServices['analytics'], //cookieconsent v3

                ...changedServices

            ];



            CookieConsent.acceptService(servicesToAccept, 'analytics');

        }

    },



    services: {

        // ...

    }

});





Note: the above example assumes that all services belong to the

analytics

 category.



$3



Horizontal aspect ratio:



*

1:1, 2:1, 3:2, 5:2, 4:3, 16:9, 16:10, 20:9, 21:9





Vertical aspect ratio:

*

9:16, 9:20`

License

Distributed under the MIT License. See LICENSE for more information.

#### Note
Not all services (example: twitch) allow automatic/easy thumbnail fetch.

@orestbida/iframemanager

Table of Contents

Features

Installation

Configuration options

$3

Custom Widgets

Placeholder for non-js browsers

APIs

Configuration examples

Usage with CookieConsent [v1.2.0+]

$3

License