README.md

SocialGap

SocialGap is a simple library intended to ease the integration of PhoneGap hybrid mobile apps with social networks. It is modular, so it can be easily extended and it reduces overhead since you import only the modules you need. This plugin has been developed as a proof of concept while developing Mmarazzu Mobile app. This software is not intended for production usage as it is because of the following list of known needed modifications:

1. Facebook long-lived token support needs the app-secret. This should not be deployed on the clients. In order to use the Facebook API as intended you need to transform short-lived token in long-lived ones on your servers and then transport the tokens on the clients, where they will be stored. More information: https://developers.facebook.com/docs/facebook-login/access-tokens

Setup

Including this library in your project is quite easy. This software require the inAppBrowser plugin and the modernizr javascript library.

If you do not have it already, you can install the inAppBrowser plugin by typing the following command from within your app main folder:
cordova plugin add https://git-wip-us.apache.org/repos/asf/cordova-plugin-inappbrowser.git

Once the prerequisites are in place, reference the following js files from your html page:

	<script type="text/javascript" src="js/modernizr.js"></script>
	<script type="text/javascript" src="js/SocialGap/socialGap.js"></script>
	<script type="text/javascript" src="js/SocialGap/socialGap_facebook.js"></script>

From now on the setup procedure differ based on the module you would like to use.

• Facebook:
  When deviceready event is received, set up the Facebook extension calling the Facebook_ChangeSettings function as follows:
  

   SocialGap.Facebook_ChangeSettings('appID', 'appSecret', 'fbAppDomain', 'fbScopes');

  
  

  	Then prepare two callback functions.<br>
  	One of them will be called in case of success receiving as parameter the Facebook access token.<br>
  	Instead, the other will be called in case of failure.
  	 <pre><code>	fbLogonSuccess: function(accessToken)
  {
  	alert(token);
  }
  
  fbLogonFailure: function(){
  	alert('Fail');
  }</code></pre>
  	
  	Once ready build a link that will start the authentication process.
  	 <pre><code>	&lt;a onclick=&quot;SocialGap.Facebook_PerformLogon(fbLogonSuccess, fbLogonFailure);&quot;&gt;
  	Logon with Facebook
  &lt;/a&gt;</code></pre>
  	
  </li>
  
  <li><b>LinkedIn</b>:<br>
  	When deviceready event is received, set up the Facebook extension calling the <code>Linkedin_ChangeSettings</code>
  	function as follows:<br>
  	 <pre><code> SocialGap.Linkedin_ChangeSettings('apiKey', 'secretKey', 'ldAppDomain', 'ldScopes');</code></pre><br>
  	
  	Then prepare two callback functions.<br>
  	One of them will be called in case of success receiving as parameter the LinkedIn access token.<br>
  	Instead, the other will be called in case of failure.
  	 <pre><code>	ldLogonSuccess: function(accessToken)
  {
  	alert(token);
  }
  
  ldLogonFailure: function(){
  	alert('Fail');
  }</code></pre>
  	
  	Once ready build a link that will start the authentication process.
  	 <pre><code>	&lt;a onclick=&quot;SocialGap.Linkedin_PerformLogon(ldLogonSuccess, ldLogonFailure);&quot;&gt;
  	Logon with LinkedIn
  &lt;/a&gt;</code></pre>
  	
  </li>
  

Develop an extension

Developing an extension is quite straightforward.
We have prepared a "template" in example/js/socialGap_basic.js which can be used as a starting point for extending this library.

Run the example

In order to make the example work follow these steps:

1. Create a new PhoneGap app typing something similar to:
   phonegap create YourApp/ com.whatever.yourapp YourApp
2. Copy the files contained in the example folder into the www folder of the project you've just created
3. Copy the folder Social Gap contained under the lib directory into the folder www/js of the project you have just created.
4. Set the required settings for the extension(s) you need as explained above.
5. Install the inAppBrowser plugin for your project, typing these commands:

   cd YourApp
   cordova plugin add https://git-wip-us.apache.org/repos/asf/cordova-plugin-inappbrowser.git

6. Run the project for the platform you like most.
   For instance type the following command from within YourApp directory:
   phonegap run android