Create SDK integration

Using the Create SDK, Shutterstock can render the Create editor into an element you designate on your website, bringing many of the tools and capabilities of the editor to your customers. The SDK allows your application to interact with the editor to export in-progress and final designs, observe telemetry about the user’s behavior, and control parts of the editor experience. The SDK is divided into two parts:

Getting Started

Partners will include a reference to the SDK’s javascript library in their source code, which will provide an SDK object to interact with. Insert a script tag into your html that refers to the Create SDK javascript library using the following format:

<script src="https://www.shutterstock.com/create/integration.js"></script>

NOTE: The CORS settings on your site must allow scripts to be served and executed from the corresponding Shutterstock domains, in particular Content Security Policy (CSP) script-src directive.

Once you have added a reference to the CreateSDK javascript library, you can access the global SDK constructor from the window object.

Obtain Your Partner Consumer Key

Consumer keys, also known as apiKey or api key, are specific to each partner and integration. These keys allow Shutterstock to:

How you obtain a key depends on the type of API account you have with Shutterstock.

Paid API Subscription Accounts

If you are a Shutterstock partner who has a paid API subscription, you should already be working with a partner manager on your account. Please contact your partner manager directly.

Free API Subscriptions

If you have a free API account from Shutterstock and want to try the Create SDK, please contact our sales team for help. If you have already created a Shutterstock API application, be sure to mention it. They may be able to add the Create SDK capability to your existing consumer key or help you set up a new application to experiment with.

Initialize Create SDK

By inserting the script tag, a CreateEditor method will be attached to the global window object. Use the CreateEditor method to initialize the SDK, which will confirm the requesting host matches one of the host values provided when you created your application.

Usage

const createSDK = window.CreateEditor(opts);

Parameters

Takes a plain JS Object of options for initializing the SDK.

Returns

CreateSDK object. The SDK has the following structure:

Checkout the Codepen example to see a simple example of how mount and use the CreateEditor.

Browser and Language Support

The Create editor and SDK currently only support desktop users with modern browsers. The browser family and major version is used to determine when to allow the editor to launch and when to block launching.

Browser Matrix

The code below is used to check minimum browser versions and determine if Create should be launched or not.

  export const supportedVersions = {
    [BrowserFamily.chrome]: '72',
    [BrowserFamily.firefox]: '65',
    [BrowserFamily.safari]: '11.0.3',
    [BrowserFamily.msedge]: '80',
    [BrowserFamily.opera]: '58',
  };
  export const supportedAndroidVersion = '4.4';
  export const supportedIOSVersion = '13';

Graphics Capabilities

Create requires users' devices to support WebGL in order to provide the real time interactivity with elements on the editor canvas. If users do not have adequately modern hardware or have disabled certain browser features, they may not be able to use WebGL. Learn more at get.webgl.com’s test page. In these cases, Create will present an error page and link to a self-help topic to address any configuration problems. Subscribe to the Error event to understand how often your users encounter this or other problems.

Mobile breakpoints

The Create SDK uses the browser and device type to determine if the user is on a mobile device. If an iOS or Android mobile device and browser are detected then Create will redirect users. The Create SDK does not use screen width or height to determine if the user is using a mobile device. If a specific viewport size needs to be defined, the recommendation from the Shutterstock UX team is to set the breakpoint to 800px. This will ensure an optimal user experience for the smallest possible screen size.

Tablets are recognized as separate devices from mobile and are able to launch the Create SDK.

Language and Translation

The editor UI and controls are translated into a variety of languages. Pass the language option when calling launchEditor to set the language for each user.

Editor-Supported Languages Codes

The editor supports a slightly smaller set of languages than the Shutterstock API does. See the language code supported by the API here.

Release Methodology

There are two main areas of concern to ensure the ongoing working order of your integration with Create SDK:

SDK Library

Our primary strategy for integration.js is to always be additive to the SDK, rather than changing existing APIs. Your javascript integration code with the SDK should never need to change, except to take advantage of new features.

Create App

Create is adding features to the editor continually, and also is using the CI/CD release methodology to ship both bug fixes and new features regularly. Therefore, we will account for SDK scenarios in all changes going forward. We will be working with Shutterstock Partner Managers to provide information on configuring newly added premium opportunities as they become available.

SDK Reference

Methods

Initialization returns an SDK object that has many properties that allow partners to interact with and control the Create editor.

launchEditor(opts)

Launches the editor and either starts a new blank document, or provides an image or template ID from the Shutterstock library to use as a starting point in the editor canvas.

Usage

const options = {
  ctaLabel: ‘Export’,
  document: {
    width: 600,
    height: 300
  },
  onDesignComplete: (design)=>{
    // code to interact with design object
  }
};
await sdk.launchEditor(options);
// OR
sdk.launchEditor(options).then(()=> {
  // your code here
})

Parameters

LaunchOptions Object - Required.

LaunchOptions

Returns

Promise<InitializedEditor> You should await or .then() the promise before interacting further with the SDK object. The launchEditor method will decorate the existing SDK object on which you called launchEditor with some internal SDK methods that you should not need.

addAssetToCanvas

Preconditions

You must set the overrideUploadHandler launch option to true in order to correctly use this method. Learn more about providing your own asset management API here.

Usage

