CIDM Neo Developer Guide

initialise(config)

Initialise the profile widget for the current web page. In summary this function performs the following actions:
1) Read provided configuration values (client id, level, required attribute) provided by the webpage.
2) Start the profile widget storage provider. $jc.qgcidm.config.hub is used to setup the storage engine.
3) Detect browser capabilities in terms of iframes and crow window messaging.
4) Initialise all window message event listeners. Event listeners are used to receive and execute profileAction commands originating from widgets running as modal. for example closing of widget frames or handling authorization results from the CIDM-NEO profile application.
5) Initialise the session expiration library with some basic config values. This does NOT start session expiration but only configure it.

enable(e)

Enable the profile widget for the current web page. In summary this function performs the following actions:
1) Extract, interpret and perform any 'profileAction' parameters from the CIDM-NEO Profile Application in the page URL.
2) Extract, parse and store any embedded #token parameter in the URL.
3) Request all attributes specified by configuration. On successful retrieval of a minimum set of attributes (Picture and Email) perform the following: - Execute any onAttributes event handlers.
- Enable session expiration countdown.
- Associate a generated Profile Menu with specified avatars.
- Register the new token in widget domain cookie.
- Execute any onLogin event handlers.
- Start the authorization sequence (step-up, EOI, sharing) if required.

searchAttribute(nameKey)

Retrieve from the profile widget $jc.qgcidm.profile property any attribute value with name being specified by nameKey. Does the same as getAttributeValue(...). Note: attributes aren't retrieved from the API with this call but from memory.

getSignedAttributes()

Retrieve from the profile widget $jc.qgcidm.profile property all attributes issued and signed by the CIDM-NEO customer attribute API. Note: attributes aren't retrieved from the API with this call but from memory.

getAttributeAccessWarnings()

Retrieve from the profile widget $jc.qgcidm.profile property all warning issued by the CIDM-NEO customer attribute API. Note: attributes aren't retrieved from the API with this call but from memory.

getAttributeValue(nameKey)

Retrieve from the profile widget $jc.qgcidm.profile property any attribute value with name being specified by nameKey. Note: attributes aren't retrieved from the API with this call but from memory.

getAttributes()

Retrieve from the profile widget $jc.qgcidm.profile property all attributes issued by the CIDM-NEO customer attribute API. Note: attributes aren't retrieved from the API with this call but from memory.

getLoginInfo(callback)

Retrieve login information for the current identity from the CIDM-NEO customer_identity API. The value returned by callback should be NOT NULL for any valid customer authentication. This can be used to determine if the current login is valid.

getLoginURL(redirectUrl)

Generate an Auth0 login URL as means of directing the browser to the Auth0 SIGN-IN page. This page will prompt the customer to log in.

getLogoutURL(e)

Generate an Auth0 login URL as means of directing the browser to the Auth0 SIGN-OUT page. The generated logout URL can be adapted by setting the following in configuration:
- logoutUrl: This URL will be used as return location after sign-out has been performed.
- logout_federation: Pass the sign-out to federated identity providers like Google or Microsoft. This will cause the federated account to also sign-out.

getStorage(name, callback)

Retrieve session values from profile widget storage provider.
Typical keys used to retrieve values are $jc.qgcidm._auth_result, $jc.qgcidm._auth_token, $jc.qgcidm._release_token .
Example usage:

$jc.qgcidm.getStorage( $jc.qgcidm._auth_token, function( token ) { ... } )

delStorage(name, callback)

Delete session values in the profile widget storage provider. Example usage:

$jc.qgcidm.delStorage( your item name, function() { ... } )

setStorage(name, value, callback)

Save session values in the profile widget storage provider. Example usage:

$jc.qgcidm.setStorage( your item name, your value, function() { ... } )

onAttributes(callback)

Accepts a handler as callback which will be executed when attributes are successfully retrieved from the CIDM-NEO customer attributes API. ( triggered by $jc.qgcidm.enable(...) and $jc.qgcidm.updateProfile(...))
The callback function will receive all attributes returned from the API.

onAuthorized(callback)

Accepts a handler as callback which will be executed when a customer has successfully completed all required authorization steps (like step-up, EOI or Sharing preferences).
The callback function will receive all authorization result upon execution. Example result: { IAAL: 1, IRAL: 2, cancelledEOI: false, cancelledRelease: false, cancelledStepup: false, errorCode: 0, releaseToken: eyJr...bw, shareAlways: false}.

NOTE: The profile widget will continue executing the onAuthorized callback per page load (or call to $jc.qgcidm.enable(...) ) for the duration of the customer session with the configured client service (clientID as identifier). Once a customer has signed-in again this event will stop being executed. Only after the authorization sequence has been attempted again will the onAuthorized callback be executing again.

onUnAuthorized(callback)

Accepts a handler as callback which will be executed when a customer has prematurely opted (or error) out of a required authorization step (like step-up, EOI or Sharing preferences).
The callback function will receive all authorization result upon execution. Example result: { IAAL: 1, IRAL: 2, cancelledEOI: false, cancelledRelease: false, cancelledStepup: false, errorCode: 0, releaseToken: eyJr...bw, shareAlways: false}.

