Getting Started

The widget is an incredibly simple white-labeled solution to sell printed products entirely in your own site– no redirects to other pages, no “sharing” of customers and/or customer data. The entire transaction takes place seamlessly within your site, and we never use/reuse/share your customer data.

If you’re looking for something more lightweight than this, perhaps just a wrapper over our API, please check out our client-side js library.

The widget does not pollute any of the page’s CSS/JS. All of the JS is placed under the PIO namespace and all of the CSS is inline.

pio.js is pure javascript and weighs in at around 5kb. Zero 3rd party JS files are used. In other words, this file does not include/need jquery, lodash, zepto, or any other lib. You will not have JS clash issues.

In order to get started with the widget, you need to get an api key (which we call RecipeId). This can be obtained by signing up. By default, the widget is setup to run against our staging environment; in the staging environment no items get submitted, and no real charging occurs. It’s easy to switch to live when you’re ready to release.

One of the widget’s goals is to be entirely customizable and extensible to as many use cases as possible. To this end, developers can control both the style and the functionality/flow via its simple JS API.

Note that customers that use our widget also tend to use either our orders GET endpoint/API or our webhooks solution to have order/customer data sync-ed back into their systems. Of course, this is entirely optional.

Example

We recommend you place the code for embedding and configuring side by side.

The pio.js script is hosted on an https-ready CDN at https://az412349.vo.msecnd.net/pio/pio.latest.v2.js.

After one has embedded the script one can then configure the widget using the PIO.config(options) function.

PIO.config({
    // required -- set the widget endpoint url
    url:"https://widget.print.io/widget/",
    // required -- api key
    recipeId:"",
    // preload data into localstorage
    // so that the user's experience is fast
    preLoad: { on: true},
    // show all products available for the region
    useDefaultProductSettings:true
});

Now that we have it configured, we can easily have the widget launch by attaching the open function to a button:

$('#myButton').on('click',function(e){
    e.preventDefault();
    //this will open the widget-- easy!
    PIO.open({});
});

Or perhaps we could pass an image into the widget when we open it:

$('img.clickable').on('click',function(e){
    e.preventDefault();
    //here we pass the src of the image that was clicked
    PIO.open({
        images:[$(this).attr('src')]
    });
});

And thats it!

Switching Between Testing and Live

We offer a testing mode for partners to test with before they go live. The default setting is live. Switching to test is pretty simple though– merely pass in the appropriate setting to the widget:

PIO.open({
  recipeId:"6cfb4f30-34c7-4cf6-9490-f51925650811",
  // the live url
  url:"https://widget.print.io/widget/",
  // set test mode
  // -- could also be done in the .config()
  isInTestMode:true
});