Shutterstock UI

The Shutterstock UI widget lets you embed Shutterstock image and video search and licensing and other related features on your site. You can customize actions to happen when users search or click items, and you can get information about what they search for and click. You can implement the ability to license and download images and to browse previously licensed images.

Prerequisites

The widget works only with API applications that have referrer authentication enabled. In your application, you must specify the host names on which you will host the widget. You can specify localhost as a referrer for local testing.

To add referrer authentication to your app:

Go to https://shutterstock.com/account/developers/apps.
Create or edit an app you want to use with the widget.
In the Referrer field, specify a comma-separated list of host names that you will host the widget on.
Make sure that each referrer host name is also listed in the Callback URL field.
Save the app and note the consumer key.

Now you can use the consumer key from your application to authenticate your instance of the widget.

Authentication

The widget uses the same authentication that the API uses. In most cases, your application obtains an OAuth token from the API and uses that token to make requests on behalf of a Shutterstock account holder. For more information about authenticating to the API, see Authentication in the Shutterstock API reference.

After you have the token, you store it on the server side to avoid putting it in client-side code. Your application makes calls to the API, such as license requests, from that server-side code.

Quick start

You can use the wizard on this page to generate a starter widget in HTML or in React with the settings and parameters that you choose:

https://tech.shutterstock.com/shutterstock-ui-wizard/

This page lets you edit the widget code in a live preview so you can set it up the way you want it:

To add the widget to a page, import its source files and pass parameters that specify where to place it on the page.

On the page, import the JavaScript and CSS files.
In most cases, use the wizard to get links to a specific version of the CSS and JS files. If you link to these specific versions, the widget stays on that version until you choose to upgrade.
Create an HTML element to contain the widget and give it an ID, such as widget-container.
Create the the widget object.
In the the widget parameters, specify your API application's consumer key and the ID of the HTML element. The widget can show only one type of media at a time.
Add one or more pages. For information about the different pages that are available, see Customizing pages.
Call the widget's render() method or the search page's search() method to initialize the widget.

Now the widget appears on the page. You can implement callbacks such as onError, onItemClick, and onSearch to respond to actions as described below.

The search widget looks like this with the search bar enabled:

Here is an example of the widget with a single search page:

<html>
  <head>
    <link rel="stylesheet" type="text/css" href="https://api-cdn.shutterstock.com/{%version%}/static/css/sstk-widget.css">
    <script src="https://api-cdn.shutterstock.com/{%version%}/static/js/sstk-widget.js"></script>

    <script>
      window.onload = () => {
        const mySearchPage = {
          name: 'mySearchPage',
          component: ShutterstockWidget.components.SearchPage,
          props: {
            languageCode: 'en',
            mediaType: 'images',
            license: ['commercial'],
            showSearchBar: true,
            showMore: true,
            title: 'Search page',
            subtitle: 'Shutterstock UI',
            onItemClick: (event, item) => {
              event.preventDefault();
              console.log(`You clicked ${item.description}`);
            },
            onSearch: (search) => {
              console.log(`Your search found ${search.total_results} results. The first result is "${search.results[0].description}"`);
            },
          }
        };

        const widget = new ShutterstockWidget({
          container: document.getElementById('widget-container'),
          key: 'YOUR_API_APP_CONSUMER_KEY',
          customHeaders: {
            'x-shutterstock-application': 'Shutterstock UI Example App',
          },
          pages: [
            mySearchPage,
          ],
        });
        
        widget.render();
      }
    </script>
  </head>
  <body>
    <p id="statusText"></p>
    <div id="widget-container"></div>
  </body>
</html>

You can try the widget locally by running it on Node.js. Because it requires referrer authentication, the widget does not work without being hosted by a server. Follow these steps to set up the widget for local testing on a simple web server:

In your application, make sure that localhost is listed in both the Callback URL and Referrer fields.
Install Node.js.

In a command-line window, run these commands to create a folder for the widget, set up a Node.js application, and create the necessary files:

mkdir serve-shutterstockui
cd serve-shutterstockui
npm init
npm install express
mkdir public
touch index.js
touch public/index.html

Using any text editor, copy the following code into the index.js file:

const express = require('express');
const app = express();

app.use(express.static('public'));

app.listen(4646, () => console.log('App listening on port 4646!'));

Using any text editor, copy the following code into the public/index.html file:

<html>
  <head>
    <link rel="stylesheet" type="text/css" href="https://api-cdn.shutterstock.com/{%version%}/static/css/sstk-widget.css">
    <script src="https://api-cdn.shutterstock.com/{%version%}/static/js/sstk-widget.js"></script>

    <script>
      window.onload = () => {
        const mySearchPage = {
          name: 'mySearchPage',
          component: ShutterstockWidget.components.SearchPage,
          props: {
            languageCode: 'en',
            mediaType: 'images',
            license: ['commercial'],
            showSearchBar: true,
            showMore: true,
            title: 'Search page',
            subtitle: 'Shutterstock UI',
            onItemClick: (event, item) => {
              event.preventDefault();
              console.log(`You clicked ${item.description}`);
            },
            onSearch: (search) => {
              console.log(`Your search found ${search.total_results} results. The first result is "${search.results[0].description}"`);
            },
          }
        };

        const widget = new ShutterstockWidget({
          container: document.getElementById('widget-container'),
          key: 'YOUR_API_APP_CONSUMER_KEY',
          customHeaders: {
            'x-shutterstock-application': 'Shutterstock UI Example App',
          },
          pages: [
            mySearchPage,
          ],
        });
        
        widget.render();
      }
    </script>
  </head>
  <body>
    <p id="statusText"></p>
    <div id="widget-container"></div>
  </body>
</html>

Replace the variable YOUR_API_APP_CONSUMER_KEY with your consumer key.
In a command-line window, run the command node index.js.
In a web browser, go to the URL http://localhost:4646 to load the page.

Now you can try the widget and make changes to it locally.

Reference

For detailed information about implementing the widget in your application, see the Shutterstock UI reference.

Documentation

Shutterstock UI

Prerequisites

Authentication

Quick start

Embedding the widget on a page

Running the widget locally

Reference