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
- Installation
- Settings
- Logging in
- Adding social account for existing member
- Posting updates
- Adding userdata (email, password)
- Displaying saved tokens
- Examples
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)
- Set to Pending if email cannot be obtained. If email address cannot be obtained from social network, you can force the account to be Pending (but person can still log in in order to provide email using add_userdata form). When email is added thoguh add_userdata form and you've set Self-activation via email in EE membership preferences, email with activations instructions is sent to user.
- 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.
- Prevent duplicate social account association. If you check this setting the user will see a warning if he tries to associate account in social network with his EE account, and that social account is already associated with other EE account (e.g. by editing custom profile fields)
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
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.
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.
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. Make sure you mark only r_basicprofile scope and leave all Redirect URLs empty. 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.
Windows / Live ID
To let people login using their Windows account (formerly Live ID), you need to register your website using https://manage.dev.live.com/Applications/Create. 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 Windows ID.
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.
To enable logins using Google account, you need to register your site at https://console.developers.google.com/project. Make sure you enable Google+ API for the project. 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+
To use Instagram logins, you need to register your site at http://instagram.com/developer/clients/register/. After you finish the registration, you'll be provided Client ID and Client Secret. Input those values into appropriate fields. Select a custom profile field to store Instagram username.
In your template code for login form, add this parameter:
callback_uri="/template-url" where /template-url is your OAuth redirect_uri.
If you have Instagram account associated with your site, you can enter it's ID (not username!) and people will be authomatically following it once logged in. You can use this link to learn your ID
Instagram is not sharing user's email address
VK.com
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
App.net
To use App.net logins, you need to have Developer account. Register your site at https://alpha.app.net/developer/app/create/. After you finish the registration, you'll be provided Client ID and Client Secret. Input those values into appropriate fields. Select a custom profile field to store App.net username.
You can enter your App.net username in settings and people will be authomatically following it once logged in and choose whether you want to send updates on user's behalf.
App.net is not sharing user's email address
Edmodo
First, register yourself as Edmodo developer. Then request app creation via https://developers.edmodo.com/edmodo-connect/edmodo-connect-overview-getting-started/#app-registration. Select following scopes: basic, read_user_email.
Edmodo does not support callback URLs with question mark in it, therefore you will need to create a template on your site with one tag: {exp:social_login_pro:access_token}. Then, provide URL to page using this template as your Callback URI. In your template code for login form, add this parameter:
callback_uri="/template-url" where /template-url is your Callback URI.
When you'll receive Application ID and Secret, enter their values into appropriate fields. Select a custom profile field to store Edmodo username.
Logging in
Place {exp:social_login_pro:form} wherever you want login form to appear. You can have multiple form instances on page.
Parameters:
- return — a page to return after login (either successful or failed). Can be a full URL or URI segments.
Use return="SAME_PAGE" to return user to the page used to display login form. - no_email_return — a page to return after login if user email is not set or cannot be obtained
- new_member_return — if this is first time user logs in (registers) at your site, he can be directed to special page
- providers — if you have settings for several social networks, but want to limit certain form just with some of them, list them in this parameter (pipe | separated, optional). Ex. providers="twitter|facebook"
- icon_set — you can specify other icon set to be used for certain form than one provided in settings. Ex. icon_set="24x24"
- group_id — if this is member's first login, you can set membership group for hime (overriding value in the settings)
- id — form ID. Defaults to 'social_login_form'
- class — form CSS class. Defaults to 'social_login_form'
- name — form name. Defaults to 'social_login_form'
- popup="yes" — open the authentication dialog in popup window
- secure_action="yes" — force https usage
Form fields:
- provider — name of external login service provider to use. Can be hardcoded or auto-populated using {providers} tag pair
- auto_login — "Keep me logged in" checkbox. The value should be "1". (This will work only if your session type is "cookies only")
- anon — 'Do not show me in "who's online" list' checkbox. The value should be "1".
Inside of {providers} tag pair following variables are availabe:
- {provider_name} — provider name. This is 'technical' variable, should be used as value for 'provider' input field.
- {provider_title} — the 'full' name/title of service provider/social network
- {provider_icon} — URL for image/button for corresponding provider (from the icons set defined in settings)
You can optionally apply backspace="xx" parameter to {providers} tag pair to remove xx last characters from output result.
If you use Cookie Consent module, you need to add "allow_cookies" field to your form.
<input type='checkbox' name='cookie_consent' value='y'/> <span class="alert">Allow Cookies</span>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
— {my_custom_field} - all custom fields are available (but formatting not applied)
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.
Displaying saved tokens
If you need to use oAuth tokens associated with user account for work with other module, you can access them by using {exp:social_login_pro:tokens} tag.
{exp:social_login_pro:tokens}
<p>
<img src="{provider_icon}" id="img_{provider_name}" /> {provider_title}
{if oauth_token}<br />Token: {oauth_token}{/if}
{if oauth_token_secret}<br />Secret: {oauth_token_secret}{/if}
</p>
{/exp:social_login_pro:tokens}
For Yahoo! accounts, there's also {guid} variable available.
You can also use this tag to display ID of user in social network (additionally to username, which is stored in custom field). Use {user_id} variable.
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}