NOTE: The profile widget will continue executing the onUnAuthorized callback per page load (or call to $jc.qgcidm.enable(...) ) for the duration of the customer session with the configured client service (clientID as identifier). Once a customer has signed-in again this event will stop being executed. Only after the authorization sequence has been attempted again will the onUnAuthorized callback be executing again.

onLogin(callback)

Accepts a handler as callback which will be executed when a customer is signed-in. Whether to execute the onLogin event is determined by the presence of a valid JWT in storage and a minimum set of attributes (picture and email) returned from the customer attributes API for the current JWT.

NOTE: This event will be fired on each page load (or call to $jc.qgcidm.enable(...) ) when the above criterion is met.

onLogout(callback)

Accepts a handler as callback which will be executed just before a customer is signed-out. The logout function will clear token values in storage and cookies.

startAuthorizationSequence()

Starts the authorization sequence. This function will preform the following:
1) If the $jc.qgcidm.config.authorization_enabled flag is true then continue.
2) Retrieve any existing authorization results ( for example: { IAAL: 1, IRAL: 2, cancelledEOI: false, cancelledRelease: false, cancelledStepup: false, errorCode: 0, releaseToken: eyJr...bw, shareAlways: false} ).
3) Make a call to the CIDM-NEO customer identity API to verify that the customer has reached the required AAL level (as per $jc.qgcidm.config.level).
4) Determine whether any of the configured attributes (in $jc.qgcidm.config) requires sharing privileges.
5) If any configured attribute require sharing privilege or the customer has not yet reached the required AAL level the authorization sequence start page will be loaded. If the customer has previously cancelled from any of the authorization steps (step-up, EOI, sharing preferences) or authorization error occurred the authorization sequence will NOT be started and the onUnAuthorized event will be raised instead (note: customer re-sign-in will reset previous result).

With the $jc.qgcidm.config.authorization_events_enabled flag being true the following events will be handled:
- If the customer has met all requirements in terms of sharing and AAL level the onAuthorized event handler will be executed.
- If the customer has not yet reached the correct AAL level or sharing is still required BUT the customer has cancelled previously from authorization sequence the onUnAuthorized event handler will be executed.

forceAuthorizationSequence()

Starts the authorization sequence by calling $jc.qgcidm.forceAuthorizationSequence().
This method does the same as startAuthorizationSequence(...) except that it clears all previous authorization sequence cancellation and result values from storage and assumes both $jc.qgcidm.config.authorization_enabled and $jc.qgcidm.config.authorization_events_enabled to be true.
See startAuthorizationSequence(...) for more detail.

updateProfile(callback)

Sends a request to the CIDM-NEO customer attributes API to retrieve all required attributes as specified in $.qgcimd.config. By default it will also request Email and Picture even with no attributes being configured.

On receiving a response from the customer attributes API the returned result object is assigned to $jc.qgcidm.profile and subsequently the onAttributes event is fired.

logout(e)

Executes the onLogin event handler and secondly performs a clean-up of token values stored in cookies and storage ($jc.qgcidm.delStorage(...) ).

Useful neo variables

profile	
JavaScript Object	{}	
Object containing all attributes returned from the CIDM-NEO customer attributes API. Used for caching retrieved attributes.

_lastLogin
string	
null	
Last login timestamp as reflected by the current JWT.

_loginType
string	
null	
login type as reflected by the current JWT.

_auth_result
string	
authorization_result	
Constant value representing the key value of a key value pair type storage regime. Used in conjunction with $.qgcidm.getStorage.
For example: $.qgcidm.getStorage($.qgcidm._auth_result, function( result ){...})

_auth_token
string	
access_token	
Constant value representing the key value of a key value pair type storage regime. Used in conjunction with $.qgcidm.getStorage.
For example: $.qgcidm.getStorage($.qgcidm._auth_token, function( token ){...})

_release_token
string	
release_token
Constant value representing the key value of a key value pair type storage regime. Used in conjunction with $.qgcidm.getStorage.
For example: $.qgcidm.getStorage($.qgcidm._release_token, function( token ){...})

_storage_prefix	
string	
qgcidm	
Constant value representing a prefix for all key values used to store values in the profile widget storage. For example: "qgcidm_access_token"

_onAttributes
$.Callbacks() handler		
Collection of handlers set by _onAttributes.add(callback) OR $("page element").onAttributes(callback) OR $.qgcidm.onAttributes(callback)

_onAuthorized
$.Callbacks() 
handler		
Collection of handlers set by _onAuthorized.add(callback) OR $("page element").onAuthorized(callback) OR $.qgcidm.onAuthorized(callback)

_onLogin
$.Callbacks() 
handler		
Collection of handlers set by _onLogin.add(callback) OR $("page element").onLogin(callback) OR $.qgcidm.onLogin(callback)

_onLogout
$.Callbacks() 
handler		
Collection of handlers set by _onLogout.add(callback) OR $("page element").onLogout(callback) OR $.qgcidm.onLogout(callback)

_onUnAuthorized
$.Callbacks() 
handler		
Collection of handlers set by _onUnAuthorized.add(callback) OR $("page element").onUnAuthorized(callback) OR $.qgcidm.onUnAuthorized(callback)