Turnkey Plugins \ Social Login for WordPress Fork on Github

1. Installation

Automatic Installation

  1. Login to your WordPress blog as administrator,
  2. Click on Plugins in the left navigation panel,
  3. Click on Add New at the top of the page,
  4. Enter oneall social login in the search box and click on Search Plugins,
  5. Look for Social Login and click on Install Now.

Manual Installation

  1. Download the latest version of the Social Login Plugin here: WordPress Social Login,
  2. Upload the plugin folder to the /wp-content/plugins/ directory of your WordPress website,
  3. Login to your WordPress blog as administrator,
  4. Click on Plugins in the left navigation panel,
  5. Activate the plugin.

2. Setup

After having installed Social Login on your WordPress blog you have to enter your API credentials and you must setup the social networks that you would like to use.

a. How to obtain my API Credentials?

  1. Login to your existing OneAll account or alternatively create a new account.
  2. Click on Sites in the left navigation bar,
  3. Click on the name of your site (If you do not have a site yet, please create a new site first),
  4. Copy & paste the API Credentials into the Social Login settings in your WordPress admin area.

b. How to setup the Social Networks?

Many social networks require that the webmasters register their websites before being able to use more advanced features. To be able to use some of the social networks (e.g. Facebook & Twitter) you will have to register your blog.

This process is straightforward and takes only a couple of minutes. It has to be done only once for each provider and we will guide you through this process. To setup your providers, please login to your OneAll account, go to the dashboard and click on the Social Networks link of your Site.

3. Actions, Hooks & Filters

The codes in the following examples must be added to the end of the functions.php file of your WordPress theme. By doing so your changes will not be overwritten when you install a new version of Social Login. You can find this file in your WordPress admin area under Appearance \ Editor \ Theme Functions (functions.php)

a. How to store additional data retrieved from a social network profile?

The standard WordPress database does not have the required tables/fields to store the complete user profile retrieved from the social networks. To store the full user profile you must extend the structure of your database and then use an action like this: 

	//Handle data retrieved from a social network profile
	function oa_social_login_store_extended_data ($user_data, $identity)
	{
		// $user_data is an object that represents the newly added user
		// The format is similar to the data returned by $user_data = get_userdata ($user_id);

		// $identity is an object that contains the full social network profile
		
		//Example to store the gender
		update_user_meta ($user_data->ID, 'gender', $identity->gender);
	}

	//This action is called whenever Social Login adds a new user
	add_action ('oa_social_login_action_after_user_insert', 'oa_social_login_store_extended_data', 10, 2);

b. How to store additional data in BuddyPress Xprofile fields?

	//Store data retrieved from a social network profile in BuddyPress Xprofile fields
	function oa_social_login_store_xprofile ($user_data, $identity)
	{
	  // $user_data is an object that represents the newly added user
	  // The format is similar to the data returned by $user_data = get_userdata ($user_id);
	 
	  // $identity is an object that contains the full social network profile
	   
		//The following line is required to initialise the BuddyPress table names
		do_action('bp_setup_globals');
	  
	  //Example to store the firstname/lastname
		xprofile_set_field_data ('First Name', $user_data->ID, $identity->name->givenName);
		xprofile_set_field_data ('Last Name', $user_data->ID, $identity->name->familyName);
	}
	add_action( 'oa_social_login_action_after_user_insert', 'oa_social_login_store_xprofile', 10, 2);

c. How to allow only logins from a specific email address?

	//Verify the email address of a new user
	function oa_social_login_restrict_new_user_email ($user_email)
	{
		//Only users with social network accounts having an email address ending in @gmail.com may register
		if ( ! preg_match ('/@gmail\.com$/i', trim ($user_email)))
		{
			trigger_error ('This email address may not be used to register', E_USER_ERROR);
		}
		return $user_email;
	}

	//This filter is applied to the email addresses of new users
	add_filter('oa_social_login_filter_new_user_email', 'oa_social_login_restrict_new_user_email');

d. How to use the email address as user login?

To make sure that you receive the email addresses from your users you should also enable the following option in the Social Login settings in your WordPress admin area: If the user's social network profile has no email address, should we ask the user to enter it manually? 

	//Use the email address as user_login
	function oa_social_login_set_email_as_user_login ($user_fields)
	{
		if ( ! empty ($user_fields['user_email']))
		{
			if ( ! username_exists ($user_fields['user_email']))
			{
				$user_fields['user_login'] = $user_fields['user_email'];
			}
		}
		return $user_fields;
	}

	//This filter is applied to new users
	add_filter('oa_social_login_filter_new_user_fields', 'oa_social_login_set_email_as_user_login');