See the usage section of the RequestAddAssetToCanvas event.

Parameters

Takes a single asset object.

Returns

Void.

closeEditor

Removes the iFrame that contains the Create editor and all resources from the DOM. Any design not exported or otherwise saved will be lost.

Usage

  const closeOptions = {};
  if (launchOptions.preventEditorClose) {
    closeOptions.forceEditorClose = true;
  }
  sdk.closeEditor(closeOptions);

Parameters

Returns

Void.

completeDesignAndClose

This method is used in connection with the launchEditor option hideTopBar, which suppresses the main navigation bar of the editor which includes the primary call to action button. Normally, the primary call to action button will fire both the DesignComplete and EditorClose events back-to-back. The completeDesignAndClose method empowers partners to mimic the primary call to action button from their own UI.

Usage

  const myButtonClickHandler = () => {
    sdk.completeDesignAndClose();
  }

Returns

Void.

exportDesign

Exports the current elements and layout in the editor’s canvas. The returned object can later be imported using the importAsset option for launchEditor.

Preconditions

In order to keep the exported Design size down, it is strongly recommended that you set the overideUploadHandler launchEditor option to true, and provide your own asset management API. This will use URLs for uploads, keeping the export size down. Otherwise, user uploads will be serialized into the Design’s document.uploadedAssetsB64Blobs collection on export, which will swiftly increase the size of the object.

Usage

const currentDesign = await sdk.exportDesign();

Returns

Returns a Promise<DesignExport> to provide a complete representation of the design’s data that can be stored by partners and reopened later. If you call replaceUnlicensedAssets to swap licensed images into the editor before exportDesign, the asset URLs will be reverted to watermarked images during the export process. Note, tampering with the Design’s internal schema or data in any way may result in unexpected behavior.

DesignExport

A DesignExport represents all of the component parts of a design needed to restore it to the Editor’s canvas at a later time by passing it as a launchEditor option. This allows users to reopen a design in the editor and adjust it.

getDesign(opts)

This method allows the host application to get a current snapshot of the user’s canvas. It utilizes the same output settings configured when you called launchEditor on the fileType. If fileType === FileType.jpg, the SDK will also honor the value requested with the jpegQuality option.

Usage

  const { getDesign, FileType} = sdk;
  const snapshot = await sdk.getDesign({
    fileType: FileType.jpg,
  });
  const url = URL.createObjectURL(snapshot.pages[currentPageIndex].imageBlob);

Parameters

Takes a single options object.

DocumentWatermarkOptions

Use this format to define a watermark that can be placed on a design provide by the getDesign method.

Returns

Promise<DesignSnapshot> - An object with information about the current state of the design. Any images with watermarks will still be watermarked. Learn more about the DesignSnapshot object.

getUnlicensedAssets

Reports out any assets that are used in the editor that need to be licensed. For images, this means they are watermarked.

Usage

  const unlicensedAssets = await sdk.getUnlicensedAssets();
  console.log(JSON.stringify(unlicensedAssets));
  /*
    [
      {
        "image_id": "506163361",
        "asset_token": "as_9xHC4pXJrW"
      },
      {
        "image_id": "506163362",
        "asset_token": "ab_9xHC4pQJrN"
      }
    ]
  */

Returns

Promise<AssetInfo> an array of AssetInfo objects that describe each of the unlicensed assets used.

AssetInfo

getUploadsInDocument

Reports out any uploads that are used in the current document. This method is useful if the Renderer service is used instead of a client side document render. It allows identifying any user uploaded assets in a design, and swap those assets’ sources for fresh URLs, that e.g. contain an authentication token, when they call the Renderer.

Usage

  const uploadsInDocument = await sdk.getUploadsInDocument();
  console.log(JSON.stringify(uploadsInDocument));
  /*
    [
      {
        "imageId": "image-id-0.9071800759653539",
        "assetToken": "as_YXn7gaCsF"
      }
    ]
  */

Returns

Promise<UploadInfo> an array of UploadInfo objects that describe each of the uploaded assets used.

UploadInfo

on, off, once

These three methods are responsible for programmatically adding or removing event handlers on supported events.

Parameters

Usage

  const handlerForExampleEvent = () => {
    // do some work
  }
  sdk.on(“ExampleEvent”, handlerForExampleEvent);
  sdk.off(“ExampleEvent”, handlerForExampleEvent);
  sdk.once(“EventName”, () => {
    // do some work
  });

Returns

Void.

hide, show

These methods are responsible for hiding and re-displaying the iFrame containing the Create editor using CSS. Hide leaves the SDK in memory so that the partner integration can continue interacting with the methods, however the end user will no longer be able to see and interact with the editor until show is called.

Parameters

None.

Usage

  sdk.hide();
  // editor iframe no longer displayed, sdk remains loaded
  sdk.show();
  // editor iframe is re-diplayed

Returns

Void.

replaceUnlicensedAssets(opts)

Swaps watermarked images used in a design for licensed images obtained from the Shutterstock licensing API. Learn more about techniques to license assets here.

Usage

  // first get the images you need to license
  const unlicensedAssets = await sdk.getUnlicensedAssets();
  // call the Shutterstock licensing APIs
  // Partner backend provides auth token, subscriptionID on proxied call
  const licensedAssets = await yourApiProxy.licenseAssets(unlicensedAssets);
  // pass the results to replaceUnlicensedAssets
  await sdk.replaceUnlicensedAssets(licensedAssets.data);

