Janrain

Piano integrates seamlessly with Janrain for user login and registration. To enable Janrain on your publisher account, configure your Janrain credentials inside of the Piano dashboard. Browse to the publisher dashboard, click Edit Business, click the User provider tab, enter your Janrain details and hit Save.

Setting the Type Name

Janrain allows you to setup multiple record types in their database. Typically, you will have user records. Occasionally you will have more than one database, however. When configuring Janrain in the Piano dashboard, configure the Type Name as it is in the Janrain API.

 janrain type name

The Type Name value should correspond with what is showing in Janrain between X type_name records, in this case the Type Name would be set to “user”.

Initialization

Once you have configured Janrain in the Piano dashboard, you must configure the Piano javascript to initialize it.

tp.push(["init", function() {
    tp.janrain.init({
 
        // These are the minimum fields required to configure
        // janrain inside the javascript tier. They are all
        // required fields.
        appName:  "your app name from janrain",
        appId:    "your app id from janrain",
        clientId: "your client id from janrain",
 
        // This is the janrain screen that Piano will render
        // if someone attempts to checkout while not logged in.
        // This is also the screen that we will render in the
        // case when someone attempts to go to the my account
        // component
        // optional; defaults to "signIn"
        loginRequiredScreen: "signIn",
 
        // IMPORTANT:
        // If you pass janrain.settings to tp.janrain.init, we will
        // pass these settings to janrain.settings and then append
        // the janrain javascript file to the page for you, e.g.
        // http://widget-cdn.rpxnow.com/load/your-app-name
 
        // If you have already embedded the janrain javascript
        // elsewhere on the page, do not pass any settings to
        // tp.janrain.init. We will not append the janrain
        // javascript to the page if you do not pass in any
        // settings.
        settings : {
            capture : {
                redirectUri: 'http://your url/',
                flowName: 'standard',
                flowVersion: 'HEAD',
                registerFlow: 'socialRegistration',
                setProfileCookie: true,
                keepProfileCookieAfterLogout: true,
                modalCloseHtml: 'X',
                noModalBorderInlineCss: true,
                responseType: 'token',
                returnExperienceUserData: ['displayName'],
                stylesheets: [],
                mobileStylesheets: ['styles/janrain-mobile.css']
            },
            packages: ["login", "capture"],
            language: 'en-US',
            tokenUrl: 'http://localhost/',
            tokenAction: 'event',
            borderColor: '#ffffff',
            fontFamily: 'Helvetica, sans serif',
            width: 300,
            actionText: ' '
        }
    });
}]);

If you pass settings to tp.janrain.init, we will set janrain.settings and then place the janrain widget file on the page for you, e.g. http://widget-cdn.rpxnow.com/load/your-app-name

If you have already embedded janrain's widget javascript elsewhere on the page, do not pass any settings to tp.janrain.init. We will not append janrain's widget javascript to the page if you do not pass in any settings.

Default Behavior

At this point, Piano is configured to work with Janrain. There is no need to pass the janrainCaptureToken to Piano or set the publisher user ref token for logged-in janrain users. Piano will determine whether or not the user is logged in or not, and if they are not, Piano will call:

janrain.capture.ui.renderScreen(loginRequiredScreen);

Piano registers janrain's onCaptureSessionCreated event to continue checkout, or to display the my account component.

After successful login, Piano calls janrain.capture.ui.modal.close().

If you do not use the janrain modal, you will need to close your non-modal by registering a loginSuccess callback function.

Placement Order

You must make the call to tp.janrain.init before calling tp.offer.show or tp.myaccount.show.

If you initialize janrain after you show an offer or show the My Account component, Piano will not know that janrain is configured, and it will result in an error.

// CORRECT
tp.push(["init", function() {
    tp.janrain.init({
        appName: "janrainappname",
        appId: "janrainappid",
        clientId: "janrainclientid",
        loginRequiredScreen: "signIn"
    });
    // Piano knows that janrain is initialized at this point
    tp.offer.show({
        offerId: "O1234",
        templateId: "OTABCD"
    });
}]);

