Emplifi UGC Widget User Guide

Introduction

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

How it works

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

All Emplifi UGC 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 Emplifi UGC widgets on a page; they are intelligent and share the same lightbox and uploader (if enabled) automatically. To do so, you must create and then pass in the identifier of the target element to each of the widgets with the 'containerId' option. By default, we include a target element 'pixlee_container' and target that.

Emplifi UGC widgets can be loaded by an addition of a script tag generated by the Emplifi UGC Publishing GUI (most common use-case), or through use of third party tag managers like Google Tag Manager or Tealium. We highly recommend using our publishing GUI, 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 publishing GUI to generate code snippets for publishing, you can stop here.

Limitations

This document is intended to provide an in-depth explanation 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:

Subscribing to Widget Events

All widgets emit events when certain actions occur. You can optionally subscribe to these events using the 'subscribedEvents’ option, which accepts an array of strings. Currently the following events are available for subscription:

photoOpened: fired when a user clicks on a photo, opening the lightbox
photoClosed: fired when a user closes a previously opened photo, closing the lightbox
ctaClicked: fired when a user clicks on a photo’s call to action link within the lightbox

Passing the following option to addSimpleWidget/addProductWidget will cause the widget to emit events for these actions:

subscribedEvents: ['photoOpened','photoClosed’]

You can then add an event listener to your page in order to take actions when these events occur:

CODE

function receiveMessage(event) {
    //only listen to events coming from Pixlee
    if (event.data) {
        try {
            var message = JSON.parse(event.data);
        } catch (error) {
            return;
        }
    } else {
        return;
    }
    if(message.eventName && message.eventName === 'photoOpened'){
       //take action when a photo is opened
    }else if(message.eventName && message.eventName === 'photoClosed'){
       //take action when a photo is closed
    }else if(message.eventName && message.eventName === 'ctaClicked'){
       //take action when a cta is clicked
    }
}
window.addEventListener("message", receiveMessage, false);

In Depth Implementation

The album that a widget references and displays can be hard-coded into the script tag or dynamically assigned if on a product or category page by simply passing in a productId or categoryId option.

There are multiple widget experience types, such as photowall, horizontal, coverflow, mosaic, slideshow. The type of experience rendered is denoted by the 'type' option.

If you have custom CSS applied to your widget(s), the displayOptionsId created by the publishing GUI can be passed to your widget(s) If you have a custom sort order, applied to your widget(s), the recipeId created by the publishing GUI can be passed to your widget(s) When loading onto a product or category page, the addSimpleWidget function call becomes addProductWidget() or addCategoryWidget(), respectively.

All widgets require an API key, accountId, type and one of the following: albumId, productId, or categoryId, depending on which ‘add’ function is called. If recipeId or displayOptionsId are not defined, we will default to the standard experience.

At the bottom of our initialization snippet, we include a reference to Emplifi UGC widget. This is only to be called once, after the rest of your initialization code. If you do not wish to include this script in your body for any reason, you may wrap the rest of your code snippet inside of the window.PixleeAsyncInit function in an onReady event.

If using the publishing GUI for simple publishing, all of the above will be automatically handled by the wizard and you will receive a code snippet that might look like the following examples:

Example single widget code snippet:

CODE

<div id="pixlee_container"></div>
<script type="text/javascript">
    window.PixleeAsyncInit = function() {
        Pixlee.init({
            apiKey: '<redacted>'
        });
        Pixlee.addSimpleWidget({
            albumId: 2652,
            recipeId: 181,
            displayOptionsId: 3611,
            type:"photowall",
            accountId:2
        });
    };
</script>
<script src="https://assets.pixlee.com/assets/pixlee_widget_1_0_0.js "></script>

Example multiple widget snippet:

CODE

<div id="pix1"></div>
<div id="pix2"></div>
<script type="text/javascript">
    window.PixleeAsyncInit = function() {
        Pixlee.init({apiKey:'<redacted>'});
        Pixlee.addSimpleWidget({
            albumId:203679,
            recipeId:237,
            displayOptionsId:6829,
            type:"mosaic",
            accountId:827,
            setMetaTags:true,
            containerId:"pix1"
        });
        Pixlee.addSimpleWidget({
            albumId:203679,
            recipeId:237,
            displayOptionsId:6829,
            type:"mosaic",
            accountId:827,
            setMetaTags:true,
            containerId:"pix2"
        });
    };
</script>
<script src="//assets.pixlee.com/assets/pixlee_widget_1_0_0.js"></script>

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

This order is important.

Widget Reference

Pixlee.init()
- apiKey (required)
  Organization API key
Pixlee.addSimpleWidget()
- accountId (required)
  Emplifi UGC account id
- type (required)
  Type of experience to be rendered (photowall, horizontal, coverflow, mosaic, slideshow)
- albumId (required)
  ID of the album to be rendered
- displayOptionsId (optional)
  ID of the custom CSS options stored in Emplifi UGC
- recipeId (optional)
  ID of the custom filter and sort applied to the experience
Pixlee.addProductWidget()
- accountId (required)
  Organization Emplifi UGC account id
- type (required)
  Type of experience to be rendered (photowall, horizontal, coverflow, mosaic, slideshow)
- productId (required)
  ID of the product to be rendered
- displayOptionsId (optional)
  ID of the custom CSS options stored in Emplifi UGC
- recipeId (optional)
  ID of the custom filter and sort applied to the experience
Pixlee.addCategoryWidget()
- accountId (required)
  Organization Emplifi UGC account id
- type (required)
  Type of experience to be rendered (photowall, horizontal, coverflow, mosaic, slideshow)
- categoryId (required)
  ID of the category to be rendered
- displayOptionsId (optional)
  ID of the custom CSS options stored in Emplifi UGC
- recipeId (optional)
  ID of the custom filter and sort applied to the experience

Do you have feedback or more questions? You can contact us through our Emplifi Customer Center.