The HowDidiDo Passport Javascript SDK enables third-party developers to integrate with the HowDidiDo Passport system, allowing golfers to benefit from a single login across multiple Club Systems International Ltd. products/services. It also frees app developers from having to implement their own authentication system, if they wish.
Include the following javascript into the body of the page(s) to be used with the SDK. This code will load and initialise the SDK. Make sure you replace [your-app-id] with the application id of your app and [your-redirect-uri] with the URL of your callback page (explained further down). Also make sure the scope values are customised to your app's requirements (more on scope).
<script src="https://passport.howdidido.com/scripts/auth/sdk.js">
<script>
PASSPORT.init({
app_id: '[your-app-id]',
scope: 'forename, surname, email',
redirect_uri: '[your-redirect-uri]',
version: '1.0'
});
When initialising the SDK you must provide a scope. This determines the user data the app can access. The value of scope can be changed at any time. The user will be asked to grant permission if the scope values provided haven't previously been authorized by the user.
Possible scope values are as follows (multiple values can be separated by a comma):
forename - The user's forename.surname - The user's surname.email - The user's email address.In order to check the status of a user, you must call getLoginStatus. This function takes a callback function in order to receive and handle the response. The example below uses a div with id "status" to render the appropriate content.
PASSPORT.getLoginStatus(function (response) {
statusCheck(response);
});
function statusCheck(response) {
var e = document.getElementById('status');
if (response.status == 'not_logged_in')
e.innerHTML = 'You are not logged in';
else if (response.status == 'not_authorised') {
e.innerHTML = 'You have not given permission for this app to access your passport account.';
}
else if (response.status == 'authorised') {
e.innerHTML = 'You are authorised and logged in';
if (response.data != null) {
e.innerHTML += "User Data: " + JSON.stringify(response.data);
}
}
else {
e.innerHTML = 'Unknown status';
}
}
The response object contains a number of fields that depend on the login status.
{
status: 'authorised',
data: {
'forename': 'Joe',
'surname': 'Blogs',
'email': 'joe@joebloggs.com',
'usertoken': '00000000-0000-0000-0000-000000000000'
}
}
Possible statuses are:
not_logged_in - The user is not logged in to the Passport system.not_authorised - The user is logged in to the Passport system but has not authorised the third-party app to access their personal data.authorised - The user is logged in to the Passport system and the third-party app has permission to access their personal data.unknown - The status of the user is unknown.The data section of response will only be available if the status is authorised. The fields in the data section relate to the value of the scope field supplied to PASSPORT.init, with the exception of usertoken, which is always included to uniquely identify the user.
Note:
If you have/are implementing your own authentication/authorization as well as making use of the HowDidiDo Passport system, you can use usertoken to link a Passport user with the corresponding user in your app's database.
To begin the login process, apps should call the login API function. This function will launch the HowDidiDo Passport pop-up login window. getLoginStatus can be called ahead of time to determine if login needs to be called or not. If a status of not_logged_in or not_authorised is returned from getLoginStatus, you should call the login function, which will automatically show either the login page or the authorisation page.
PASSPORT.login(function (response) {
statusCheck(response);
});
In order to return response data to apps, the Passport system needs execute a callback page hosted by the third-party on the same domain as the app. You must pre-register the callback URL with Club Systems International Ltd. for security reasons and also pass it into the init function as the value of the redirect_uri parameter. The Passport system executes the callback automatically so there is no additional work for app developers other than to serve the content of the page.
The callback page must return the following generic HTML code at present:
<!DOCTYPE html>
<html>
<head>
<title>HowDidiDo Passport</title>
</head>
<body>
<script>
// Popup or iframe.
(window.opener || window.parent).PASSPORT.loginStatusChangeCallback();
</script>
</body>
</html>
[your-app-id] and [your-redirect-uri] with the appropriate values. You will also need to host a callback page containing this code.
<!DOCTYPE html>
<html>
<head>
<title>HowDidiDo Passport</title>
</head>
<body>
<h1>HowDidiDo Passport Javascript SDK Test</h1>
<hr />
<div id="status"></div>
<script src="http://passport.howdidido.com/scripts/auth/sdk.js"></script>
<script>
PASSPORT.init({
app_id: '[your-app-id]',
scope: 'forename, surname, email',
redirect_uri: '[your-redirect-uri]',
version: '1.0'
});
/*
Check the status of this user and decide what to do.
*/
PASSPORT.getLoginStatus(function (response) {
statusCheck(response);
});
function statusCheck(response) {
if (response.status == 'not_logged_in')
document.getElementById('status').innerHTML = 'You are not logged in. <a href="#" onclick="doLogin()">Login</a>';
else if (response.status == 'not_authorised') {
document.getElementById('status').innerHTML = 'You have not given permission for this app to access your passport account. <a href="#" onclick="doLogin()">Authorize</a>';
}
else if (response.status == 'authorised') {
document.getElementById('status').innerHTML = 'You are authorised and logged in.';
if (response.data != null) {
document.getElementById('status').innerHTML += "<p>User Data: " + JSON.stringify(response.data) + "</p>";
}
}
else
document.getElementById('status').innerHTML = 'Unknown status';
}
function doLogin() {
PASSPORT.login(function (response) {
statusCheck(response);
});
}
</script>
</body>
</html>