Parameters

Takes an array of LicensedAsset objects. For ease of use, the partner can pass the data response from the Licensing API directly to replaceUnlicensedAssets without modification. Therefore, some properties are not required and the property names are formatted slightly differently than the rest of the SDK.

LicensedAsset

Returns

Promise that resolves as the images are swapped.

setCustomUploadUrlAdjustment(opts)

When a partner is providing their own asset management API to manage custom uploads, they provide URLs to user assets in the partner’s storage system. Partners may need to change the host and/or path to the asset storage over time. Partners may also use the query string on an asset URL to provide tokens or other security mechanisms that need to be refreshed regularly. Therefore, the SDK provides setCustomUploadUrlAdjustment to replace the entire host + path and query string of an asset URL, preserving only the final segment of the path to represent the asset’s id.

Example

  const uploadedUrl = customUploadUrlAdjustment.prefix
    + originalAssetId
    + customUploadUrlAdjustment.suffix;

Preconditions

For setCustomUploadUrlAdjustment method to be necessary, the partner application must provide their own asset management API, as described here and support exportDesign where custom upload URLs would be stored.

Usage

  // original asset URL
  // https://partner0.cloudstorage.net:1234/bucket/path/abcde?token=value
  const exportedDesign = yourAssetApi.getUserDesign('abcde');
  const launchEditorOptions = {
    overrideUploadHandler: true,
    onRequestAddAssetToCanvas: addAssetHandler,
    onRequestDeleteAsset: deleteAssetHandler,
    onRequestUploadAsset: uploadAssetHandler,
    importAsset: exportedDesign,
  };
  const sdk = await editorSdk.launchEditor(launchEditorOptions);
  // Call on a timer with fresh values as necessary while SDK is loaded
  sdk.setCustomUploadUrlAdjustment({
    prefix: 'https://partner1.cloudstorage.net:5678/bucket2/path/',
    suffix: '?token=freshToken'
  });
  // Final asset URL would be:
  // https://partner1.cloudstorage.net:5678/bucket2/path/abcde?token=freshToken

Parameters

Takes an options object.

Returns

Void.

setUploads(assets)

This method sets the collection of image assets available in the uploads section of the editor. Asset urls point back to the partner’s asset manager. This should be called both when you first open the SDK, and also again from each of the asset upload handlers.

Preconditions

You must set the overrideUploadHandler launch option to true in order to correctly use this method. Learn more about providing your own asset management API here.

Usage

  // get assets from partner storage
  const userAssets = await yourAssetApi.getAllAssets();
  // map assets from partner format to the SDK asset format
  const mappedAssets = userAssets.map((asset) => {
    return {...asset};
  });
  // launch the editor
  await sdk.launchEditor({overrideUploadHandler: true});
  // add the user uploads into the editor uploads panel
  sdk.setUploads(mappedAssets);

See also the usage sections for the RequestUploadAsset and and RequestDeleteAsset.

Parameters

Takes an array of asset objects.

Returns

Void.

Objects

Common objects provided by the SDK or event handlers as parameters.

Asset

An object provided to the event handlers for asset management. This allows partners to manage assets in their private storage. Learn more about providing your own asset management API here.

DesignSnapshot

A DesignSnapshot object is provided as either the response to a call to getDesign or as a parameter passed to the event handler for DesignComplete.

DesignPage

Object that describes individual pages within a design.

FileType

This is found on the SDK object returned by the CreateEditor constructor. It contains the supported file formats the editor can export the design as. FileType essentially acts as an enum with the string representation of the file types. While you don’t strictly need to use the FileType object, it does guarantee the type you request maps correctly to the output types the SDK supports.

Usage

  console.log(JSON.stringify(sdk.FileType))
  /* output to console
    {
      png: 'png',
      jpg: 'jpg',
      pdf: 'pdf',
    };
  */
  const opts = {
    fileType: sdk.FileType.png,
  }
  sdk.launchEditor(opts);

JpegQuality

When the fileType option for launchEditor is designated as FileType.jpg, you may also set the jpegQuality option. The JpegQuality object contains the 3 supported jpeg quality levels: low, medium, high.

While you don’t strictly need to use the JpegQuality object, it does guarantee your request maps correctly to the supported levels.

