JavaScript API

Overview

SheerID's JavaScript API provides functionality that is useful when integrating SheerID into user-facing web applications. The JavaScript API consists of a base JavaScript include (https://services.sheerid.com/jsapi/SheerID.js) and a number of useful modules which can be included and configured, each of which is described in the Modules section below.

Common Module Configuration

The following configuration options are available for all modules and are configured in the same way as module-specific configuration.

Configuration Key Required? Description Default Value
baseUrl No The URL prefix for REST API interactions. To use the sandbox API, set this value to https://services-sandbox.sheerid.com https://services.sheerid.com

Generic Usage Pattern

<script src="https://services.sheerid.com/jsapi/SheerID.js"></script>
<script>
SheerID.load('${module_name}', '${module_version}', {
    config: {
        '${config_key1}' : '${config_value1}',
        ...
        '${config_keyN}' : '${config_valueN}'
    }
});
</script>

Modules

Asset Upload

This module facilitates an upload of a document using the Asset Upload REST resource method.

Module Name:
asset
Supported Version(s):
1.0

Module Configuration

Configuration Key Required? Description Default Value
token Yes An asset upload token obtained from the Issue Token REST resource method. None
container Yes The ID of an element in the page inside of which the form should be rendered. None
maxFiles No The maximum number of files that can be uploaded at a time. 1
ajax No Use AJAX-style upload keep the end-user on the same page while the upload is processing and after it has completed. false
success Only if ajax = true A URL to redirect to upon successful upload. None (raw JSON response is displayed)
failure Only if ajax = true A URL to redirect to upon encountering an error uploading the file. None (raw JSON error response is displayed)
messages No A object literal of string key/value pairs used to modify the default text generated. See the Usage Example below for a list of the default key/value pairs. Customers who wish to present this module within localized interfaces, will need to provide localized versions of the strings within the message object. See below for default (English) messages

A note about AJAX mode: The background file upload is not actually using AJAX but rather POSTing to a hidden iframe and waiting for the result. The success and failure URLs in this case are not displayed to the user, but instead used as indicators of the success/failure status of the upload request. For this reason, it is very important that these URLs match completely the domain, port and protocol of the page serving the upload form, in order for the event handlers to properly detect a completed upload.

Usage Example

<div id="upload"></div>
<script src="https://services.sheerid.com/jsapi/SheerID.js"></script>
<script>
SheerID.load('asset', '1.0', {
    config: {
        container: 'upload',
        maxFiles: 3,
        success : '${successUrl}', // replace with your success URL
        failure : '${failureUrl}', // replace with your failure URL
        ajax: true,
        token: '${assetUploadToken}',
        messages: {
            'instructions': 'Please upload document(s) that prove your affiliation.',
            'add_file': 'Add another file...',
            'error400': 'Bad Request',
            'error401': 'Bad Token',
            'error403': 'Upload Not Allowed',
            'error415': 'Invalid File Type',
            'error500': 'Server Error',
            'error': 'Unknown Error',
            'nofile': 'Please ensure that you have selected at least one file to upload.',
            'submit': 'Submit',
            'submitButtonPrefix': '',
            'submitButtonSuffix': '',
            'success': 'Upload Complete!',
            'uploading': 'Uploading...',
            'uploadTimeout': 'It appears we may have encountered an issue uploading your document(s).',
            'linkDirectUpload': 'Click here to try the conventional upload method instead.'
        }
    }
});
</script>

Organization Combobox

This module simplifies the process of specifying a SheerID organization for use in the Verify REST resource method. Using this module will transform an existing HTML input field into a type-ahead/combobox that helps the user select the appropriate organization.

Module Name:
combobox
Supported Version(s):
1.0 2.0

Module Configuration

Configuration Key Required? Description Default Value
input Yes A reference to a DOM (input) element that will be converted into the combobox. None
allowName No true to allow users to specify an organization name that is not in the list, otherwise combobox will require the user to select an option from the list. false
proxyName No If set, the text entered into the combobox field will be submitted by the current form with this parameter name. None
mode No select mode can be used to render as a standard HTML select element instead of a type-ahead. combobox
trigger No Determines whether a drop-down toggle is displayed in the right-hand side of the combobox to allow selection of an organization with a mouse. true
params No An object literal containing request parameters that will be supplied to the List Organizations or the Typeahead resource method to further refine the organizations that are returned. This can be used to modify the combobox for international use by assigning the parameter country to a value containing a string of the corresponding country code and the parameter includeLocation to the boolean true. none
customOrganizations No An array of additional organization names (if any) that should be added to the list fetched via API. When one of these options is selected, the underlying input value will be 0, so this should be used in conjunction with the proxyName and allowName configuration options so that the selected name is submitted. none

Usage Example (Version 2.0)


<form>
    <input type="text" name="organization.id" id="orgId" placeholder="School Name" />
    <input type="text" name="data['FIRST_NAME']" id="custFirstName" placeholder="First Name" />
    <input type="text" name="data['LAST_NAME']" id="custLastName" placeholder="Last Name" />
    <input type="text" name="data['EMAIL']" id="custEmail" placeholder="Email" />
    <input type="text" name="data['POSTAL_CODE']" id="custZipCode" placeholder="Zip Code" />
    <button type="submit">Submit</button>
</form>
<script src="https://services.sheerid.com/jsapi/SheerID.js"></script>
<script src="https://code.jquery.com/jquery-1.12.4.min.js"></script>
<script>
    SheerID.load('combobox', '2.0', {
        config: {
            input: document.getElementById('orgId'),
            allowName: true,
            proxyName: 'organization.name',
            listeners: {
                change: function(orgEntity) {
                    document.getElementById('custZipCode').value = orgEntity.zip;
                }
            },
            params: {
                type: ['UNIVERSITY', 'K12'],
                includeLocation: true,
                country: 'US'
            }
        }
    });