e. How to set a custom role for new Social Login users?

	//Set custom roles for new users
	function oa_social_login_set_new_user_role ($user_role)
	{
		//This is an example for a custom setting with one role
		$user_role = 'author';
		
		//This is an example for a custom setting with two roles
		$user_role = 'author editor';

		//The new user will be created with this role
		return $user_role;
	}

	//This filter is applied to the roles of new users
	add_filter('oa_social_login_filter_new_user_role', 'oa_social_login_set_new_user_role');

f. How to allow existing users to login with Social Login but disable new registrations?

With this filter, existing users can link their social network accounts to their existing WordPress account and then login with these social network accounts. New users however cannot signup using a social network account. 

	//Disable registrations using Social Login
	function oa_social_login_disable_registrations ($email)
	{
		if ( ! email_exists ($email))
		{
			trigger_error ('Registrations using Social Login have been disabled', E_USER_ERROR);
		}
		return $email;  
	}
	
	//This filter will be applied when new users are registering using social login
	add_filter('oa_social_login_filter_new_user_email', 'oa_social_login_disable_registrations');

g. How to set custom roles based on the URL where the users sign up?

This filter can be useful if you have two different registration pages, for example one for employers and one for candidates. In this case you can use the following filter to assign new users a role based on the page where they signed up. 

	//Set custom roles for new users
	function oa_social_login_set_new_user_role_url_based ($user_role)
	{
		//Read the current url
		$current_url = oa_social_login_get_current_url():
	    
		//For example: http://www.your-website.com/employer-signup/
		if (strpos ($current_url, '/employer') !== false)
		{
			return 'employer';
		}
		
		//For example: http://www.your-website.com/candidate-signup/
		if (strpos ($current_url, '/candidate') !== false)
		{
			return 'candiate';
		}
		
		//Default
		return $user_role;
	}

	//This filter is applied to the roles of new users
	add_filter('oa_social_login_filter_new_user_role', 'oa_social_login_set_new_user_role_url_based');

h. How can I use my own CSS to customize Social Login? Custom CSS Required

To customize Social Login you first of all have to create a new CSS file on your server and then you must use the following filter to include the CSS file in the plugin. 

 //Use a custom CSS file with Social Login
 function oa_social_login_set_custom_css ($css_theme_uri)
 {
  //Replace this URL by an URL to a CSS file on your own server
  $css_theme_uri = 'http://assets.oneallcdn.com/css/api/socialize/themes/buildin/connect/large-v1.css';
		
  // Done
  return $css_theme_uri;
 }	 
 add_filter('oa_social_login_default_css', 'oa_social_login_set_custom_css');
 add_filter('oa_social_login_widget_css', 'oa_social_login_set_custom_css');
 add_filter('oa_social_login_link_css', 'oa_social_login_set_custom_css');

i. Can I hide the regular WordPress login form and only use Social Login?

To hide the regular WordPress login form you need to add the following code to the functions.php file of your WordPress theme. Before adding this code please make sure that you can login as administrator using Social Login. 

	//Hides the regular WordPress login form
	function oa_social_login_hide_wordpress_login_form ()
	{ 
		?>
			<style type="text/css">
				#login form p {display: none;}
			</style>
		<?php
	}
	add_action( 'login_enqueue_scripts', 'oa_social_login_hide_wordpress_login_form');

j. How can I redirect Social Login users to a custom url?

For more advanced redirections you can use a filter to customize the redirection url. Please note that the filter will override the basic redirection settings made in the Social Login settings in your WordPress admin area. 

    //Customizes the page to redirect users to after having connected with Social Login
    function oa_social_login_set_redirect_url ($url, $user_data)
    {
        // $user_data is an object that represents the current user
        // The format is similar to the data returned by $user_data = get_userdata ($userid);
        // https://codex.wordpress.org/Function_Reference/get_userdata
        
        // Redirects users to http(s)://www.your-wordpress-blog.com/members/%user_login%
        return  get_site_url(null, '/members/' . $user_data->user_login); 
    }

    // Applies the redirection filter to users that register using Social Login
    add_filter('oa_social_login_filter_registration_redirect_url', 'oa_social_login_set_redirect_url', 10, 2);
    
    // Applies the redirection filter to users that login using Social Login
    add_filter('oa_social_login_filter_login_redirect_url', 'oa_social_login_set_redirect_url', 10, 2);

4. Shortcodes

Since Version 2.5 WordPress supports so called Shortcodes. These codes can be used to manually embed Social Login into your blog posts. The following shortcodes are included with Social Login:

a. Social Login Shortcode

This shortcode will display Social Login and allow users to login with their social network accounts. Please note that Social Login is only displayed for users that are not logged in. 

[oa_social_login]

Alternatively you can also use the following PHP code which will produce the same result: 

<?php do_action('oa_social_login'); ?>

b. Social Link Shortcode

The Social Login plugin for WordPress also includes our Social Link service that allows users to manually link/unlink social network accounts to/from their WordPress account.

The following shortcode can be used to embed Social Link. Please note that Social Link is only displayed for users that are already logged in. Social Link will not be displayed for guests. 

[oa_social_link]

Alternatively you can also use the following PHP code which will produce the same result: 

<?php do_action('oa_social_link'); ?>

c. Conditionally display content

Social Login also includes shortcodes to conditionally display content for users that have (not) logged in with a social network account. The content between the shortcode will only be displayed if the defined condition is met. 

		[oa_social_login_test is_social_login_user="true"]
			This content is displayed only if the user IS logged in AND has used Social Login to login.
		[/oa_social_login_test]

		[oa_social_login_test is_social_login_user="false"]
			This content is displayed only if the user IS logged in AND has NOT used Social Login to login.
		[/oa_social_login_test]

5. Troubleshooting

a. The Social Login buttons are not being displayed in my comments area!

The plugin uses existing WordPress hooks to seamlessly integrate into your blog. If your theme does not support these hooks, the plugin will not be displayed correctly. You can add the Social Login features manually by inserting the following code into your template: 

		<?php do_action('oa_social_login'); ?>

This code has be added at the location where Social Login should be displayed, i.e. above the comments form.

  1. Login to your blog as administrator,
  2. Click on Appearance and then Editor,
  3. Click on Comments (comments.php) in the file list to your right,
  4. Look for <h3><?php comment_form_title( 'Leave us your thoughts', 'Leave a Reply to %s' ); ?></h3>
  5. Add the code <?php do_action('oa_social_login'); ?> below.

Your theme might look slightly different. Try adding <?php do_action('oa_social_login'); ?> to another place in the code and check if the Social Login options are displayed. Please note that the buttons will not be displayed while you are logged in. If you are not sure where to add the tag, feel free to contact us, we will help you set it up.

b. I get an error 403 when logging in with a social network!

If you have installed the Bad Behavior plugin you might encounter the following error: 

	Error 403

	We're sorry, but we could not fulfill your request for /?oa_social_login_source=widget on this server.
	You do not have permission to access this server. Data may not be posted from offsite forms.
	Your technical support key is: 4466-1157-cd36-1abb

	You can use this key to fix this problem yourself.
	If you are unable to fix the problem yourself, please contact XXX at gmail.com and be sure to provide the technical support key shown above.

To fix this issue you must open the Bad Behavior settings in your WordPress administration area and Enable Offsite Forms. More information about this restriction is available in the Bad Behavior documentation.

c. The API Communication does not seem to work correctly!

Please make sure that your firewall does not block outbound requests on both ports 80 and 443. One of these ports must allow outgoing requests (from your server to ours) so that the plugin can establish a communication with our API.

If you have access to the console of your server you can test if outbound requests are allowed by using this command: telnet ping.api.oneall.com 443. If the port is open then you should obtain a result like this: 

		~$ telnet ping.api.oneall.com 443
		Trying 136.243.63.184...
		Connected to ping.api.oneall.com.
		Escape character is '^]'.

d. I do not get the correct email addresses of my users

Some social networks (e.g. Twitter) do not provide the user's email address. In this case it's unfortunately not possible to retrieve the email address directly from the user's social network profile data and the plugin will generate a placeholder email address.

To circumvent the problem, please login to your WordPress administration area, open the Social Login settings and enable the following option: If the user's social network profile has no email address, should we ask the user to enter it manually?

If you enable this option, then the plugin will ask the user to enter his email address manually in case it's not provided by the social network.

e. Social Login does not work with special (russian, cyrillic, arabic) characters!

Per default WordPress does not allow to use special characters in usernames. Non-latin characters are silently filtered out and your users cannot create accounts that contain such characters. To enable accounts with special characters you first of all have to install this plugin: WordPress Special Characters in Usernames

If users with longer usernames can no longer register after having installed that plugin then you might have to increase the length of the column user_nicename in the table wp_users in your database. 

		ALTER TABLE `wp_users` CHANGE `user_nicename` `user_nicename` VARCHAR(255) NOT NULL DEFAULT ''

User Contributed Notes