The Social Connect Addon is meant primarily to allow your users to both register, and log in, using popular social websites such as Facebook and Google+. Currently only Facebook connect is implemented but we have plans to add more sites in future versions.

The secondary function is to add various integration options, such as showing a seller's Facebook profile pic on the seller's listings.

This addon currently allows users to click a link Login with Facebook. This will direct them to a page that will let them log into their Facebook account, and "approve" your website's Facebook app to access minimal information. The user is then taken back to the site. Below are the different scenarios for what will happen:

• If the Facebook profile ID is already attached to an account in the software, the user is logged in under that account. <
• If the user's e-mail matches a user already in the system, then it knows the user is the same as the one already in the system. In that case, it links the Facebook account to that existing user, and logs the user in. <
• Rare Scenario: If trying to link up a FB account to one account, when it is already linked to another account, it will merge both user accounts together using the "older" of the two user accounts in the system. Typically this will happen if someone that already has a user account attempts to use "login with Facebook" when the e-mail does not match, so that it creates a brand new user account. If that user later tries to link the FB account to the older account within the software, it will merge the newer account created using Facebook connect into the pre-existing older user account. <
• If there are no matching accounts on the site yet, it will register a new "minimal" user with the info mentioned in Minimal User Registration <

When a new user is registered by using Login with Facebook, the following account fields are used.

• Username: Tries to use the best appropriate username in the software according to the following heirarchy:
  1. Facebook username if set for the profile¹⁾ - example: facebookusername <
  2. First name and last initial - example: First L²⁾ <
  3. Full name - example: First Last³⁾ (Only if first/last name could not be determined) <
  4. First part of e-mail before @
  5. Username is filtered to remove any characters not allowed for a username.
  6. If the username generated matches one in the system, it adds a number - example: First L 1 or First L 5⁴⁾ if happen to already have 4 other users with same first name and last initial. <

<

• Password: NOT used! ⁵⁾ <
• First Name: Set to first name in Facebook profile. <
• Last Name: Set to last name in Facebook profile. <
• Email: Set to e-mail for Facebook profile. Note that when user is "allowing access" to your site, they can elect to use anonymous e-mail, which will still work fine, you can read more info on facebook.com's FAQs. <
• Country: It looks at the "locale" on the Facebook profile, and attempts to determine if it matches to any countries within the software. If it finds a match, it sets the user's country. <
• Profile ID: In order to allow future "login with facebook" to work, and to allow displaying the profile picture for the user, it stores the Facebook profile ID. <
• That's all!⁶⁾ Even if you have other required fields set in your registration settings, the above are the only fields that will be populated for a user registered using Login with Facebook. If however, the user ever tries to edit the profile information within "my account" area, it will require that all required fields are entered at that time before they can save any other changes. <

These instructions will walk you through steps necessary to set your site up to start using Facebook Connect.

1. Install and enable the addon as instructed in Installation of Addons.
2. If you do not already have a Facebook App for your website, go to http://developers.facebook.com/setup to sign up. Note that you will need to have a personal Facebook account to create a Facebook App. The link above goes to a page that looks like the following:
   
   The above page would list any apps if you already had one. The above shows an account with none of them. In the above page you would click the "Create a New App" link.
3. You will then see a screen like the one below:
   For the Display Name enter what you want the app name to be. This will show when visitors click to login with facebook, it will be used at the top of the window to log in. We recommend to use your site's name or something similar. Be sure to read the info provided when you hover over the ? next to the display name to see restrictions. The category field is now a requirement but doesn't really mean anything in this instance as you are not offering this app to other facebook users. You can set any category you like but Apps for Pages if you non-committal on your choice. Namespace field is optional and not needed in this app instance.
4. If you see one, Do NOT check the box for "web hosting"⁷⁾, since you already have your own hosting. Click the Create App button in that screen to continue.
5. You will now see a page like the one below:
   
   From here click the Settings link in the left menu
6. You will now see a page like the one below:
   
   For App Domains enter the main domain name where the app will be used, without the www if you use it. As an example, if your site was installed at www.example.com you would enter example.com When you enter the main domain there, it should allow all sub-domains as well so that www.example.com will work, as well as any sub-domains for geographic navigation if you happen to use that feature.
7. Next click on the + Add Platform link in that same page as shown in the above screen shot. You will see a section that appears like this:
   
   Click the Website link/icon.
