Plugins: Guide \ Social Link 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 Link Plugin to allow your existing users to link their account to one or more social networks so they can sign in using them.

1. Add the Social Link plugin to your users' account settings

Update your user account settings 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="social_link"></div>
		
<script type="text/javascript">
 oneall.api.plugins.social_link.build("social_link", {
  'providers' :  ['facebook', 'google', 'twitter', 'yahoo'], 
  'callback_uri': 'https://app.oneall.com/social-login/',
  'user_token': 'INSERT YOUR USER_TOKEN HERE OR LEAVE BLANK'
 });
</script>

Important: If user has not yet linked any social networks, you will not have a user_token for this user. In this case leave the user_token empty, our API will create a new one. After having received the new user_token, you have to tie it to this user and include it in each subsequent call of the Social Link Plugin.

Include the user_token

The Social Link plugin will display the provider selection on your website and handle the account linking. Please have a look at the following screenshot to get an idea on how it could look like.

Social Link Example

Test your setup

If you have finished setting up your account settings 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.

2. 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

How to setup your own callback script?

In the Social Login Setup we arelady created callback script handle the logins to your website. We will now enhance this script to handle the account linking.

Multilink: The same user can link multiple social networks to one single account. For the same user, our API will always return the same user_token. The API will return a different identity_token for each of the linked social network accounts (identities).

<?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)
	{
		//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')
		{
			//http://docs.oneall.com/plugins/guide/social-login/ 
		}
		elseif ($data->plugin->key == 'social_link')
		{
			//Operation successfull
			if ($data->plugin->data->status == 'success')
			{
				//Identity linked
				if ($data->plugin->data->action == 'link_identity')
				{
					//The identity <identity_token> has been linked to the user <user_token>
					$user_token = $data->user->user_token;
					$identity_token = $data->user->identity->identity_token;

					//Next Step:
					// 1] Get _your_ $userid from _your_ SESSION DATA
					// 2] Check if the $userid is linked to this user_token: GetUserIdForUserToken($user_token) 
					// 2.1] If not linked, tie the <user_token> to this userid : LinkUserTokenToUserId($user_token, $user_id) 
					// 3] Redirect the user to the account linking page
				}
				//Identity Unlinked
				elseif ($data->plugin->data->action == 'unlink_identity')
				{
					//The identity <identity_token> has been unlinked from the user <user_token>
					$user_token = $data->user->user_token;
					$identity_token = $data->user->identity->identity_token;

					//Next Step:
					// 1] At your convenience
					// 2] Redirect the user to the account linking page
				}
			}
		}
	}
}
?>

Test your implementation

After having finished this step, you should be able to link your account to one or more social network accounts. The callback script should detect that you are either want to link a social network account (and store this link in the database) or unlink a social network account. In both cases redirect you should be redirected to the user account settings page.

4. Done!

Congratulations! You have successfully connected your website to the social networks. Your users can now sign in/up to your website with their social network account and link their existing account to one or more social networks so they can sign in using them.

Feel free to contact us if you are stuck at some point, we will be glad to help you!