This will always throw a “user must be logged in” error when attempting to checkout.

// INCORRECT
tp.push(["init", function() {
    // Piano does not know that janrain is initialized
    // at the time that it shows the offer
    tp.offer.show({
        offerId: "O1234",
        templateId: "OTABCD"
    });
    tp.janrain.init({
        appName: "janrainappname",
        appId: "janrainappid",
        clientId: "janrainclientid",
        loginRequiredScreen: "signIn"
    });
}]);

User Updates

Piano registers a webhook endpoint with janrain to receive any updates that happen on janrain's side. These updates include updates to the user's email address, first name, and last name.

Overriding loginRequired

If you do not specify a loginRequired callback, Piano will render the loginRequiredScreen for users who are not logged in prior to checking out or showing the My Account component.

If you do not want to leverage this functionality but still need janrain integration, you can override this default behavior by specifying your own loginRequired callback when showing an offer or the my account component.

tp.push(["init", function() {
    tp.janrain.init({
        appName: "janrainappname",
        appId: "janrainappid",
        clientId: "janrainclientid",
    });
    var offerConfig = {
        offerId: "O1234",
        templateId: "OTABCD"
    }
    var loginRequired = function(params) {
        // perform your custom janrain initialization here
 
        // register the onCaptureSessionCreated to continue checkout
        // after the user logs in
        janrain.events.onCaptureSessionCreated.addHandler(function() {
            // params contains the termId that the user is checking out
            // with so they don't have to select the term again
            offerConfig.termId = params.termId;
            tp.offer.show(offerConfig);
        });          
 
        // be sure to return false to prevent Piano from rendering
        // the default error screen when someone is not logged
        // in and starts checkout.
        return false;
    }
    offerConfig.loginRequired = loginRequired;
    tp.offer.show(offerConfig);
}]);

Capturing loginSuccess

If you are not using janrain's screens in their modal implementation, you will need to handle closing the janrain login or registration screen yourself. To do so, register the loginSuccess callback on showing of the offer or My Account component.

tp.push(["init", function() {
    tp.janrain.init({
        appName: "janrainappname",
        appId: "janrainappid",
        clientId: "janrainclientid",
    });
    tp.offer.show({
        offerId: "O1234",
        templateId: "OTABCDE",
        loginSuccess: function() {
            // close the custom non-modal janrain screen
 
            // if you return false from this method, we will not continue;
            // more often than not, you do not want to return false
        }
    });
    tp.myaccount.show({
        displayMode: "modal",
        containerSelector: "#my-account",
        loginSuccess: function() {
            // close the custom non-modal janrain screen
 
            // if you return false from this method, we will not continue;
            // more often than not, you do not want to return false
        }
    });
}]);

Other Methods

The tp.janrain object has other methods that are available to an integrator.

isConfigured

Calling tp.janrain.isConfigured() will return a boolean whether or not janrain has been configured in the javascript tier - i.e. whether or not tp.janrain.init has been called.

Note: tp.janrain.isConfigured() does not perform any server-side checks to determine if janrain has been configured in the Piano dashboard. It is still necessary to configure janrain integration in the dashboard prior to calling tp.janrain.init.

login

The login method is available to you to perform a janrain login using the previously configured loginRequiredScreen. This function takes a single callback parameter that will be executed after successful login.

tp.push(["init", function() {
    tp.janrain.login(function() {
        tp.offer.startCheckout({
            termId: "T12345644",
            offerId: "OABCDEF"
        });
    });
}]);

logout

The logout method is available to you to perform a janrain logout. This function takes a single callback parameter that will be executed after successful logout. This method calls janrain.capture.ui.endCaptureSession().

tp.push(["init", function() {
    tp.janrain.logout(function() {
        // do logout behavior
    });
}]);

getLoginRequiredScreen

Returns the loginRequiredScreen, defaults to signIn, which is janrain's default screen for login.