Social Login PRO

Social Login module enables people to log in into your ExpressionEngine site using their account in social network that support OAuth authentication. PRO version of module has number of extra features (easy way to bind social account to logged in member; automatically follow user; post to social networks about member's activity on your site).

General concept

To let people log into your site using their accounts on Facebook/Twitter/etc. you should place {exp:social_login_pro:form} form on your pages. You can style it with javascript (so that it will not looks as a form) or even hardcode login links (see examples section).

When the user clicks login button (submits the form), he is brought to the site of corresponding service provider (social network) where he is asked to authorise your site. After he authorises it by clicking appropriate button/links, he is brought back to your site (any page that you specify as return).

If the member with given social network ID is already registered in your site, he is logged in into his account. Otherwise new account is created for him.

From the technical point of view, whenever a new person is trying to log in, a record is created in members database table. However the user does not get any notification about created account, he's just logged in. A custom profile field containing username/ID in social network is used to identify returning visitor.

Installation

Place /social_login_pro and /shorteen folders into your /third_party folder. Make sure you also upload themes and images folders into appropriate places. Then go to Modules section in EE Control Panel and click Install near Social Login PRO. Be sure to install both module and extension.

Shorteen module will be installed authomatically.

If you already have Social Login installed, the settings will be copied for Social Login PRO and the module de-installed.

Settings

Because Social Login PRO is MSM-compatible module, the settings are saved separately for each site.

The general settings are:
- Member group to assign. The membership group that will be used fro people who try to log in using this module (and not registered with your site yet). It is recommended that you create separate group for them. (can be overridden by setting tag parameter in template)
- Graphical set (icons type/size) to use. The set of icons to be used by frontend form tag. Can be overridden by using form parameter. By default available are different square icons and horizonal bars. You can also use your own icons set by placing images into your themes/third_party/social_login/<your_icons_set_name> folder. The images should be in PNG format and named like <provider_name>.png (ex. twitter.png) - URL shortening service. Third-party service to be used for URL shortening when posting status updates to social networks. The shortening is donw with the help of Shorteen module - please be sure to provide appropriate API keys in its settings.

You can also optionally set custom fields that will be filled with First name, Last name, Full name and Gender ('m' or 'f'). Note that not all social networks provide that kind of data.

All other settings are provider-specific. As a general rule, you will need to provide application/customer ID, secret key, custom profile field to store the username used by service provider/social network and check whether you want to send status updates to this network on user's behalf.
The custom field is mandatory and will be used to identify whether person trying to login using external service is already registered at your site. You should use separate field for each service provider.

Posting templates are described in separate section

Facebook

To use Facebook logins, you need to register your site at http://developers.facebook.com/setup/. After you finish the registration, you'll be provided Application ID and Secret key. Input those values into appropriate fields. Select a custom profile field to store Facebook username and choose whether you want to send updates to Facebook on user's behalf.

Twitter

To let people login using Twitter, you need to register your site at https://dev.twitter.com/apps/new. Use your website name as Application Name. The Application Type is Browser and Default Access type you need is Read and Write. You can use your site homepage as Callback URL - it will be set dynamically, so you don't have to worry about it. After you finish the registration, you'll need to provide module settings with given Consumer key (not API key) and Consumer secret. Select a custom profile field to store Twitter username and choose whether you want to send tweets on user's behalf.

If you have Twitter account where you post updates from your site, you can enter it's name and people will be authomatically following it once logged in.

Twitter is not sharing user's email address, so email is not stored for people who log in using Twitter

Make sure you specify something as callback URI in Twitter app settings. Though it will be overridden, this field should not be empty.

LinkedIn

To let people login using LinkedIn, you need to register your website using https://www.linkedin.com/secure/developer. If you only want to let people log in - it is enough to fill only the required fields. After you finish the registration, you'll need to provide module settings with given API key and Secret ket. Select a custom profile field to store LinkedIn ID and choose whether you want to send updates to LinkedIn on user's behalf.
NOTE: we are using LinkedIn ID and not URL to identify user, because one can set the profile to be hidden - but still use it to log in.

Just like Twitter, LinkedIn is not sharing user's email address, so it is not stored

Yahoo!

To use logins using Yahoo! ID, you need to register your site at https://developer.apps.yahoo.com/projects/. Register as Standard Project, select "This app requires access to private user data" and then select "Read/Write Public" under "Social Directory (Profiles)". After you finish the registration, you'll be provided Consumer Key and Consumer Secret. Input those values into appropriate fields. Select a custom profile field to store Yahoo! ID (note that it is stored in "short" form, i.e. username only) and choose whether you want to send updates to Yahoo! on user's behalf.

Google

To enable logins using Google account, you need to register your site at https://www.google.com/accounts/ManageDomains. After you finish the registration, you'll be given OAuth Consumer Key and OAuth Consumer Secret. Input those values into appropriate fields. Select a custom profile field to store Gmail address, which will be used as returning visitor identifier.

Google is currently supported only for authentication, as there is no public API yet for Google+

VKontakte

To let people login using their VKontakte (VK.com) account, you need to register your website at http://vkontakte.ru/editapp?act=create&site=1. After you finish the registration, you'll need to provide module settings with given Aplication ID and Secret key. Select a custom profile field to store vKontakte ID.

VKontakte is also not sharing user's email address, so it is not stored initially

VKontakte does not yet support posting messages to user's wall from web applications

Logging in

Place {exp:social_login_pro:form} wherever you want login form to appear. You can have multiple form instances on page.

Parameters:

Form fields:

Inside of {providers} tag pair following variables are availabe:

You can optionally apply backspace="xx" parameter to {providers} tag pair to remove xx last characters from output result.

Adding social account for existing member

Unlike 'basic' version of Social Login, PRO version allows the login form to be displayed to already logged in user. In this case, it will be used to add other social network accounts/logins to EE member account. If some accounts have already been added for member, they will not be displayed in the form.

Posting updates

Concept

PRO version of Social Login is able to post updates back to social networks people use to log in regarding their activity on your site. The updates are sent under their name.

If you do not want to send updates to certain social networks (or to all of them), uncheck the appropriate (or all) checkboxes on settings page.

All links in messages are shortened using the service you selected in settings.

Currently there are 4 events upon which updates can be sent:
— user resisters on your site using Social Login
— user publishes an entry
— user submits a comment
— user starts new forum thread

Templates

The templates for each type of update can be edited on Posting templates tab of module control panel.

To completely disable certain type of notification, uncheck the appropriate "Enable posting using this template?" checboxes.

Member registered

This template is used for message sent when user logs it first time/registers on you site.

Following variables are available for use in template:
— {site_name}
— {site_url}

Entry published

This template is used for message sent when user publishes an entry (only with 'open' status).

Following variables are available for use in template:
— {site_name}
— {title} - entry title
— {url_title} - entry URL title
— {channel_short_name} - channel short name
— {channel} - channel title
— {permalink} - link to entry based on channel settings and URL title
— {title_permalink} - same as {permalink}
— {entry_id_permalink} - link to entry based on channel settings and entry ID

Comment posted

This template is used for message sent when user submits a comment (only to entry with 'open' status).

Following variables are available for use in template:
— {site_name}
— {title} - entry title
— {url_title} - entry URL title
— {channel_short_name} - channel short name
— {channel} - channel title
— {permalink} - link to entry based on channel settings and URL title
— {title_permalink} - same as {permalink}
— {entry_id_permalink} - link to entry based on channel settings and entry ID
— {comment} - full comment text
— {comment_id} - comment ID

Forum thread started

This template is used for message sent when user starts new forum thread (only in live/not hidden forums).

Following variables are available for use in template:
— {site_name}
— {title} - thread title
— {forum_name} - parent forum name
— {forum_id} - parent forum ID
— {board_name} - forum board name
— {board_id} - forum board name (don't think anyone will need this...)
— {permalink} - link to this thread

Preferences form

It would be a smart idea to let people control whether they want updates to be sent to social networks under their name or not.

To let people contol this, place {exp:social_login_pro:permissions} form somewhere on your pages - it will display form to edit member's posting permissions.

The permissions are saved separately for each site if you use MSM. Members are able to check/uncheck permissions for each event (except Member registered, as it is sent only once).

{exp:social_login_pro:permissions return="thanks"}
{permissions}
<p><input type="checkbox" value="y" name="{field_name}"{checked}/> {title} </p>
{/permissions}
<input type="submit" value="save" />
{/exp:social_login_pro:permissions}

Adding userdata (email, password)

In case when email address has not been provided by social network, you may want to ask user for it. You may also want to let people set their own password (if you want to let them login with username/password, or edit username etc.)

For this purpose, you can use form generated with {exp:social_login_pro:add_userdata} tag pair.

Here's and example to give you idea:

{exp:social_login_pro:add_userdata return="SAME_PAGE" id="userdata_form"}
{email_block}
<p>Please let us know your email address:<br />
<input type="text" name="email" />
</p>
{/email_block}
{password_block}
<p>For additional security, you may create password to protect your account:<br />
<input type="password" name="password" />
</p>
<p>Confirm password:<br />
<input type="password" name="password_confirm" />
</p>
{/password_block}
<input type="submit" value="Save" />
{/exp:social_login_pro:add_userdata}

The form is displayed only when user is logged in and either email or password fields are empty. The contents of {email_block} is displayed only when email is empty. The contents of {password_block} is displayed only when password is empty.

Examples

Basic example with radio buttons

{if logged_in}
{screen_name}--{username}--<a href="{path=LOGOUT}">Log out</a>
{/if}
{exp:social_login_pro:form return="comments/social-login"}
{providers}
<input name="provider" type="radio" value="{provider_name}" id="{provider_name}_button">
<label for="{provider_name}_button"><img src="{provider_icon}" title="Log in using {provider_title}" /></label>
<br />
{/providers}
<input type="submit" value="proceed" />
{/exp:social_login_pro:form}

Example with auto-submitting dropdown select

{if logged_in}
{screen_name}--{username}--<a href="{path=LOGOUT}">Log out</a>
{/if}
{exp:social_login_pro:form return="comments/social-login"}
Login using:
<select name="provider" onchange="document.getElementById('social_login_form').submit()">
<option value="">--select a service--</option>
{providers}
<option value="{provider_name}">{provider_title}</option>
{/providers}
</select>
<input type="checkbox" name="auto_login" value="1" />Keep me logged in {/exp:social_login_pro:form}

Hardcoded login links

Replace 67 with the value of ACT input in the form (you can also find its value on module settings page in CP). RET variable is optional and can point to relative URL to redirect after login (full URLs will not work here)

<a href="http://www.mydomain.com/?ACT=67&provider=facebook&RET=/index.php/comments/social-login"><img src="http://www.mydomain.com/themes/third_party/social_login/bar/facebook.png" title="Log in using Facebook" /></a>

JavaScript-styled form

{exp:jquery:script_tag}
<script type="text/javascript">
$(document).ready(function(){
$('.extlogin').click(function(){
$('#social_login_form input[name=provider]').val($(this).attr('rel'));
$('#social_login_form').submit();
});
});
</script>
{exp:social_login_pro:form return="SAME_PAGE"}
<input type="hidden" name="provider" value="" />
{providers}
<a href="javascript:void(0)" class="extlogin" rel="{provider_name}" title="{provider_title}"><img src="{provider_icon}" alt="{provider_title}" /></a>
{/providers}
{/exp:social_login_pro:form}

Top of page