8. You will now see the following within that page
   
   Enter the website URL. If the software was installed in http://example.com/index.php you would enter http://example.com/. In other words when you view the software homepage on your website, it should be the entire URL minus the file index.php.
9. Now you will need to get the APP ID and App Secret from you App Dashboard (click the Dashboard link in the left hand menu). You will find those values there as seen in the following screenshot:
   
   You will need to click on the show button next to App Secret to expose that value for cutting and pasting within those same fields in your ADDONS > SOCIAL CONNECT > SETTINGS admin tool like appears in the screenshot below:
   
   After entering those values click the save button in that admin tool.
10. Once you are sure you have everything correct you will need to change that status of your app from development to live" within the Status & Review admin tool at facebook as it appears in the screenshot below:
    
    Click the sliding button to allow the general public access to that feature. - Now try the feature on the client side. But DO NOT test this with an facebook account whose email matches the Geo admin users account. ====== Addon Tags ====== There are several addon tags that you can use in your design as explained below. ===== facebook_login_button ===== {addon author='geo_addons' addon='social_connect' tag='facebook_login_button'} Use this tag to display the Login with Facebook button anywhere within your site. Note that we have a few suggestions on where you might want to place this tag in Template Suggestions. * If the user is not logged in, it will appear like this: Clicking will either log the user in (if FB account already linked to user's account), or will register a new user account using info from Facebook profile. < * If the user is logged in using normal login and they do have Facebook profile linked to account, it will look like this: Clicking will re-connect to the FB account. This can sometimes happen if it has been a while since the user has last authorized the account. As long as the user is already logged into Facebook, and has previously already allowed access to the site, to the user it will appear to re-load the current page with that button gone⁸⁾. < * If the user is logged in using normal login and they do NOT have Facebook profile linked to account, it will look like this: Clicking on the button will prompt the user to authorize the site to have access to the user's account info. Once they log in and authorize access, that pre-existing user's account will be "linked" to the Facebook account. < ===== facebook_session_profile_picture ===== {addon author='geo_addons' addon='social_connect' tag='facebook_session_profile_picture'} If the user is currently logged in, and is linked to FB profile, this tag will display the user's Facebook profile picture. ===== facebook_listing_profile_picture ===== {addon author='geo_addons' addon='social_connect' tag='facebook_listing_profile_picture'} This is used on listing details page. If the seller's account is linked to FB, and that seller has checked to show his or her Facebook profile pic. This setting is found in my account information within my account, the setting named Show Facebook Profile Pic in Listings, as illustrated below: ====== Template Suggestions ====== This is our suggestion for changes to make to your templates, assuming you are using a design close to the default design. In the file header.tpl, find this section: <code html><!– START USER BAR –> <div id="user_bar"> Welcome, {module tag='display_username'} ( {if not $logged_in} {*Logged out code*} <a href="register.php">Register</a> | <a href="index.php?a=10">Login</a> {else} {*Logged in code*} <a href="index.php?a=4">My Account</a> | <a href="index.php?a=17">Logout</a> {/if} ) </div> <!– END USER BAR –></code> Replace that entire section, with the below modified version: <code html><!– START USER BAR –> <div id="user_bar"> {addon author='geo_addons' addon='social_connect' tag='facebook_session_profile_picture' assign='fb_pic'} {if $fb_pic} <div style="float: left; border: 1px solid black; margin: 0px 8px 8px 5px; line-height: 0px;">{$fb_pic}</div> {/if} Welcome, {module tag='display_username'} ( {if not $logged_in} {*Logged out code*} <a href="register.php">Register</a> | <a href="index.php?a=10">Login</a> {else} {*Logged in code*} <a href="index.php?a=4">My Account</a> | <a href="index.php?a=17">Logout</a> {/if} ) {addon author='geo_addons' addon='social_connect' tag='facebook_login_button'} </div> <!– END USER BAR –></code> The above changes will make the Facebook profile pic display to the left of the normal "Welcome…" text, if the user is logged in with Facebook. If the user is not logged in with Facebook, it will show the appropriate Facebook button according to what is mentioned above in facebook_login_button. ====== Future Plans ====== Our main goal is to add more Social websites, to allow users to log in with Google+ and any others that clients might want. We also plan to add deeper integration**, for instance showing all your friends that use the website. If you have any suggestions of your own don't hesitate to let us know!