Progressive Profiling

Skip to end of metadata
Go to start of metadata

Progressive Profiling is used to incrementally collect profile data over time, as a relationship of trust is built between your site and the customer. Instead of creating lengthy registration forms with many required fields, you can use progressive profiling to request information from your user further down the line, and only after a certain even triggers (such as a fourth login, a visit to a specific page, or a number of shares is reached). Information is gathered unobtrusively over time while the number of user registrations stays high.

You can implement progressive profiling scenarios in several ways. One way is to add custom code to your global site configuration, that tracks the relevant events. Another method is to use Markup Extensions for displaying certain screens only if certain conditions are met. 

Best Practice - Global Configuration

Global Configuration is where you define standard Gigya definitions for your site, such as the list of enabled social providers, and where you can add your own custom code that is accessible both to Gigya's Web SDK and to your site. You can define progressive profiling scenarios by using custom JavaScript in your site's Global Configuration, which triggers a customized Profile Update screen that ask for more information.  

To set up progressive profiling, use the customEventMap parameter. You can use this to subscribe to all events across your entire site (or, your entire site group - with all necessary code defined in one place). Some examples of events you can track to trigger a progressive profiling screen include login, adding a connection, sharing, commenting, profile editing, and loading a page. When the user is logged in, with this code you have the ability to write to the their account.

