Syncronex Knowledge BaseIntegrationCircPro Subscriber Management Portal IntegrationIntegrating the CircPro Subscriber Management Portal into your WebSite

Integrating the CircPro Subscriber Management Portal into your WebSite

Quick Start Example

This article assumes you are running Newscycle Solutions' CircPro circulation system.

The Quick Start Example uses jQuery for convenience. jQuery is not a requirement for integrating the SMP into your site (but we think it's pretty convenient!)

Follow these steps to get your CircPro Subscriber Management Portal (SMP) up and running.

  1. Create an HTML page to act as the container for your portal and include the following code:
<!DOCTYPE html>
<html lang="en" xmlns="http://www.w3.org/1999/xhtml">
<head>
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <meta charset="utf-8" />
    <title>CircPro SMP QuickStart</title>
    <link rel="stylesheet" 
      href="https://stackpath.bootstrapcdn.com/bootstrap/4.3.1/css/bootstrap.min.css"
      integrity="sha384-ggOyR0iXCbMQv3Xipma34MD+dH/1fQ784/j6cY/iJTQUOhcWr7x9JvoRxT2MZw1T" 
      crossorigin="anonymous">
    <style>
        body { padding-top: 50px; }
        iframe {
            display: block;
            width: 100%;
            height: 100%;
            border: 0;
        }
        #smp-container {
            text-align: center;
            width: 800px;
            height: 600px;
            margin: 0 auto;
        }
        .unauthenticated { color: red; }
        .hidden { display: none; }
    </style>
</head>
<body>
<div class="container">
    <!-- Create a container to hold the CircPro portal -->
    <div class="hidden" id="smp-container">
        <iframe id="smp-content"></iframe>
    </div>
    <!-- Optionally create a container to hold a 'not-logged-in' 
         view/message to your users -->
    <div id="unauthenticated-view">
        <p class="text-center unauthenticated">
            You must be logged in to access your account.
        </p>
        <form>
            <div class="form-group">
                <label for="exampleInputEmail1">Email address</label>
                <input type="email" class="form-control" 
						id="exampleInputEmail1" 
						aria-describedby="emailHelp" 
						placeholder="Enter email">
            </div>
            <div class="form-group">
                <label for="exampleInputPassword1">Password</label>
                <input type="password" class="form-control" 
						id="exampleInputPassword1" 
						placeholder="Password">
            </div>
            <button id="login-submit" type="button" class="btn btn-primary">
                Login
				</button>
            <button id="login-submit-federated" type="button" 
                    class="btn btn-info">
                Federated Login
				</button>
        </form>
    </div>
</div>
<script src="https://code.jquery.com/jquery-3.3.1.min.js"></script>
<script src="https://cdn.dev.syncronex.com/libs/v1.8/syncLoginSdk.js"></script>

