Skip to main content
Skip table of contents

Confirm a User's Logged-in Status or Provide a Registration or Login Form

This article is about implementing SSO for Emplifi Ratings & Reviews widgets. For implementing SSO for the Emplifi platform, see Single Sign-on (SSO).

Fill out the userDataFn to confirm a user's logged-in status or provide a registration or login form:

Steps:

  1. Familiarize yourself with the function reference for this step, which covers the userDataFn and ssoRegDone functions.

  2. Inside the userDataFn function, add code to check the user's logged-in status.

  3. If the user is not logged in, provide a registration or login form.
    (info) Email Address Verification
    When a user registers with your site during the content submission process, you should call ssoRegDone only after the user's email address is verified to your satisfaction. Emplifi understands this call as your authorization to submit the content. If you only want to allow confirmed email addresses, wait to call the ssoRegDone function until after the user confirms their email address.

  4. When the user is logged in, generate the userDataToken, which is a JWT token you'll need to compute on the server side using your site's authKey. The authKey is available in your site's settings area.
    For details on the contents of the userDataToken, see the function reference for ssoRegDone.

  5. From the PDP, make a callback to the ssoRegDone function with the userDataToken.

    This callback can be in the userDataFn function, but it's not required to be there. You just have to call ssoRegDone whenever you're done logging in the user. It's asynchronous, so you can handle this in whatever way you need.

    The callback looks like this:

    CODE
    TurnToCmd('ssoRegDone', { context: contextObj, userDataToken: userToken });

After you finish this step, the userDataFn function might be structured something like this:

CODE
var turnToConfig = {
    ...
    sso: {
        userDataFn: function(contextObj){
          // Check the user's logged-in status.
          // YOUR CODE HERE

          // If the user is not logged in, provide a registration or login form.
          // If the user is logged in, generate the userDataToken.
          // YOUR CODE HERE
          // Assign the token to use it in the ssoRegDone callback.
          var userToken = // YOUR CODE HERE

          // Make a callback to the Emplifi ssoRegDone function with the userDataToken.
          TurnToCmd('ssoRegDone', { context: contextObj, userDataToken: userToken });
        },
    }
}

Examples and functions reference

userDataToken generation example

Here is an example implementation of a server-side call to retrieve user data and generate the JWT userDataToken. The key used in the example is aaa-aaa. In a real implementation, it would be your site's authKey. This example is in PHP, but you are free to use Java or C# or whatever backend language your site uses on the server side.

userDataToken generation example
CODE
use \Firebase\JWT\JWT;

namespace EmplifiSSO;

class User {
        // fields for holding user information from your site
        public $username;
        public $password;
        public $firstName;
        public $lastName;
        public $nickName;
        public $emailAddress;
        public $userAuthToken;

        public function isLoggedIn() {
        return (isset($this->username) && isset($this->password));
        }

        /**
        * For illustrative purposes user details are passed in from a controller. In a live    
        *  environment these will be stored by your system.
        */
        public function setUserDetails($data) {
            $this->firstName = $data['firstName'];
            $this->lastName = $data['lastName'];
            $this->nickName = $data['nickName'];
            $this->emailAddress = $data['email'];
            $this->userAuthToken = $data['userAuthToken'];
        }

        /**
        * Use username/password to authenticate user and retrieve personal data.
        *  In this example, any username and password are accepted, but in a live example
        *  you should implement authentication logic.
        */
        public function logUserIn($username, $password, $userInfo) {
            $this->username = $username;
            $this->password = $password;
            $this->setUserDetails($userInfo);
            return $this->buildUserToken('aaa-aaa');
        }

        /**
         * User token is an encrypted set of user details that will be used by Emplifi's system to 
         *  identify who is logged in. $siteAuthKey comes from site settings
         *  and is different for each site.
         */
        public function buildUserToken($siteAuthKey) {
            // build an array with the required user fields
            $userData = array (
                "fn" => $this->firstName,
                "ln" => $this->lastName,
                "nn" => $this->nickName,
                "e" => $this->emailAddress,
                "ua" => $this->userAuthToken,
                "iss" => "Emplifi",        // issuer should always be Emplifi
                "exp" => time() + 86400   // current Unix timestamp (in seconds), plus 24 hrs in secs
            );

            return JWT::encode($userData, $siteAuthKey, 'HS256');
        }
}

USERDATAFN(CONTEXTOBJ) function

This function is called by Emplifi Ratings & Reviews code to request information about the current user. The operation is handled asynchronously, so this function does not have a return value. When SSO verification or login completes, your code should make a callback to the ssoRegDone function.

USERDATAFN(CONTEXTOBJ) function reference table

Parameter

Description

contextObj

Encrypted state of the user's in-progress action at the time SSO verification or login was triggered. This data should be included in the callback unaltered.

The contextObj is encoded in Base-64. Although it should not be modified, if you need more information you can decode it to read the following fields:

  • action: identifies the current user action by one of the following values:

    • REVIEW_CREATE

    • QUESTION_CREATE

    • ANSWER_CREATE

    • REPLY_CREATE

    • PROFILE_ACCESS

    You can use the action field value to display appropriate messaging on your login and registration screens.

  • sku: the product SKU relevant to the request for logged-in profile data. This will typically be the SKU from the Product Detail Page that the user is browsing.

  • rating: if the logged-in data request was triggered by a click on a star-rating in order to start a product review, this contains the rating value (1-5) that was selected. Otherwise this field will not be present.

Return value

There is no return value

SSOREGDONE function

When logged-in status is verified or login completes, this function is called by your code to resume the user's in-progress action (such as submitting a review). The function is provided for your use via the TurnToCmd object.

SSOREGDONE function

Parameter

Description

userDataToken (String)

A JWT token generated by your site. If SSO verification or login is unsuccessful, the value of userDataToken should be null. If SSO verification or login succeeds, the token should contain the following data formatted as an encrypted JSON String:

  • ua: user auth token -- a String that uniquely identifies the user on your site. This will be used as a key to synchronize the user's data between your site and Emplifi Ratings & Reviews.

    • Required.

    • Maximum length: 255 characters.

  • fn: first name -- the user's first name as a String.

    • Not required if nn is passed.

    • Maximum length: 255 characters.

  • ln: last name -- the user's last name as a String.

    • Not required if nn is passed.

    • Maximum length: 255 characters.

  • nn: nickname -- a display name that will be used instead of first and last names.

    • Not required if fn and ln are passed.

    • Minimum length: 5 characters.

    • Maximum length: 255 characters.

  • e: email -- the user's email address as a String.

    • Required.

    • Maximum length: 255 characters.

  • iss: issuer -- a String with the value "TurnTo".

    • Required.

  • exp: expiration -- a timestamp, in seconds, indicating when the token expires.

    • Required.

context (String)

The encrypted data passed to userDataFn as the contextObj argument. This should not be altered by your code.

Return value

There is no return value.

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.