Following is a code example that causes a certain screen to display on the third user login (fourth login only, not on the fifth and assumes that you have previously added the data.previousLogins field to your site's schema).

You must create new schema fields either by using the accounts.setSchema API or by mapping a new field in the UI Builder. Creating new fields using accounts.setAccountInfo may break your implementation.

{
    customEventMap: {
        eventMap: [{
            events: '*',
            args: [function(e) {
                return e;
            }],
            method: function(e) {
                if (e.fullEventName === 'accounts.login') {
                    // Increment number of logins count.
                    gigya.accounts.setAccountInfo({
                        data: {
                            numLogins: (e.data.previousLogins || 0) + 1
                        }
                    });
 
					// If this is the 4th login.
                    if ((typeof(e.data.numLogins) !== 'undefined') {
						if (e.data.previousLogins === 3) {
							gigya.accounts.showScreenSet({
								screenSet: 'Default-ProfileUpdate',
								startScreen: 'progressive-profiling-custom-screen'
							});
						}	
					}
                }
            }
        }];
    }
};
 Click here for code that fires a screen every Nth login
{
    customEventMap: {
        eventMap: [{
            events: '*',
            args: [function(e) {
                return e;
            }],
            method: function(e) {
                if (e.fullEventName === 'accounts.login') {
                    // Handle login event here.
                    var userGlobalLogins;
                    if (typeof(e.data.progressive_logins) !== 'undefined') {
                        userGlobalLogins = e.data.progressive_logins +1;
                        gigya.accounts.setAccountInfo({
                            data: {
								"progressive_logins": userGlobalLogins
                            }
                        });
                        var tester = function() {
                            var a = userGlobalLogins/6; // set N
                            if (a.toString().indexOf('.') === -1) { // If the result of userGlobalLogins divided by N is not a float, the screen fires. In this case, the screen will fire every 6th login.
                            	gigya.accounts.showScreenSet({
									screenSet: 'Default-ProfileUpdate',
									startScreen: 'progressive-profiling-custom-screen'
								});
                            }
                        };
                        tester();
                    } else {
                        userGlobalLogins = 1;
                        gigya.accounts.setAccountInfo({
                            data: {
								"progressive_logins": 1
                            }
                        });
                    }
                } else if (e.eventName === 'logout') {
                    // Handle logout event here.
                }
            }
        }];
    }
};

 

Using Markup Extensions

Screens defined using Gigya Markup Extensions can be assigned a variety of  conditions so as to make the gathering of profile information progressive and flexible. For example, one or two items of information can be gathered after each login, and again after the user is logged in for a certain period (e.g., after 10 minutes on the site).

Note that you can create all of these screens initially in the UI Builder, however, you must add your own additional logic in order to get them to perform progressively. You can do this using Gigya's Markup language via the Screen's Advanced Customization tab or via custom JavaScript to trigger the necessary screens.

How it Works

The conditional container class, gigya-container is applied to a <DIV> tag:

<div class="gigya-container">

which surrounds any fields you wish to control the display of within an HTML <FORM> tag. Attributes are added to this <DIV> tag specifying conditions relating to the display of the form's fields.

For example:

<div class="gigya-container" data-display-cap=5>

(tells the engine that this <div> element will not be displayed more than 5 times).

The <FORM> tag, inside which the data-display-cap class was nested, is set to close the screen or to open a different screen depending on the response received by <div class="gigya-container">.  Another attribute named data-auto-skip-screen sets the action to take if the screen does not display.

For example, if the attribute data-auto-skip="true" is set, it prevents the form from displaying (it will be "auto-skipped").

<form class="gigya-profile-form" data-auto-skip="true" data-on-auto-skip-screen="_finish">

 

gigya-container Conditions

 

Class gigya-container

A conditional container class that can be applied only to a <div>, which is then displayed or hidden according to various conditions.

The gigya-container class must be inside a form. The container will be displayed if all its specified conditions are true.

The class gigya-container can only be used with <div> elements.

 

Attributes that can be used to condition gigya-container:

  • data-apikeys  - A comma-separated list of API keys. The condition will be true only when the screen is loaded using one of these API keys.
  • data-after-date  - A date/time specification in ISO 8601 format, e.g., 2013-11-21T16:45:30.022+01:00. The condition becomes true if the current time is after the specified date.
  • data-before-date  - A date/time specification in ISO 8601 format, e.g., 2013-11-21T16:45:30.022+01:00. The condition becomes true if the current time is before the specified date.
  • data-condition  - A valid JavaScript Boolean expression that defines the condition for displaying based on profile fields, data fields or any other data of the page. For example:

    data-condition="profile.gender=='m' && data.newsletter==true && window.myGlobalVar == 'john'"

    The conditions to display or hide a container are evaluated after every field is modified, so for example, when the user selects his/her gender, a container that depends on that field immediately appears or disappears.

  • data-display-cap  - The total number of times this container may be displayed. The condition becomes true as long as the cap has not been reached. This attribute requires the container to have a name, and is just for registered users.
  • data-display-freq  - The minimum frequency in seconds between displaying the container. The condition becomes true after the specified time since the last display has passed. This attribute requires the container to have a name, and is just for registered users.
  • data-domains - A comma-separated list of domain names or *.domain.name (for all subdomains of the parent domain). The condition becomes true only when the screen is loaded on a matching domain.
  • data-empty-fields - Indicates which of the fields contained in the container are required to have data. This can be a list of field names or the special value "*" (asterisk), which means all fields within the container are required. The condition will become true if any of the required fields are null or empty.

    Note that this attribute is unrelated to the setting of required fields in the site's schema, it only dictates whether the current container should be displayed based upon whether data is missing from any, all, or only the specified field(s) contained within it.

    When using required fields, whether they are required by the site schema or you designate them as required using HTML markup; these fields can not be hidden using conditional workflows. Any required fields are always displayed in the current screen.

  • data-login-identities - A comma-separated list of provider names. The container will be displayed if any of the providers exist and allow login. Can also use the following special values:
    • site : The user is a registered site user.
    • site-only : Only registered site users.
    • social : Any social network identity.
    • social-only : Only social network identities.
    • site-and-social : The user has a site identity and a social network identity.
    • + : Use the "+" sign to indicate that a condition or set of conditions are required: "+site, +social" indicates a user who has a site account and (&&) a connected social network (same as 'site-and-social').  
  • data-prob : A probability value in the range 0-1 that the condition will be true. 

Form Attributes

 

Attributes

The <form> element accepts several attributes, all attributes are optional. Some of the form attributes may override the corresponding attribute defined in the screen-set declaration.

To reference a screen from a different screen-set use the format <another-screen-set>screen-ID. To open another screen-set without specifying a screen, use the format <another-screen-set/>. If the requested screen is within the currently loaded screen-set (collection) then the screen ID is sufficient. 

The form attributes are defined within the <form> tag, for example:

<form class="gigya-login-form" data-on-success-screen="welcome-screen">  ...  </form>

The available attributes:

  • id - The form's unique identifier. If not specified then the ID of the form is its class name.
  • data-auto-skip - A boolean attribute with a default value "false". When the value is set to "true" and all the required fields in the form have data (from the database), the form is automatically skipped and behaves as if it was successfully submitted and processed. Gigya loads the data-on-success-screen if defined, or finishes the flow and hides the screen-set. The data-auto-skip logic also takes into consideration the data-empty-fields settings, so a screen may not be skipped if it has a container that has missing required fields and passes all other defined conditions (so the container is visible).
    Note: This attribute is mostly relevant to the gigya-profile-form, in a case when this form is used after social registration to fill in required fields. If this attribute is set to "true" and all the required fields are available (from the social data), the screen is skipped and the registration process completes successfully.
  • data-on-auto-skip-screen - When specified, this attribute overrides the data-on-success next screen attribute and allows specifying a different next screen when the form is successfully submitted vs. when the screen is auto-skipped. If this attribute is not specified then the next screen for both cases is determined by the data-on-success attribute.
  • data-on-screenset-skipped-screen - Indicates the next screen to display when a screen in a different screen-set was skipped, returning control to the current screen-set.
  • data-on-success-screen - Defines which screen to switch in case of successful submission and processing of the form. If not specified, after successful processing of the form, the flow finishes and Gigya hides the screen-set (see also Removing the Screen-set section). 
    Weighted next screens are also supported. This means that only one of the defined screens will be selected randomly, with probability distributed according to the weight of each possible next screen. The extended format will be a comma-separated list of "<next screen>:". For example:

    data-on-success="extra_screen_one:3,extra_screen_two:5"

    If a weight is not specified then the default weight is "1".

     

Attributes that override the parallel screen-set attributes:

  • data-on-missing-loginid-screen - A screen to go to in order to add a login-identifier (e.g., email) following a Social Login, if required by site policy.

 

Progressive Profiling Example Code

In the following example code, there is a single screen-set, screen-set-a, containing four screens: edit-profile1, edit-profile2, edit-profile3 and edit-profile4.

Fields used in these screens can be propagated from the profile object or the data object.

Note that you must define data object fields before they can be used in screens. 

To define fields in the data object use accounts.setSchema or add the fields to a screen in the Screen-Sets UI Builder (a dummy (unused) screen may be used) and map them in the site schema. If you want to run this example you will need to create these fields first.

The screens used in this example invite users to enter data in three pre-defined fields:

  • data.company
  • data.jobTitle
  • data.companySize

First Screen: edit-profile1

This screen requests entry of the user's company.

  • Screen is opened when screen-set-a is displayed.
  • Screen will be auto-skipped if the user has previously entered their company.
  • If auto-skip applies, then screen edit-profile2 is opened.
  • If the screen was not auto-skipped, then a successful response from the user closes the entire screen-set.

Second Screen: edit-profile2

This screen requests the user's job title.

  • Screen is opened by screen edit-profile1 when it (edit-profile1) is auto-skipped.
  • This screen will be auto-skipped if the user has previously entered their job title.
  • If auto-skip applies, then screen edit-profile3 is opened instead.
  • If auto-skip is not applied, then a successful response from the user closes the entire screen-set.

Third Screen: edit-profile3

This screen requests that user select the size of their company.

  • Screen is opened by screen edit-profile2 when it is auto-skipped.
  • Screen will be auto-skipped if the user has previously entered a company size.
  • If auto-skip applies, then screen edit-profile4 is opened.
  • If auto-skip is not applied, then a successful response from the user closes the entire screen-set.

 

The above example uses the following code:

 

 Show/Hide
<html>
    <head>
    <title>Gigya Accounts Test</title>
     <SCRIPT type="text/javascript" lang="javascript" 
       src="http://cdn.gigya.com/JS/gigya.js?apikey=3_6bD3U8x9OACU1h-f63LdTg6jDenkZZV21PRcziMYJair5Riu3EtAdqc9sdvemiDr">
     </SCRIPT>
       </head>
<body>
      <script type="text/javascript">
          //Load the screenset, starting with screen edit-profile1
          gigya.accounts.showScreenSet({ screenSet: 'screen-set-a', startScreen: 'edit-profile1' });
      </script>
    <!-- ScreenSet code begins -->
    <div class="gigya-screen-set" id="screen-set-a" data-width="500" data-height="600" style="display: none">
        <!-- Profile update Screen -->
        <div class="gigya-screen" id="edit-profile1" data-width="360" data-height="500" data-caption="Question 1" > 
                <!-- If you run this example then you must log in first -->
                 <a href="#" onclick="gigya.accounts.showScreenSet({screenSet:'screen-set-a', startScreen:'login-screen'});">Login</a> 
           <!-- if no data entry is required, this screen will not be displayed and the screen-set will auto-skip to edit-profile2 -->
            <form class="gigya-profile-form" data-auto-skip="true" data-on-success-screen="_finish" data-on-auto-skip-screen="edit-profile2">  
                 <!-- gigya-container will not display if data.company has data -->
                   <div class ="gigya-container" data-empty-fields="data.company">
                     First name: <input type="text" name="profile.firstName" disabled><br />
                     Last name: <input type="text" name="lastName" disabled><br /> 
                     Email: <input style="margin-left:31px" type="text" name="email" disabled><br />  
                     Company: <input style="margin-left:5px" type="text" name="data.company" placeholder="Company name"><br />
                   </div>            
                   <h4>Enter a company, press submit and then refresh the screen to restart the display.</h4>
                <input type="submit" value="submit" style="float: right;">
             </form>
          </div> 
          <div class="gigya-screen" id="edit-profile2" data-width="360" data-height="500" data-caption="Question 2"> 
             <!-- if no data entry is required, this screen will not display and the screen-set will auto-skip to edit-profile3 -->          
             <form class="gigya-profile-form" data-auto-skip="true" data-on-success-screen="_finish" data-on-auto-skip-screen="edit-profile3">  
                 <!-- gigya-container will only be displayed if there are empty fields -->
                 <div class ="gigya-container" data-empty-fields="*" >
                   First name: <input type="text" name="profile.firstName" disabled><br />
                   Last name: <input type="text" name="lastName" disabled><br /> 
                   Email: <input style="margin-left:31px" type="text" name="email" disabled><br />  
                   Company: <input style="margin-left:5px" type="text" name="data.company"><br />
                   Job Title: <input type="text" style="margin-left:12px" name="data.jobTitle" placeholder="Enter your job title"><br />
                 </div>            
                 <h4>Enter a job title, press submit and then refresh the screen to restart the display</h4>
                <input type="submit" value="submit" style="float: right;">
             </form>
          </div>
          <div class="gigya-screen" id="edit-profile3" data-width="360" data-height="500" data-caption="Question 3"> 
                <!-- if no data entry is required, this screen will auto-skip to edit-profile4 without being displayed -->
                  <form class="gigya-profile-form" data-auto-skip="true" data-on-success-screen="_finish" data-on-auto-skip-screen="edit-profile4"> 
                  <!-- gigya-container will only be displayed if there are empty fields --> 
                    <div class ="gigya-container" data-empty-fields="*">
                       First name: <input type="text" name="profile.firstName" disabled><br />
                       Last name: <input type="text" name="lastName" disabled><br /> 
                       Email: <input style="margin-left:31px" type="text" name="email" disabled><br />  
                       Company: <input style="margin-left:5px" type="text" name="data.company" > <br />
                       Job Title: <input style="margin-left:12px" type="text" name="data.jobTitle"> <br />
                         <p><h4>What is the size of your company?</h4></p>
                         <select name="data.companySize" data-display-name="ageGroup">
                           <option value="">Select a size range</option>
                           <option value="0-50">0-50</option>
                           <option value="51-250">51-250</option>
                           <option value="251-1500">251-1500</option>
                           <option value="1500-5000">1500-5000</option>
                           <option value="Over 5000">Over 5000</option>
                          </select>
                       </div>      
                      <h4>After submitting data, refresh the screen to restart the display</h4>
                   <input type="submit" value="submit" style="float: right;">    
                 </form>
           </div>
           <div class="gigya-screen" id="edit-profile4" data-width="360" data-height="500" data-caption="End of Example"> 
             <!-- This form clears the input fields -->
                 <form class="gigya-profile-form" id="endForm" data-on-success-screen="edit-profile1"> 
                    <div class ="gigya-container">
                       First name: <input type="text" name="profile.firstName" disabled><br />
                       Last name: <input type="text" name="lastName" disabled><br /> 
                       Email: <input style="margin-left:31px" type="text" name="email" disabled><br />  
                       Company: <input style="margin-left:5px" id="company" type="text" name="data.company" ><br />
                       Job Title: <input type="text"  style="margin-left:12px" id="jobTitle" name="data.jobTitle"> <br />
                       Company Size: <input type="text" id="companySize" name="data.companySize"> <br />
                         <h4>The progressive example is now complete, click Clear Fields and refresh the screen to restart the display</h4>
                     </div>      
                   <input type=button value="Clear Fields" onClick="javascript: document.getElementById('company').value = '';document.getElementById('jobTitle').value = '';
    document.getElementById('companySize').value = ''; document.getElementById('hidden').click();"> 
                           <input type="submit" id="hidden" style="visibility:hidden">
                </form>
            </div>
  <!-- Login Screen -->
        <div class="gigya-screen" id="login-screen" data-width="365" data-height="565" data-caption="Login">
            <h2>Login with Your Social Identity and then refresh the screen:</h2>
            <div class="gigya-social-login">
                <param name="buttonsStyle" value="fullLogo">
                <param name="width" value="313">
                <param name="height" value="160">
                <param name="showTermsLink" value="false">
                <param name="hideGigyaLink" value="true">
            </div>
       </div>
   </div>
  <!-- ScreenSet code end -->
</body>
</html>

Notes:

In order to make the above code work in your environment, please note:

  • The API key in the sample will only work on http://localhost/...
  • To load the page from your domain, modify the value of the "APIKey" field in the code to your own Gigya API Key. A Gigya API Key can be obtained from the Site Dashboard page on Gigya's website. Please make sure that the domain from which you are loading the page is the same domain name that you used for generating the API Key.
  • If you are using https, be sure to further adjust the js API url to: https://cdns.gigya.com/JS/gigya.js?apikey=<Your_API_Key>.

 

Markup Progressive Profiling Working Example

Please see the working example here.