A solution to customize Piwik's OptOut-iframe



I was not glad about the situation that you can’t format the content of the OptOut-iframe and let it look like the rest of your site. So I decided to solve the problem by myself. I guess I found a practical way to integrate the iframe into the individual layout of the calling page. I just changed the template for the OptOut-iframe a little bit and wrote an additional file (customize.js), which I put in the same folder as the template.

Changed file: "plugins/CoreAdminHome/templates/optOut.tpl“
New file: "plugins/CoreAdminHome/templates/customize.js“

The main idea was to add another parameter to the iframe-source-attribute with individual data for the style of the embedded iframe. And – you won’t believe it – I’ve decided to name that parameter „style“. The value of the new parameter should be a JSON-object which keys are a list of selectors (use jQuery-selectors) and their values are further JSON-objectes with the style-informations.

For example:

  "p": {"color":"black", "font-size":"12px"},
  "body": {"margin":"0px", "padding":"0px"}

Of course the value for the parameter „style“ has to be url-encoded. If you use a script-language like PHP, it is very comfortable. Here is an example for the iframe-tag using PHP:

<iframe ...
  src = "http://your-piwik-domain.org/index.php?
  style=<?php echo urlencode('{
    "p": {"color":"black", "font-size":"12px"},
    "body": {"margin":"0px", "padding":"0px"}
  }'); ?>

The changes of the OptOut-template are references to jQuery and the new file „customize.js“. I also add some logical HTML-markups for an easier way to select elements of the iframe (and to improve the accessibility).

The script of my additional embedded JS-file waits until the whole content of the iframe is loaded. Then it reads the style-information from the new parameter and starts to customize the styling of the iframe-elements by using the jQuery-CSS-function from within the iframe. So there should not occur any problems with the Same-Origin-Policy.


As far as I can see my solution has no security problems for Piwik or for the users because the transmitted data from the individual site has to be valid JSON and is interpreted by the css()-function of jQuery. And without active JS or without setting the parameter “style” on the calling page nothing happens and all looks and acts just like before.

If you like my solution, feel free to download the files from my homepage and copy them to your own Piwik-installation. On my homepage you can find a description in German as well.

And if you people at Piwik like my idea just as I do, it’s up to you to integrate the two files into Piwik (Of cause I set my new added file just like PIWIK under the GPL v. 3).

Here you can find the German description and the needed files packed in one zip-file:

Comments are willcome.


(Matthieu Aubry) #2

Nice idea! I posted a link to this post from Allow to customize some CSS of optOut widget · Issue #1929 · matomo-org/matomo · GitHub

I am not 100% sure that Jquery css() is safe from user submitted styles/XSS so I’d need to check before applying.


I am not sure if the css()-function is protected against xss. But I’ve tried some attacks discriped on the OWASP-site and nothing happened.

Especially look here:

and try this for all browsers

background-url : 'javascript:alert(1)' 

and this for IE

text-size: 'expression(alert(1))'

Otherwise it would be possible to use whitelist-characters for the key/value paires or to use this OWASP-jquery-plugin (but it’s pretty big)


Script Version 2.0


I have written a security-update for my customization-script. Now it canonicals all data from the style-parameter to protect the script against unfriendly double-encodings (which probably intents to bypass the security controls). After that it checks all data with character-white-lists. Matched unallowed characters in the jQuery-selector and the css-names stops the customization. Unexpected characters in the css-values will be encoded.
These should protect the script against xss-attacks.

The script requires the jquery-encoder by the OWASP Foundation and Class by John Resig. Both are bundled in the downloadable zip-file and integrated in the new minimized version of customize.js.

You can still get the script at the same address:

Update informations are bundled in the zip-file as well.

(Matthieu Aubry) #5

please consider using this plugin that was released on the Marketplace! http://plugins.piwik.org/CustomOptOut