Plugins: Guide \ Social Login Integration

This page is part of our step-by-step tutorial guide for implementing our Social Login and Social Link plugins with a web site that already has users with accounts.

In this part we will explain you how to deploy the Social Login Plugin to easily let new users sign up for an account on your site by using their existing accounts from over twenty different social networks such as Facebook, Google, Twitter, Yahoo, Hotmail and LinkedIn.

In this section we are assuming that you have:
  1. Added a table to your database to store the user_token
  2. Added a simple callback script to your system.
If your system is not ready yet, you might want to read the Website Setup Guide first.

1. Include our Social Library in the head section of your page

The social library contains the javascript functions required by our plugins. The library has to be included once in the <head> ... </head> section of your website. Do not include the library more than once.

The following code is only an example, you have to use your custom code build with one of the wizards. 

	<script type="text/javascript">
	 var oneall_js_protocol = (("https:" == document.location.protocol) ? "https" : "http");
	 document.write(unescape("%3Cscript src='"+oneall_js_protocol+"://oneall.api.oneall.com/socialize/library.js' type='text/javascript'%3E%3C/script%3E"));
	</script>

2. Add the Social Login plugin to your sign-up/registration page

Update your registration page and insert the following code at the place where you would like the social networks to be displayed. When building the code with the plugin wizard, use the callback_uri to the script created in the Website Setup.

The following code is only an example, you have to use your custom code build with the Social Login Wizard. 

	<div id="oa_social_login_container"></div>
		
	<script type="text/javascript">
	 oneall.api.plugins.social_login.build("oa_social_login_container",{
	  providers : ["facebook", "google", "twitter", "yahoo"],
	  callback_uri: "https://app.oneall.com/social-login/" 
	 });
	</script>

The Social Login plugin will display the provider selection on your website and handle the login with social network accounts. Please have a look at our Signup Page to get an idea on how it could look like.

The UI goal should be that users can easily identify that they can signup with their social network account, but that users without a social network account can continue to register normally without being confused.

Test your setup

If you have finished setting up your registration page, do a first test by clicking on one of the social network providers. You should be prompted to login with your social network account, then being redirected to the callback_uri and see a message like Connection token received: 7a559a39-51a5-4f21-92aa-cc880da2233f.

3. Add the Social Login plugin to your sign-in/login page

Update your login page and insert the following code at the place where you would like the social networks to be displayed. When building the code with the plugin wizard, use the callback_uri to the script created in the Website Setup.

This will work both for existing users of your site that have attached a social network to their account and new users, who will be able to sign up using their social network account (using the same flow as above).

In addition to your main signin page, you may also have a signin user interface in your home page or elsewhere. You should ideally provide an option to sign in using a social network in every place you provide a traditional signin option.

The following code is only an example, you have to use your custom code build with the Social Login Wizard. 

	<div id="oa_social_login_container"></div>
		
	<script type="text/javascript">
	 oneall.api.plugins.social_login.build("oa_social_login_container",{
	  providers : ["facebook", "google", "twitter", "yahoo"],
	  callback_uri: "https://app.oneall.com/social-login/" 
	 });
	</script>

Please have a look at our Signin Page to get an idea on how it could look like.

The UI goal should be that users can easily identify that they can signin with their social network account, but that users without a social network account can continue to signin normally without being confused.

4. Implement the callback script

Once the user has selected a social network (like for example Facebook), he will be asked to sign in with this account. If the user successfully authenticates, he will be redirected to the callback_uri that you specified in the plugin parameters.

The callback_uri is an URL to a script on your server. This script contains a few lines of code that extract the POST parameter connection_token and fetch the user profile data by sending a request to our API Connections Resource.

Callback Script Flow Callback Script Handler

How to setup your own callback script?

In the Website Setup, we created a very simple callback script to test the integration of the plugins. 

<?php

//Check if we have received a connection_token
if ( ! empty ($_POST['connection_token']))
{
  echo "Connection token received: ".$_POST['connection_token'];
}
else
{
  echo "No connection token received";
}

?>

We now replace this script with a working version. 

<?php

//Check if we have received a connection_token
if ( ! empty ($_POST['connection_token']))
{
	//Get connection_token
	$token = $_POST['connection_token'];

	//Your Site Settings
	$site_subdomain = 'REPLACE WITH YOUR SITE SUBDMOAIN';
	$site_public_key = 'REPLACE WITH YOUR SITE PUBLIC KEY';
	$site_private_key = 'REPLACE WITH YOUR SITE PRIVATE KEY';

	//API Access domain
	$site_domain = $site_subdomain.'.api.oneall.com';

	//Connection Resource
	//http://docs.oneall.com/api/resources/connections/read-connection-details/
	$resource_uri = 'https://'.$site_domain.'/connections/'.$token .'.json';

	//Setup connection
	$curl = curl_init();
	curl_setopt($curl, CURLOPT_URL, $resource_uri);
	curl_setopt($curl, CURLOPT_HEADER, 0);
	curl_setopt($curl, CURLOPT_USERPWD, $site_public_key . ":" . $site_private_key);
	curl_setopt($curl, CURLOPT_TIMEOUT, 15);
	curl_setopt($curl, CURLOPT_VERBOSE, 0);
	curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
	curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, 1);
	curl_setopt($curl, CURLOPT_FAILONERROR, 0);

	//Send request
	$result_json = curl_exec($curl);

	//Error
	if ($result_json === false)
	{
		//You may want to implement your custom error handling here
		echo 'Curl error: ' . curl_error($curl). '<br />';
		echo 'Curl info: ' . curl_getinfo($curl). '<br />';
		curl_close($curl);
	}
	//Success
	else
	{
		//Close connection
		curl_close($curl);
		
		//Decode
		$json = json_decode ($result_json);

		//Extract data
		$data = $json->response->result->data;

		//Check for plugin
		if ($data->plugin->key == 'social_login')
		{
			//Operation successfull
			if ($data->plugin->data->status == 'success')
			{
				//The token of the user that signed in/up using his social network account
				$user_token = $data->user->user_token;
			
				// 1] Check if you have a userID for this token in your database
				$user_id = GetUserIdForUserToken($user_token); 
				
				// 2.1] If the userID is empty then this is the first time that this user signs in
				if ($user_id === null)
				{
					// 2.1.1] Create a new account (optionally display a form to collect  more data about the user). 
					// Insert you proprietary account creation code here.
					
					// 2.1.2] Attach the user_token to the userID of the created account.
					LinkUserTokenToUserId ($user_token, $user_id);
				}
				// 2.2] If you DO have an userID for the user_token then this is a returning visitor
				else
				{					
					// 2.2.1] The account already exists			
				}
				
				// 3] You either created a new user or read the details of an existing user from your database
				// 3.1] Setup your session/cookies to login the user
				// 3.2] Forward the user to his account dashboard				
			}
		}
	}
}
?>

Test your implementation

After having finished this step, you should be able to create a new account on your website by using your social network account. The callback script should detect that you are either a new visitor (and create a new account for you) or a returning visitors and in both cases redirect you to the user dashboard.

5. Next Step

Continue with the integration of the Social Link Plugin to allow your existing users to tie their account to a social network.