<script>
    // Initialize the Syncronex Login SDK
    let loginSdk = window.syncLoginSdk;
    //loginSdk.applicationOrigin = '{your application origin here}'; 
    loginSdk.debug = true;
    //loginSdk.tenantId = '{your tenantId here}';
    loginSdk.requireLegacyLogin = true;
    // Helper functions to control the UI
    let hidePortalContent = function () {
        $('#smp-container').addClass('hidden');
        $('#unauthenticated-view').removeClass('hidden');
    };
    let showPortalContent = function () {
        $('#unauthenticated-view').addClass('hidden');
        $('#smp-container').removeClass('hidden');
    };
    // Load up the container iframe with the 
	 // customer-specific CircPro portal page
    let loadPortalInFrame = function () {
        let frameContentUrl = loginSdk.applicationOrigin +
				 '/smp/circpro/pages/profile.html';
        $('#smp-content').attr('src', frameContentUrl);
    }
    // Function to run if the current user is logged in
    let handleUserIsLoggedIn = function () {
        loadPortalInFrame();
        showPortalContent();
    };
    // Function to run if current user is not logged in
    let handleUserIsNotLoggedIn = function () {
        hidePortalContent();
    };
    // jQuery initialization function. Checks the current login status
    // before showing portal or not-logged-in view
    $(function () {
        loginSdk.getLoginStatus(handleUserIsLoggedIn, 
            handleUserIsNotLoggedIn);
    });
    // Inline login setup (i.e., An Overlay Login)
    $('#login-submit').click(function () {
        let userEmail = $('#exampleInputEmail1').val();
        let userPass = $('#exampleInputPassword1').val();

        loginSdk.loginUser(userEmail, userPass, 
            handleUserIsLoggedIn, handleUserIsNotLoggedIn);
    });
    //  Encode a Customer's instance as Company and Property
    let CompanyPropertyInstance = function(tenantId) {
        let companyPropertyParts = loginSdk.tenantId.split('-');
        let companyPart = companyPropertyParts[0];
        let propertyPart = companyPropertyParts[1];

        this.company = companyPart;
        this.property = propertyPart;
    }
    // Federated login setup (i.e., original workflow )
    $('#login-submit-federated').click(function () {
        let instance = new CompanyPropertyInstance(loginSdk.tenantId);
        let thisPage = location.href;
        let thisPageEncoded = encodeURI(thisPage);
        let loginPage = loginSdk.applicationOrigin + 
         '/' + instance.company + 
         '/' + instance.property + 
         '/account/logon?op=fedauth&returnUrl=' + 
         thisPageEncoded;

        location.href = loginPage;
      });
</script>
</body>
</html>
Click to copy

Your  applicationOrigin and tenantId values are provided by Syncronex Support.  Send an email to [email protected] to request your values.

The QuickStart example assumes that you are running the CircPro Circulation system and that you already have some subscribers in syncAccess that were setup via the new start or activation workflows.  You'll need the email address and password for one of those subscribers in order to see the QuickStart example work.

Quick Start Example Explained

There are two main tasks required to integrate the SMP into your web site:

  1. Create a container <iframe> to hold the SMP content
  2. Supply a means by which subscribers can log in to your system

Create a Container for the SMP Content

The SMP is a self contained application that has been designed to run within an html <iframe>.  This allows you to preserve the look and feel of your overall website even though the SMP is technically a different web site.

Typically, you'd create a dedicated 'Account Management' page that contains the same headers, footers, styles, etc. as the rest of your site.  Then, insert an <iframe> element in the page to hold the contents of the SMP.  You can see this in the Quick Start example's html code:

<!-- Create a container to hold the CircPro portal -->
<div class="hidden" id="smp-container">
    <iframe id="smp-content"></iframe>
</div>
<!-- Optionally create a container to hold a 
     'not-logged-in' view/message to your users -->
<div id="unauthenticated-view">
    <p class="text-center unauthenticated">
        You must be logged in to access your account.
    </p>
    <!-- login form or link to federated login, etc. -->    
</div>
Click to copy

The example page sets up two <div> elements to hold the main SMP content and an 'unauthenticated' view that contains a way for the user to get signed in.  The script in the example handles checking the current user's login status (via the syncAccess Login SDK ). If the user is logged in, the script loads the SMP container by setting the src attribute on the <iframe> element:

// Function to run if the current user is logged in
let handleUserIsLoggedIn = function () {
    loadPortalInFrame();
    showPortalContent();
};

let loadPortalInFrame = function () {
    let frameContentUrl = loginSdk.applicationOrigin + 
		'/smp/circpro/pages/profile.html';
    $('#smp-content').attr('src', frameContentUrl);
}

let showPortalContent = function () {
    $('#unauthenticated-view').addClass('hidden');
    $('#smp-container').removeClass('hidden');
};
Click to copy