</script>

Usage Example (Version 1.0)


<form>
    <input type="text" name="organizationId" id="myOrgId" />
    <button type="submit">Submit</button>
</form>
<script src="https://services.sheerid.com/jsapi/SheerID.js"></script>
<script>
SheerID.load('combobox', '1.0', {
    config: {
        input: document.getElementById('myOrgId'),
        allowName: true,
        proxyName: 'organizationName',
        mode: 'combobox',
        trigger: true,
        params: {
            type: 'UNIVERSITY'
        }
    }
});
</script>

Redeem Token

This module provides integrators with a simple (client-side) way to redeem a Redemption token.

Warning: We provide this component as a convenience to users that must use client-side techniques to handle a callback from SheerID, but our recommendation is always to perform the token check server-side. If you must use this component, please use secure JavaScript programming techniques to protect your success/failure callbacks and understand that savvy users may be able to work around this implementation.

Module Name:
redeem
Supported Version(s):
1.0

Module Configuration

Configuration Key Required? Description Default Value
token Yes (or tokenParam) The redemption token to redeem. None
tokenParam Yes (or token) A query string parameter from which to read the redemption token. None
onSuccess No A callback function to be executed upon successfully redeeming the token. None
onFailure No A callback function to be executed upon failing to redeeming the token because it is redeemed, expired or invalid. None
onError No A callback function to be executed upon encountering an error when attempting to redeem the token. One argument will be passed which is a (string) error code (possible values: "no_token"). None

Usage Example

<script src="https://services.sheerid.com/jsapi/SheerID.js"></script>
<script>
SheerID.load('redeem', '1.0', {
    config: {
        tokenParam: 'sheerIdToken',
        onSuccess: function() {
            myPrivateObj.success();
        },
        onFailure: function() {
            myPrivateObj.failure();
        }
    }
});
</script>

iFrame

This module simplifies the setup of a SheerID hosted verification template within an iFrame. It uses postMessage() to send communications between the verification template and the iFrame object to adjust the height of the iFrame to match the content of the verification template for a more natural presentation.

Module Name:
iframe
Supported Version(s):
1.0 1.1
Browser Compatibility:
Google Chrome 18+
Mozilla Firefox 15+
Internet Explorer 9+
Safari 5+
Opera 12+

Module Configuration

Configuration Key Required? Description Default Value
lightbox No true will present the iFrame as a lightbox popup. The remaining configuration keys apply to the lightbox iFrame. false will apply a default config which sets the iFrame container's width to 100%. true
width No String containing the width of the iFrame as a css value. "600px"
height No String containing the height of the iFrame as a css value. If set to "fluid", the iFrame will listen for postMessages from the verification template and adjust its height to match. "fluid"
maxHeight No Number to check the height of the iFrame content against. If the height received from the message is larger than the maxHeight, the iFrame's height will be set to the maxHeight and the iFrame will use a scroll bar. The maxHeight property is only supported in version 1.1 or greater. null
mobileRedirect No true will redirect the user directly to the verification template rather than display the lightbox when the user's screen width is less then the mobileThreshold. This provides a better user experience on mobile devices which have trouble displaying popups. true
mobileThreshold No The value in px to check against the user's screen width to determine whether to display the lightbox or redirect to the verification template. 600
top No String containing the position from the top of the browser window the lightbox should position itself as a css value. "10%"
border No String containing the border style property for the lightbox wrapper as a css value. "2px solid #999"
borderRadius No String containing the border radius for the lightbox wrapper as a css value. "0px"
closeBtnTxt No String containing the text for the close lightbox link. ""
closeBtnFont No String containing the font style for the close link text as a css value. See CSS font property for more info. "16px Arial,Serif"
closeBtnColor No String containing the color of the close link text as a css value. "#999"
closeBtnImg No String containing the full url of an image to be used in the close link. The image will be displayed to the right of any close link text. Use "none" to not use any button image. Optionally, can use 1 of 3 SheerID hosted images by providing a value of "btn1", "btn2", or "btn3". "btn1"
closeBtnTop No String containing the position of the close link from the top of the iFrame as a css value. "10px"
closeBtnRight No String containing the position of the close link from the right of the iFrame as a css value. "10px"
stopPropagation No true will prevent the click event from bubbling up the DOM when clicking the link to activate the lightbox. false

Lightbox Usage Example

<div>
<a href="https://verify-demo.sheerid.com/my-military-app/" data-sheerid-iframe="true">Click here for a military discount</a>
<a href="https://verify-demo.sheerid.com/my-student-app/" data-sheerid-iframe="true">Click here for a student discount</a>
</div>
<script src="https://services.sheerid.com/jsapi/SheerID.js"></script>
<script>
SheerID.load('iframe', '1.0', {
    config : {
        closeBtnTxt: "Close",
        closeBtnImg: "none",
        border: "2px solid black",
        borderRadius: "6px",
        closeBtnTop: "25px",
        closeBtnRight: "25px",
        closeBtnColor: "#000",
        closeBtnFont: "16px Times New Roman",
        top: "50px"
    }
});
</script>

Embedded Usage Example

<div data-sheerid-iframe="true" data-target="https://verify-demo.sheerid.com/my-teacher-app/"></div>
<script src="https://services.sheerid.com/jsapi/SheerID.js"></script>
<script>
SheerID.load('iframe', '1.0', {
    config : {
        lightbox: false
    }
});
</script>