Integrating your white label with iframes

The easiest way to integrate our stats into your own web site is to use iframes.

You can choose between using the private link for read-only access to a single site, or a proper login. No matter which method you choose, you will need to have stored on your end either the site_id/sitekey (for private link) or username/password (for full login).

Third party cookies must be enabled in a customer's browser for the iframe method to work.


Option 1: Private link

Every site has its own unique private link, and it's available on the main site preferences page. All you need to do is create an iframe element and set its "src" to the private link URL.

<iframe src='http://stats.yoursite.com/?site_id=123&sitekey=456'></iframe>

Pros

- Simple as pie
- No need to create user accounts for your customers

Cons

- Read-only access means they can't do things like set up goals or change their time zone, and if they try, they'll be presented with a login screen.
- Access may time out due to inactivity.

Option 2: Login

If you wish to have a customer logged in to an account, which will grant them full access over their site, you'll need to point the frame to our login page and include the username and password as parameters.

<iframe src='http://stats.yoursite.com/user/login?username=XXX&password=YYY&remember=1&site_id=1'></iframe>

This will automatically log them in, and by using the 'remember' parameter, they will stay logged in even if their session expires. This is important as otherwise it breaks the user experience if they're randomly presented with a login page if they haven't clicked anything for 30 minutes - and they may not know their username/password if you created the account for them.

The site_id parameter is optional but we recommend using at shown above, "site_id=1" - "1" being a special value which just means "redirect to the first site in their account". You can also specify a real site_id in their account if you have that stored but that requires more upkeep on your end. If you leave off the site_id parameter, they will instead be redirected to their user homepage.

Pros

- Access won't timeout as long as you set the 'remember=1' parameter.
- Customer has full control over site settings such as goals and time zone.
- Customer will never see an errant login screen when they don't have the rights to do something.

Cons

- Customers having full control means they might completely break their site.


Auto-sizing your iframe

The downside of iframes is that you have to specify the height and width manually. We recommend width=100% and height=2500px as the default.

However we also offer a way to dynamically resize the height of the iframe as the child document changes sizes (e.g. as they move between pages). When we detect our site inside an iframe, we automatically run code that posts a message to the parent document with the child document's height. You can listen for this with the code below, which works on all modern browsers.

A full example of the javascript and iframe is below, including all parameters we recommend setting for the iframe. You'll need to assign an ID to your iframe, which we have highlighted in red. You can choose your own value for the ID but it must be the same in both places.

Feel free to copy this code verbatim, and just "fill in the blank" for the iframe src URL, whether you choose private link or full login mode.

<!-- code to listen for messages from the iframe -->
<script>
if( window.addEventListener ) {
    addEventListener( 'message', function(e) {
        document.getElementById('stats-iframe').height = e.data + 'px';
    });
}
</script>

<!-- iframe code -->
<iframe id=stats-iframe width=100% height=2500px scrolling=no style='border:0' src='_______________'></iframe>

Pro-tip: We add a class, "iframe", to the body element when we detect the site is in an iframe - in case you want to do something fancy with CSS. This is particularly useful if some customers access your white label via iframe and others access directly.


Demo

There's an iframe below using a private link and auto-sizing. View the source of this page to see the HTML used.