Pixlee

The Pixlee Developer Hub

Welcome to the Pixlee developer hub. You'll find comprehensive guides and documentation to help you start working with Pixlee as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    API Reference

Pixlee Widget User Guide

Pixlee Widgets are JavaScript widgets that, when added to your web page, create an iFrame experience hosted entirely by Pixlee that seamlessly blends into your site.

How it works

Pixlee Widgets are a hybrid mix of first and third party clients that communicate with each other to provide the full closed-loop Pixlee value of content serving and performance analytics tracking. They are asynchronous and do not block loading of the page.

All Pixlee Widgets come with a lightbox and uploader experience out of the box. The lightbox is a modal ‘window’ that acts as a detail view for a photo or video. When a photo or video is clicked on, the lightbox is activated and appears on-screen, presenting a larger version of the photo or video to the user, along with secondary information such as the submitter, the caption, and associated photos/links. The uploader is a modal ‘window’ that allows users to submit photos, either by logging in and choosing from their pre-existing content from social, or by adding a photo directly.

You can have multiple Pixlee Widgets on a page; they are intelligent and share the same lightbox and uploader (if enabled) automatically. See our In Depth Implementation documentation for details.

Pixlee Widgets can be loaded by an addition of a script tag generated via the Pixlee Publishing Center (most common use-case), using a module loader (e.g. requireJS) or through use of third party tag managers (e.g. Google Tag Manager or Tealium).

We highly recommend using our Publish Center, which lets you do full style customization of your widget with a very powerful WYSIWYG editor that has an expert CSS mode as well.

If you are using the Publish Center to generate code snippets for publishing, you can stop here.

Widget Performance Guide

The Pixlee widget architecture has been optimized for two principal tenets:

  1. Being performant, especially in the cached state (when it is live and people are constantly visiting the page). We use aggressive CDN caching and image compression/optimization (https://www.fastly.com/products/web-and-mobile-performance/image-optimization) and also cache heavily on the API level.
  2. Having no impact on the load of the rest of the page.

We do the latter by having our javascript deliberately run as late as possible; that is, when the rest of your site code, HTML/JS/CSS has already loaded. This ensures that the rest of your page loads visually at the same time, at the cost of our widget displaying possibly slightly later.

Generally the tests that test page speed will penalize this, but visually speaking it has little effect. As such, our optimization decisions are based on real customer experience as opposed to a browser test.

Priority loading widgets is an option that is available, in which we load our widgets in sync with the rest of the page. This should be chosen if the widget load order is an important optimization.

Please refer to our blogposts on widget and site performance for supplementary information:

On Modern Widget Architectures

Optimizing Site Page Load Speed

Additional optimizations of interest:

  • Content is cached at different image sizes, such that the smallest appropriate file size for each device/browser is loaded.

Limitations

This document is intended to provide an in-depth expalanation of how our hosted widgets work and how to implement them. It does not cover our REST APIs. Please note our APIs and documentation available at:

Pixlee Content API

Pixlee Analytics API

In Depth Implementation

Widgets act as a "window" on your page whose content and form can be dynamically edited through the use of the Publish Center in the Pixlee Control Panel.
Any changes made within the Publish Center will be reflected on the page where the widget with the corresponding widgetId resides.

All widgets require a public API key and widget id. Additionally, product widgets require a SKU parameter which may either be
hard-coded into the script tag or dynamically assigned if on a product or category page. Additional optional parameters include:

  • lightbox: boolean to determine whether clicking on photos should open the lightbox. true by default
  • containerId: string to determine the id of the target container in the DOM where the gallery will reside. pixlee_container by default
  • subscribedEvents: array of strings to determine which events you want the widget to emit, see Subscribing to Widget Events for details
  • fixedWidth: boolean to determine whether the gallery should maintain a fixed width or resize to fit its parent. true by default
  • ecomm_platform: string used for automatic product sku detection. currently supports shopify and bigcommerce

Script Tag

The most common implementation of our widgets involves placing a small snippet of embed code on your website. The initialization snippet consists of 3 parts:

1) A target container for the widget to reside in (we provide a div with the id pixlee_container by default
2) An initialization function called PixleeAsyncInit which will run once our library has loaded. This snippet will run once the Pixlee
object exists on the window, and will authenticate using the API key as well as add the widget to the target container using the corresponding add function
3) A reference to our library's code. This is only to be called once, after the rest of your initialization code.

Note: In all the following examples we use addSimpleWidget to create a regular image gallery. This is the most common use case, though the following are also available:

  • addProductWidget - for use on product pages, takes an additional skuId parameter
  • addCategoryWidget - for use on category pages, takes an additional categoryId parameter
  • addSingleWidget - for publishing single photo galleries

Example Widget Code Snippet:

    <div id="pixlee_container"></div>
    <script type="text/javascript">
        window.PixleeAsyncInit = function() {
            Pixlee.init({
                apiKey: '<redacted>'
            });
            Pixlee.addSimpleWidget({
                widgetId: 2652
            });
        };
    </script>
    <script  src="https://assets.pixlee.com/assets/pixlee_widget_1_0_0.js "></script>

