Creating a registration interstitial

[julian]

What is a registration interstitial?

When a user registers for a new account, they may be presented with an intermediate step (or "intersitial") before the registration is completed. Alternatively, the interstitial can be invoked after registration.

You may use this opportunity to obtain additional information about the user for your plugin.

In this tutorial, we'll be updating the Facebook SSO plugin to capture user emails upon registration.

The filter:register.interstitial hook

The hook filter:register.interstitial is fired whenever a user registers for a new account. It is also fired if the user session contains a registration object, and in processing the interstitial page itself.

The hook signature is {data, callback}, and data contains the following:

• userData (Object) The registration data collected so far
• interstitials (Array) A collection of interstitial objects, which you can append to if necessary. An interstitial object is:
  • template (String) A template served by your plugin that will be included into the interstitial page
  • data (Object) When rendering the above template, any data needed can go here
  • callback (Function [userData, formData, callback]) When the interstitial page is completed, this callback method will be executed, with the form data included in the second parameter

In the case of Facebook SSO, we want to capture user email addresses because Facebook may not provide the correct email to us (or at all). By looking at the code, we can see that if the email is not present, we create a fake email ending with @facebook.com.

Step 1: Invoking the interstitial

Upon completion of SSO registration, we save uid and fbid into req.session.registration. Once this object is set in the user session, NodeBB will automatically forward the user to the registration interstitial:

// Require collection of email
req.session.registration = req.session.registration || {};
req.session.registration.uid = user.uid;
req.session.registration.fbid = profile.id;

Step 2: filter:register.interstitial listener

Now, we will create a new listener to the filter:register.interstitial hook, and have it add an interstitial if the email ends with @facebook.com:

Facebook.prepareInterstitial = function(data, callback) {
	// Only execute if:
	//   - uid and fbid are set in session
	//   - email ends with "@facebook.com"
	if (data.userData.hasOwnProperty('uid') && data.userData.hasOwnProperty('fbid')) {
		user.getUserField(data.userData.uid, 'email', function(err, email) {
			if (email.endsWith('@facebook.com')) {
				data.interstitials.push({
					template: 'partials/sso-facebook/email.tpl',
					data: {},
					callback: Facebook.storeAdditionalData
				});
			}

			callback(null, data);
		});
	} else {
		callback(null, data);
	}
};

To note, when registering the interstitial (data.interstitials.push...), we define the template as partials/sso-facebook/email.tpl. This tempate is defined in the plugin itself.

Secondly, the callback calls Facebook.storeAdditionalData. That method is also defined by the Facebook SSO plugin, and handles updating the user email as passed in via the interstitial page.