Skip to main content

 

Documentation & User Guides | FotoWare

Creating an integration that uses widgets only

Learn how to create a basic integration that exports an asset using FotoWeb widgets.

This topic explains how to create an integration using the FotoWeb Selection Widget and the Export Widget, without using features that require additional API access.

Licensing

Integration using only widgets is available when:

  • FotoWeb is installed on-premises with an activated API License

or

  • FotoWeb is a SAAS tenant on a plan that includes API access

or

  • The user has a Plus or Pro license, which gives access to widgets regardless of server licenses or SAAS plan

Application Registration

  1. In the FotoWeb site settings, select "Settings", then "Applications".
  2. Create a new application of type "Widgets only".
  3. As redirection URI, specify the web URL on which the application is hosted.
  4. Make a copy of the client ID, as it will be needed in the application.

Authorization

Once the user visits the start page of the application in the browser, the application must request an access token, which must be passed to embedded widgets to authorize the user to access FotoWeb.

The process is similar to authorization of a single-page JavaScript application, as explained in Authorizing Applications using OAuth - Single-Page JavaScript Web Apps without Back-end, which can be implemented as follows:

function createState()
{
    var text = "";
    var possible = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_~.";
    for (var i = 0; i < 16; ++i)
        text += possible.charAt(Math.floor(Math.random() * possible.length));
 
    return text;
}
 
function requestAuthorization(tenantURL, clientID, redirectURI)
{
    var state = createState();
    sessionStorage.setItem('state', state);
 
    window.location = tenantURL + "/fotoweb/oauth2/authorize?" +
        "response_type=token&" +
        "client_id=" + clientID + "&" +
        "redirect_uri=" + encodeURIComponent(redirectURI) + "&" +
        "state=" + encodeURIComponent(state);
}
 
function getAccessToken()
{
    var state = sessionStorage.getItem('state');
    if (state === null) return null;
 
    var params = window.location.hash.substring(1).split('&');
    var token = null;
    var stateValid = false;
    for (var i = 0; i < params.length; ++i)
    {
        var pair = params[i].split('=');
        if (decodeURIComponent(pair[0]) === 'access_token')
        {
            token = decodeURIComponent(pair[1]);
        }
        else if (decodeURIComponent(pair[0]) === 'state') {
            if (state === decodeURIComponent(pair[1]))
                stateValid = true;
            else
                alert("Invalid state! Someone is trying to mess with you!")
        }
    }
 
    if (stateValid)
        return token;
 
    return null;
}

 

The application first calls the function getAccessToken. If no access token is returned, then the application shows a start page with a "Log in" button. When the button is clicked, the application calls requestAuthorization using the following parameters:

  • tenantURL: The base URL of the FotoWeb site or tenant, e.g., https://acme.fotoware.cloud.
  • clientIDredirectURI: The application attributes from application registration.

The "Log in" button can also be omitted.

Once the requestAuthorization function is called, the user may see the standard FotoWeb login page, followed by a consent dialog. FotoWeb eventually redirects back to the application with an access token, which will then be returned by getAccessToken.

Widget Integration

General use of the widgets is described in the topic Using the Widgets.

The URL of the selection widget is as follows:

https://acme.fotoware.cloud/fotoweb/widgets/selection?access_token=ACCESS_TOKEN

 where ACCESS_TOKEN is replaced by the access token obtained in the authorization step is given in the query string of the URL.

Note: For all widget URLs, pay attention to follow this documentation regarding whether to put the parameters into the query string or fragment.

The URL of the export widget is the same for both types of integration and thus also described in the topic Using the Widgets.