Example Multiple Widget Snippet:

    <div id="pix1"></div>
    <div id="pix2"></div>
    <script type="text/javascript">
        window.PixleeAsyncInit = function() {
            Pixlee.init({apiKey:'<redacted>'});

            Pixlee.addSimpleWidget({
                widgetId:203678,
                containerId:"pix1"
            });

            Pixlee.addSimpleWidget({
                widgetId:203679,
                containerId:"pix2"
            });
        };
    </script>
    <script src="//assets.pixlee.com/assets/pixlee_widget_1_0_0.js"></script>

The important things to note here are:

  • Pixlee.init is called once
  • All widget declarations are contained within the window.PixleeAsyncInit function declaration
  • pixlee_widget.js script is added last

This order is important.

Example Uploader Only Snippet:

<a id="pixlee_uploader_button" style="display:inline-block;text-transform:uppercase;margin-bottom:20px;padding:15px 50px;background:#323a45;color:white;border-radius:3px;cursor:pointer;font-family:helvetica neue, helvetica;">upload now</a>

<script type="text/javascript">
    document.getElementById("pixlee_uploader_button").addEventListener("click", function() {
        Pixlee.openUploader({
            widgetId:203578
        })
    }, !1);
</script>
<script src="//assets.pixlee.com/assets/pixlee_widget_1_0_0.js"></script>

Single Page Applications

Our embed code is meant for a simple copy and paste into basic sites with minimal dev resources, but we have many resources for more complex single page sites. Below is a breakdown of what each piece of the embed code does, to better equip developers with useful Pixlee functions:

<div id="pixlee_container"></div> //1

<script type="text/javascript">
     window.PixleeAsyncInit = function() { //2
       Pixlee.init({apiKey:'SnOYjJTeEFnQtLvpn9bI'}); //3
       Pixlee.addSimpleWidget({widgetId:893283}); //4
     };
</script>
<script src="//assets.pixlee.com/assets/pixlee_widget_1_0_0.js"></script> //5

(1) This is the target container which the widget will render into. You can put this anywhere on your page and the only requirement is that it exists before you call Pixlee.addSimpleWidget(...); You may optionally use a different id, just pass the option containerId: <string id> into the addSimpleWidget call with the id so this widget knows where to render. This is useful for rendering multiple widgets on the same page

(2) This stores our initialization code in a function called PixleeAsyncInit, which our library will delay until all of your assets have loaded to allow for asynchronous loading. When splitting up our embed code for single page apps this can generally be skipped

(3) This initializes our front end library and its functions with your unique apiKey. This should only be run once per load so for a single page app like yours, run this when your page first renders and never call it again to expose all of our other functions

(4) This renders a widget with the id widgetId into containerId (which by default is pixlee_container). Treat this as a "show" function for single page apps

(5) This is our library, and should only be included once and ideally at the bottom of the page (though we have internal code in place to make sure multiple instances won't cause errors)
With the above in mind, the easiest way to alter our embed code for a single page app is to:

  • Load our library and run the initialization function once when you first load the page
  • Run Pixlee.addSimpleWidget(...) when you want to show the widget (for example, when you hit a page where the widget exists)
  • Run Pixlee.resizeWidget() immediately after any addSimpleWidget call to ensure the iframe resizes properly with respect to the content around it
  • Run Pixlee.close(true) when you want to hide the widget (for example when you leave a page where the widget exists). This will clean up the instance, and the optional true parameter indicates that this is a single page app so that our event binding reacts accordingly. Note this will close all currently displayed widgets.

A typical implementation might look something like this:

https://codepen.io/pabs123/pen/YYmjgR

Notice how we initialize everything at start, and then simply use the add and close calls to work with the rendering.

One final helpful tool is the Pixlee.resizeWidget() function which forces our smart iframe resizing function to run. This can be useful with dynamically created html which may cause our widget to become cut off or have a double scrollbar, simply run the above once the page is loaded.

Module Loaders

Pixlee's widgets fully support the Asynchronous Module Definition (AMD) pattern. Using a module loader
like requireJS, you can import our library into your webpage along with any other dependencies you may
have. This is a simple three step process:

(1) Add path to config

First define a path to our script in the module loader's config as follows:

require.config({
    paths: {
        "pixlee":"https://assets.pixlee.com/assets/pixlee_widget_1_0_0"
    }
});

(2) Set an HTML target

Add the following div tag in your HTML where you would like the widget to appear:

<div id="pixlee_container"></div>

(3) Load module

Load the module into your file after any other dependencies you may have, inserting the appropriate
apiKey and widgetId. Both the public apiKey and widgetId can be found when publishing embed code
for the corresponding widget from the Publish Center in the Pixlee dashboard:

require(["pixlee"],function (){
    Pixlee.init({apiKey:<apiKey>});
    Pixlee.addSimpleWidget({widgetId:<widgetId>});
    Pixlee.resizeWidget();
});

Note: you may insert any additional "addSimpleWidget" calls within the callback function
to display multiple widgets on the same page.

Tag Managers

Pixlee widgets can be implemented through the use of many popular tag managers. You may either create a custom container/tag which holds our embed code, or use our
official vendor tag. For specific tag manager instructions, check the links below:

Pixlee Widget User Guide


Pixlee Widgets are JavaScript widgets that, when added to your web page, create an iFrame experience hosted entirely by Pixlee that seamlessly blends into your site.

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.