If the user is not currently logged in, the 'unauthenticated' container is shown instead. This is optional but helpful for your users. This also allows you to customize the messaging for your users (the built-in error message in the SMP can't be modified).  If your site has a dedicated login page, you could provide messaging here to explain to the user how to login. You can also leverage the syncAccess Login SDK directly to log the user in from credentials you get in a custom Form. See this article for more information on logging in with the SDK.

These are just suggestions. You're free to implement the integration however you like as long as you provide an <iframe> element and you ensure the user has logged in via a Syncronex login mechanism.

Getting your Subscriber Logged In to the SMP

The SMP assumes that the current user has already logged into the system via another Syncronex-provided login mechanism (i.e., syncAccess Login SDK or Federated Authentication API).  

The example provides all the script necessary to connect to and use the syncAccess Login Sdk.  The first section of code initializes the Sdk:

<script 
	src="https://cdn.dev.syncronex.com/libs/v1.8/syncLoginSdk.js">
</script>
<script>
// Initialize the Syncronex Login SDK
let loginSdk = window.syncLoginSdk;

loginSdk.applicationOrigin = '{your application origin here}';
loginSdk.debug = true;

loginSdk.tenantId = '{your tenantId here}';
loginSdk.requireLegacyLogin = true;
</script>
Click to copy

You first reference the syncAccess User Login Sdk library: <script src="https://cdn.dev.syncronex.com/libs/v1.8/syncLoginSdk.js"></script>.  Next, you have to initialize the Sdk with your customer-specific application origin and tenantId.

The applicationOrigin will typically look something like this: https://syncaccess-co-pr.stage.syncronex.com and the tenantId will look like this: co-pr.   If you don't already have your applicationOrigin and tenantId, just send an email to [email protected] and request them.

If you use the Federated Authentication API or the standard login page, you must still include the syncAccess Login Sdk in your SMP container page. The Sdk provides convenient functionality that manages the authentication status for your users regardless of login mechanism. If you're unsure of which method you're using, you can take a look at your existing 'login mechanism'.  If that mechanism involves redirecting the user to a Syncronex page, it means you're using either the Federated Authentication API or the standard login page redirect.

The Quick Start Example shows how to include the Sdk as well as how to expose both types of login mechanism.  Check out the example code for details.

We recommend that you block access to your container (that's hosting the SMP) for any users that aren't currently logged in.  The SMP provides a very basic "unauthenticated" view to your users but you'll want to implement your own in order to get more flexibility in messaging.  The default error messaging can't be changed and is only intended as a safety mechanism in the event an unauthenticated user finds her way to the SMP page.

The Quick Start Example shows you how to leverage the SyncAccess User Login Sdk to see if the current user is logged in or not.  The `getLoginStatus` function in the Sdk takes two function arguments; a function to call if/when the current user is signed in and a function to call if/when the user is not signed in.  You can tie your SMP frame loading logic into the success function and tie your unauthenticated view logic into the fail function.

// jQuery initialization function. Checks the current 
//	login status
// before showing portal or not-logged-in view
$(function () {
    loginSdk.getLoginStatus(handleUserIsLoggedIn, 
		handleUserIsNotLoggedIn);
});
Click to copy

If the current user is logged in, the handleUserIsLoggedIn function will be called which executes the logic to load the iFrame with the SMP pages and then makes the SMP container visible while hiding the login form.  Conversely, if user is not logged in, the handleUserIsNotLoggedIn function is called which simply hides the SMP container and shows the login form.  

This is just one example of how you might control your SMP, you can make your own logic as simple or as complicated as you like.

At this point, there is no built-in way to modify the styling of the SMP content itself.  We use Bootstrap v 3.x for the main SMP content and deliberately kept the styling neutral so that it wouldn't conflict with your own site's styling.  We don't currently have a way to include a custom stylesheet (we're looking at that for a future enhancement to the SMP).

If you require changes to the SMP styling, you can request a quote for a Professional Services engagement by emailing [email protected].  PS requests are reviewed and approved based on the scope of the request and current resource allocations.  Syncronex can't guarantee specific delivery timeframes for PS requests.

Conclusion

Feel free to use the Quick Start Example as a starting point for your own integration.  The only requirements are the <iframe> container in which the SMP pages are loaded and a way to ensure the user is signed in.  You can use a dedicated page like shown here, flyouts, modals, etc.  As long as you control loading the frame after you've ensured the user is logged in, you're free to create just about any UX you'd like.