Usage

  console.log(JSON.stringify(sdk.JpegQuality);
  /* output to console
    sdk.JpegQuality = {
      low: 'low',
      medium: 'medium',
      high: 'high',
    };
  */
  const opts = {
    jpegQuality: sdk.JpegQuality.high,
    fileType: sdk.FileType.jpg,
  }
  sdk.launchEditor(opts);

Events

The CreateSDK uses events to communicate between the editor provider in the iframe and the web app integration that hosts it. Event handlers can be attached in two ways:

Handlers are bound for ONLY those events that are supported and shown in the table below.

AddPageToDocument

This event is fired when the user adds or duplicates a page to the document.

Usage

  const addPageToDocumentHandler = () => {
    console.log(“User added a new page to the document“);
  };
  sdk.on(“AddPageToDocument”, addPageToDocumentHandler);

DeletePageFromDocument

This event is fired when the user removes a page from the document.

Usage

  const deletePageFromDocumentHandler = ({ pageId: string }) => {
    console.log(`User deleted a page from the document`);
  };
  sdk.on(“DeletePageFromDocument”, deletePageFromDocumentHandler);

Returns

EditorOpened

Announced when the Create Editor is launched and the Create editor React app begins bootstrapping itself within the container provided by the integrator.

Usage

  const editorOpenedHandler = () => {
  console.log(“Editor application has opened iframe);
  };
  sdk.on(“EditorOpened”, editorOpenedHandler);

EditorInteractive

Event is fired when the Create Editor is fully loaded and ready to use.

Usage

  const editorInteractiveHandler = () => {
  console.log(“Editor is interactive);
  };
  sdk.on(“EditorInteractive”, editorInteractiveHandler);

Error

The error event is fired when the Create Editor encounters significant or blocking error conditions. Partners are strongly encouraged to create a listener for the error event so you can log it to your systems and take remedial action as needed.

Usage

  const errorHandler = (errorDetails) => {
    const { id, message, data } = errorDetails;
    console.error(`The user encountered the ${id} error with the message: ${message}`, data);
  };
  sdk.on(“Error”, errorHandler);

Parameters

There is a single object provided to the event handler as a parameter. It is an ErrorDetails object that is based largely on the ECMA Error object.

ErrorDetails

Known Error Types

NOTE: This list will grow over time as more error conditions are identified.

Returns

Void.

DesignComplete

Optional handler that runs when a user completes a design as designated by clicking on the primary CTA in the header. This event is followed by an EditorClose event.

Usage

  const designCompleteHandler = (designSnapshot) => {
    const { pages, currentPageIndex } = designSnapshot;
    console.log(`This design has ${pages.length} pages.`);
    console.log(`The currently visible page in the canvas is page index ${currentPageIndex}`);
  };
  sdk.on(“DesignComplete”, designCompleteHandler);

Parameters

There is a single object provided to the event handler as a parameter. It is a DesignSnapshot object that describes information about the design that was just completed.

Returns

Void.

EditorClose

Optional function that runs when a user closes the editor

Usage

  sdk.on(“EditorClose”, (opts) => {
    const { userStatus } = opts;
    console.log(`User was ${userStatus} when they closed the editor`);
  }

Parameters

Options object with limited information about the SDK session that just completed when the editor closed.

Returns

Void

RequestAddAssetToCanvas

Occurs when a user attempts to add an image from the partner-provided uploads into the Canvas. This event handler is used in conjunction with the method addAssetToCanvas. Learn more about providing your own asset management API here.

Preconditions

Usage

  sdk.on(“RequestAddAssetToCanvas”, (addAsset) => {
    // Optional provide notification to user
    if(!window.confirm("Add image to canvas?")) return;
    // pass the addAsset event object back to the SDK
    sdk.addAssetToCanvas(addAsset);
  }

Parameters

Event handler receives an AddAsset event object.

AddAsset

RequestDeleteAsset

Occurs when a user attempts to delete an uploaded image from the uploads section of the editor. This event handler is used in conjunction with the method setUploads. Learn more about providing your own asset management API here.

Preconditions

You must set the overrideUploadHandler launch option to true in order for this event to be fired.

Usage

  sdk.on(“RequestDeleteAsset”, (deleteAsset) => {
    const { item } = deleteAsset;
    if(!window.confirm("Delete image from asset manager?")) return;
    // call your API to delete the item
    await yourAssetApi.delete(item.id);
    // update the uploads to the current full set of assets
    const partnerAssets = await yourAssetApi.getAllAssets();
    const assetsInSDKFormat = partnerAssets.map((parnterAsset) => {
      // do any necessary mapping
      return { ...parnterAsset }
    });
    // refresh the list of uploads in the SDK
    sdk.setUploads(assetsInSDKFormat);
  }

Parameters

Event handler receives an DeleteAsset event object, which can be inspected and transformed as needed before deleting from partner storage.

DeleteAsset

RequestUploadAsset

Occurs when a user attempts to upload an image using the upload button on the Uploads panel of the editor. The primary use case of this event is to be used in combination with the overrideUploadHandler launchEditor option where the partner provides their own asset management API. Learn more here. However, partners can listen to this event regardless of whether they are providing their own asset management API. When providing an asset management API, the partner should use the handler to intercept the upload event. This gives the partner the opportunity to generate a unique ID and URL for the asset and store it in their system. Before the handler is done executing, it must call the partner’s asset management API to retrieve the asset list from the partner system that contains the new upload and pass it to the SDK by the setUploads method.

Usage

  sdk.on(“RequestUploadedAsset”, (uploadedAsset) => {
    // first, store the upload to the partner system
    // responsible for generating a unique ID & URL to asset
    yourAssetApi.post(uploadedAsset);
    // retrieve the current full set of assets
    const partnerAssets = await yourAssetApi.getAllAssets();
    // map from partner storage format to SDK asset format
    const assetsInSDKFormat = partnerAssets.map((parnterAsset) => {
      return { ...parnterAsset }
    });
    // refresh the list of uploads in the SDK
    sdk.setUploads(assetsInSDKFormat);
  }

Parameters

Event handler receives an UploadAsset event object, which can be inspected, transformed and added to partner storage before being passed along to setUploads to add it to the Editor’s uploads panel.

UploadAsset

StockContentUpdated

Fired when a user alters the stock images that are used in the canvas, including both singular and multi-select add and remove operations. The event data gives you an accounting of the changes and the resulting state in the canvas, allowing the partner to accurately account for the licenses needed in the design.

Usage

  sdk.on(“StockContentUpdated”, (event) => {
    const { added, inUse, removed, updateType } = event;
    console.log(`Content was ${updateType}.`, added.length ? added : removed);
    console.log(`Count of stock in the canvas: ${inUse.length}`);
  }

Parameters

Event handler receives a single data parameter.

UserInteraction

Provides telemetry about the user’s behavior inside of the editor on a wide array of events that they may trigger. Some interactions have a data element with metadata about the user’s action that will tell you more.

Preconditions

Shutterstock will neither collect user telemetry, nor send it back to you on this UserInteraction event, unless enableUserInteraction is set to true in options passed to launchEditor. This relies on you to get consent from your users and pass that response to the Create SDK before any non-critical user data is recorded.

Usage

  sdk.on(“UserInteraction”, (event) => {
    const { eventName } = event;
    console.log(`The user just triggered a ${eventName} in the editor`);
  }

Parameters

Event handler receives a single event parameter.

UserInteraction Event Types

Supported events from the SDK.

Returns

Void.

Common Scenarios

Licensing Workflow

Your application can license assets without CreateSDK by making web requests to the Shutterstock API. You may do that with an API client such as the Shutterstock API JavaScript SDK and an API token to talk to the Shutterstock public API endpoints. Learn more about API clients here. Learn more about how to obtain a token here. Most partners use the “Getting tokens from your account page” option, and store the token securely When a partner combines the Shutterstock API with the CreateSDK, your application can create an end-to-end licensing experience in several ways:

Pre-Launch Licensing Using LaunchEditor Method

This flow requires you to license the Shutterstock image up front before launching the Create SDK, enabling you to open the editor with that licensed image as the starting point.

License While Designing Using the StockContentUpdated Event

When a StockContentUpdated event fires, the partner receives data from the editor that allows them to update prices and shopping carts. Optionally, partners can license immediately while still using the editor. This may be desirable if users want an opportunity to see their design with unwatermarked assets before finalizing the design.

License After DesignComplete Event

The user will work with watermarked images up until the time they are ready to complete their design and hopefully make a license purchase. The SDK lets you pause the DesignComplete event, license images, swap out watermarked images and extract a final piece of artwork with no watermarks. Once done, the partner can force the editor closed manually.

License After SDK Unload

In cases where a partner’s design editing experience is completely disconnected from the partner systems that do licensing with Shutterstock’s licensing API, it may be necessary to re-render the design with the newly licensed content. There are two options to swap licensed images into a design after you have unloaded the Create SDK & editor.

Reload the Editor

The simplest solution is to reload the Create SDK editor in the browser:

Rendering Service

In some scenarios, it may not be possible to reload the editor into a browser. For example, you may have a disconnected backend system responsible for managing checkout services. Instead of reloading Create SDK in a browser, the system can use the licensing API and Create SDK’s companion GraphQL Rendering Service to get the final rendered design.

User Identity and Asset Management

User Session

The Create SDK version of Shutterstock’s editor maintains the state of the user’s design during the current session only. The user has a temporary session with the editor, but is not required to create a user account with Shutterstock. This is known as an ‘anonymous’ session. When the editor and SDK are closed, the design is not preserved automatically. This means the user’s identity is always tied back to their identity in the partner system. This separation of concerns allows partners to control their users’ data at every stage of the workflow and leverage the SDK for editing and rendering their designs. Partners are provided a set of tools to complete important use cases:

Analytics and Privacy

It is important to honor the user’s privacy choices regarding collecting user telemetry and analytics. To ensure maximum safety and compliance, by default, Shutterstock will not collect or transmit any user telemetry back to the partners. If a user has consented to collecting analytics, the partner must set the launchEditor option enableUserAnalytics to true in order for Shutterstock to record user telemetry and echo it back via the UserInteraction event.

Saving and Restoring Designs

Because the user’s session is temporary, if the partner application intends to support saving and reopening a design later to continue editing, they must provide storage for a DesignExport object. Typically a partner may offer a “Save For Later” type button in their application, which triggers the exportDesign SDK method. This returns the object that can be stored in the partner system relative to the currently logged in user. When that user later returns, the partner can allow them to browse any saved projects. If a user decides to open an existing design project, the partner must set the stored ExportDesign object into the importAsset property of the launch Editor options object. NOTE: If the partner is NOT overriding the upload handlers with their own storage API to manage user-uploaded assets, the SDK will serialize those assets directly into the DesignExport object. This will swiftly increase the size of the DesignExport object. Therefore, it’s strongly recommended that if partners who want to support saving and restoring designs, that they also override the asset upload handlers so you can store the assets in your own system, providing URLs to the assets.

Managing Custom Asset Uploads

By default, the SDK version of the Create Editor does not support storing a collection of custom, user-uploaded assets that is persistent between sessions. Users do have the ability to make uploads one by one, which are inserted directly into the canvas. While convenient, as noted elsewhere, that will greatly increase the size of an exported design. So if you intend to support saving and restoring in-progress designs, it is strongly recommended that you provide your own storage for custom uploads.

Allowed Content Types

The Create Editor, and therefore the SDK, support uploads with the following content type, also known as mime type.

*** Multipage PDFs can be split into a maximum of 3 pages that are converted to PNG images. Each image will fire a separate RequestUploadAsset event.

Partner Asset Manager APIs

At minimum, a partner asset API must support these commands:

Configuring Asset Management

To configure your instance of Editor to accept and use uploaded images, you must provide event handler functions for these Editor SDK events:

  // launch the editor with the upload handler overridden
  await sdk.launchEditor({overrideUploadHandler: true});
  // retrieve existing uploads from partner API
  const userAssets = await yourAssetApi.getAllAssets();
  // map assets from partner format to the SDK asset format
  const mappedAssets = userAssets.map((asset) => {
    // do any necessary mapping
    return { ...asset }
  });
  // initialize assets when editor is first launched
  sdk.setUploads(mappedAssets);
  // implement upload handler
  sdk.on(“RequestUploadedAsset”, (uploadedAsset) => {
    // first, store the upload to the partner system
    // responsible for generating a unique ID & URL to asset
    yourAssetApi.post(uploadedAsset);
    // retrieve the current full set of assets
    const partnerAssets = await yourAssetApi.getAllAssets();
    // map from partner storage format to SDK asset format
    const assetsInSDKFormat = partnerAssets.map((parnterAsset) => {
      return { ...parnterAsset }
    });
    // refresh the list of uploads in the SDK
    sdk.setUploads(assetsInSDKFormat);
  }
  // implement an add-to-canvas handler
  sdk.on(“RequestAddAssetToCanvas”, (addAsset) => {
    // Optional provide notification to user
    if(!window.confirm("Add image to canvas?")) return;
    // pass the addAsset event object back to the SDK
    sdk.addAssetToCanvas(addAsset);
  }
  // implement an delete handler
  sdk.on(“RequestDeleteAsset”, (deleteAsset) => {
    const { item } = deleteAsset;
    if(!window.confirm("Delete image from asset manager?")) return;
    // call your API to delete the item
    await yourAssetApi.delete(item.id);
    // update the uploads to the current full set of assets
    const partnerAssets = await yourAssetApi.getAllAssets();
    const assetsInSDKFormat = partnerAssets.map((parnterAsset) => {
      // do any necessary mapping
      return { ...parnterAsset }
    });
    // refresh the list of uploads in the SDK
    sdk.setUploads(assetsInSDKFormat);
  }

Providing Your Own Nav Bar

Partners can use the hideTopBar property on the launchEditor options parameter to hide the primary nav bar that appears across the top of the editor. However, if you do this, you must also replace the functionality provided by the default nav bar:

Printing Safety

The Create editor has several LaunchOptions that can help users anticipate the limitations of taking their design from the digital world to the print world. Use these options to help your users’ designs look good when they go through the printing and cutting process.

Safety Line

If either bleedMargin or safetyMargin options are configured, Create will render a dashed safety line on the canvas indicating where elements risk being cut during the printing process. If not configured, the user can manually turn on the safety line on the settings menu under the Editor canvas. By default this adds a bleed margin of 38px to the dimensions of the document, and renders the safety line on the original document dimensions.

Crop Marks

Whenever a safety line is displayed on the canvas, the editor will automatically add crop marks to the finalized design when completed in the canvas. The crop marks, also known as cut marks, add an additional 37px of margin to allow for the crop marks on the document. The crop marks are placed outside of both the original dimensions of the document and any bleed margin that you configured. To prevent crop marks from being added, set the hideCropMarks LaunchOption when launching the editor.

SDK Renderer GraphQL Service

Overview of the Renderer

The Shutterstock Renderer Service provides a way for backend systems to render an exported design from the Create SDK when partners cannot load the Create SDK into the browser to do the rendering. This may be necessary when multiple systems provide an end-to-end flow with separate systems for each step. For example, a partner may load the Create SDK in the browser to empower a user to draft a design. Before navigating to a shopping cart system, the partner can export the design and safely unload the SDK. Once the user agrees to pay for stock content, the partner can license the content via the Shutterstock licensing API. Fulfillment systems can then provide the SDK-exported design and licensed content to the Renderer service to get a completed design without having to reload the full SDK into a browser.

Service Description

The Renderer API publishes GraphQL resolvers for interacting with the service. Partners can create a rendering task and subsequently query the status of their tasks for completion. The API takes a Shutterstock auth token, a Create SDK-enabled API key and the matching referer for the partner’s registered API application. The Renderer supports customizable properties including output format, image quality, and asset replacements. Each request is identified by a unique ID, and undergoes various statuses - from pending to completed or failed. When completed, the service returns a URL to the rendered image, valid for 24 hours.

Getting Started with the Renderer

If you are already familiar with GraphQL, you may skip over these sections introducing it and go right to the implementation section.

Introducing GraphQL

Background

GraphQL, developed by Facebook in 2012 and open-sourced in 2015, represents a query language and runtime that enables clients to request exactly the data they need, nothing more, nothing less. It emerged as a response to the limitations of REST APIs, offering a more efficient and powerful alternative, particularly for complex, interconnected data schemas. Contrary to REST, which uses different endpoints for different resources, GraphQL utilizes a single endpoint for all interactions. The type system and schema integral to GraphQL facilitate the precise querying of data, including nested resources, potentially reducing the amount of data transmitted over the network and improving application performance.

Understanding GraphQL

As you work to incorporate GraphQL into your project, it's essential to grasp the fundamental aspects that differentiate it from REST APIs and how these features can be leveraged to efficiently fetch data. In this section, we will introduce the basic concepts and the structure of a GraphQL query, providing a solid foundation to build upon as you move forward.

Basic Concepts

Query Language: GraphQL operates through a query language that allows clients to describe the exact structure of the data needed, facilitating precise and efficient data retrieval. Single Endpoint: Unlike REST APIs, GraphQL uses a single endpoint to handle all requests, simplifying the API structure and making it easier to manage and maintain. Schema & Types: Central to GraphQL is its schema, a blueprint that defines the types of data that can be queried and their relationships. The schema provides a contract between the client and server, ensuring data consistency and clarity on the available operations.

Structure of a GraphQL Query

Understanding the structure of a GraphQL query is vital in effectively leveraging its capabilities. Here's a breakdown of the essential components of a query: Field: At its simplest, a query is made up of fields. A field asks for a specific piece of information from the API. Arguments: Fields can take arguments, allowing you to pass variables and get varied responses based on the inputs. Aliases: When you need to query the same field with different arguments, aliases come in handy to avoid conflicts and streamline the query process. Operation Name: While not compulsory, specifying an operation name helps in organizing and identifying your queries, especially when you have multiple queries in your API. Variables: Variables allow you to reuse the same query but with different inputs, making your queries more dynamic and adaptable.

Setting up the GraphQL Environment

Integrating GraphQL into a browser and C# environments can be straightforward, especially with the aid of client libraries that encapsulate much of the complexity. Here, we'll guide you through setting up your environment to make GraphQL requests, either through specialized client libraries or by constructing raw web requests.

Tools and Libraries

While raw web requests can be used to interact with a GraphQL API, utilizing client libraries can significantly streamline the process and provide additional helpful features. Here are some suggestions for both C# environments and browser environments. C#-based libraries GraphQL.Client: A simple and modern library that makes it easier to integrate GraphQL APIs into your C# application. Hot Chocolate: A .NET platform for building GraphQL servers and clients, offering a wide array of features and extensive documentation. SAHB.GraphQLClient: A client library which allows you to easily execute queries against a GraphQL endpoint in a strongly typed manner.

Browser-based

The point of the Renderer service is to allow non-browser-based systems to render final designs without needing to load the SDK and design into the browser. If the use case you are solving requires a browser, you should consider using the SDK directly rather than using the Renderer service. Also, while browsers can make calls to the Renderer service, the service requires an authentication token. Storing auth tokens in the browser is not recommended best practice due to security concerns. Apollo Client: A popular choice that offers a comprehensive suite of features, including caching and state management. Its extensive documentation and community support can be a boon for developers. Relay: Developed by Facebook, it provides an efficient, predictable, and powerful way to build data-driven applications with React. GraphQL.js: A straightforward JavaScript GraphQL client, enabling you to make requests and handle responses with ease.

Calling the Renderer

To call the Renderer service, you must create a GraphQL client and authenticate that your requests are on behalf of a properly configured Shutterstock API account and application.

Authorization

In order to authenticate requests, you first need a Shutterstock API application that is enabled for the Create SDK. From this application, you will need:

Configuring Create SDK on Your Application

Your partner manager should be working with you to configure an application for the Create SDK. If you want to use that same application and API key for core Create SDK and the Renderer Service, you can proceed to obtaining the bearer token. If, however, you want to use a separate API application and consumer key for working with the Renderer, contact your partner manager who can set up a new or add the Create SDK product to an existing application. To manually confirm if the application & consumer key you want to use with the Renderer has Create SDK enabled, log into your Shutterstock account and view the details tab of the app you want to use.

Getting the API Key

The API key you send to the Renderer service is called consumer key on the API application’s authentication tab.

Getting Bearer Tokens

To create a token, you can either follow the oAuth guide here or log into your Shutterstock account, find the application you want to use and click on “generate token” on the Authentication tab.

Matching Referer

Calls to the Renderer service must also pass a fully qualified domain name that matches one of the configured referrer values on your API application. If you don’t remember what values were configured, contact your partner manager. You can also inspect this yourself by editing the application you are trying to use. The referrer field contains a comma-separated list of fully qualified domain names (FQDN) including the host, domain and, if applicable, the port number. If you do not find the FQDN you want to use in the referrer field, you can add it manually or follow up with your partner manager for help.

GraphQL Endpoint

The production endpoint for the service is: shutterstock.com/graphql

Schema

After deciding what library you want to use to work with the Renderer GraphQL endpoint, you will need to provide the Renderer’s schema file to configure the tool for making requests. GraphQL schemas provide an exact description of the data that can be asked for - what fields can we select? What kinds of objects might they return? What fields are available on those sub-objects? Schemas are written in GraphQL schema language, a simple language for defining the schema that is independent of the service implementation, allowing the backing service to be written in one of many different languages. Below is a copy of the graphql schema for the Create SDK to create and read render requests.

  """
  An sdk render request can be in one of the following states
  """
  enum CreateSdkRenderStatus {
    """
    The render request has been received and is waiting to be processed
    """
    PENDING
    """
    The render request is being processed
    """
    RENDERING
    """
    The render request has been completed successfully
    """
    COMPLETED
    """
    The render request has failed
    """
    FAILED
  }
  """
  A problem with the request
  """
  type CreateSdkRenderProblem {
    """
    The problem description
    """
    message: String!
    """
    The problem code from apollo-server-errors package
    """
    code: String
    
  }
  """
  Encapsulates the response and any problems with the request
  """
  type CreateSdkRenderResponse {
    """
    The response data (will be null if there are problems)
    """
    data: CreateSdkRender
    """
    Any problems with the request
    """
    problems: [CreateSdkRenderProblem!]
  }
  """
  A render request that returns the current status of the render and the url to the rendered image
  """
  type CreateSdkRender {
    """
    The ID of the render request to be used in subsequent requests
    """
    id: ID!
    """
    The url to the rendered image
    """
    urls: [String!]
    """
    The content type of the rendered image
    """
    contentType: String
    """
    The current status of the render request
    """
    status: CreateSdkRenderStatus!
  }
  """
  The available render types
  """
  enum CreateSdkRenderType {
    PNG
    JPEG
    PDF
  }
  """
  A replacement for an asset in the design
  """
  input CreateSdkRenderReplacement {
    """
    The asset_token of the asset to be replaced such as a watermarked image or user upload
    """
    key: String!
    """
    The replacement value, which should be a publicly accessible url
    """
    value: String!
  }
  """
  The input data for a render request
  """
  input CreateSdkRenderInput {
    """
    The format of the rendered image
    """
    type: CreateSdkRenderType
    """
    If type is JPEG, the quality of the rendered image
    Between 0 and 100
    Default is 80
    """
    jpegQuality: Int
    """
    Assets to be replaced in the design with pubicly accessible urls
    """
    assetReplacements: [CreateSdkRenderReplacement!]
    """
    The design blob
    """
    createDesignBlob: String
    """
    Used to request a specific version of the create application to be used for the render
    If not specified, the latest version will be used
    """
    sha: String
  }
  type Mutation {
    """
    Create a render request
    The response will contain the id of the render request to be used in subsequent requests
    The render request will be processed asynchronously and the response will contain the current status of the render and the url to the rendered image
    The url to the rendered image will be valid for 24 hours
    The apiKey must be a valid api key for the Create SDK
    The referer must be a referer set on the application associated with the api key
    """
    createSdkRender(
      data: CreateSdkRenderInput!
      apiKey: String!
      referer: String!
    ): CreateSdkRenderResponse!
  }
  type Query {
    """
    Get a render request by id
    The response will contain the current status of the render and the url to the rendered image
    The apiKey must be a valid api key for the Create SDK and must match the api key used to create the render request
    The referer must be a referer set on the application associated with the api key
    """
    createSdkRender(
      renderId: ID!
      apiKey: String!
      referer: String!
    ): CreateSdkRenderResponse!
  }

Making Raw Web Requests

Despite the conveniences offered by client libraries, sometimes you might prefer or need to make raw web requests. GraphQL is not bound to any specific library or tool. You can make HTTP POST requests with a JSON payload to interact with a GraphQL API. Here’s a generalized structure of how such a request would look:

C# (HttpClient)

using (var client = new HttpClient())
{
  client.DefaultRequestHeaders.Authorization = new System.Net.Http.Headers.AuthenticationHeaderValue("Bearer", "your-api-token-here");
    
    var queryPayload = new
    {
        query = @"
          mutation CreateRenderRequest($input: CreateSdkRenderInput!, $apiKey: String!, $referer: String!) {
            createSdkRender(data: $input, apiKey: $apiKey, referer: $referer) {
              data {
                id
              }
              problems {
                message
              }
            }
          }
        ",
        variables = new
        {
            input = new
            {
                // ... your serialized CreateSdkRenderInput fields go here
            }
        }
    };
    var response = await client.PostAsJsonAsync("https://shutterstock.com/graphql", queryPayload);
    var result = await response.Content.ReadAsStringAsync();
    Console.WriteLine(result);
}

Known Issues

Custom Uploads

Custom user uploads in the SDK DesignExport cannot be accessed by the Renderer without additional steps. By default, user-uploaded images in the Create SDK will be immediately inserted into the document and subsequently serialized into an exported design so that it can be reloaded later. Those uploads are only available in that unique DesignExport, and must be uploaded to the SDK again for each new design where they want to use the same uploaded image. If the DesignExport is given to the Renderer Service, these uploads will be ignored. However, some partners provide their own Asset Management API so their users have a persistent store of uploads each time they use the Create SDK editor. Partners set the customUploadUrlAdjustment LaunchOption to manipulate the host, path and the querystring of any uploaded asset URL to, for example, provide a short-lived token to authorize the requests from Create SDK to get the assets. This data may be expired by the time the Renderer obtains the DesignExport, so the partner must provide updated URLs when calling the renderer. Uploads can then be swapped out of a DesignExport when calling the Renderer:

Release notes

Release: v1.0.59 - May 2024

Documentation Published - Feb 2024