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 issueToken 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) |
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}'
}
});
</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 resource method to further refine the organizations that are returned. |
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
}
}
});
</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 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. |
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>