Last modified 14:29, 19 Mar 2015

This page is a step-by-step guide for the process of opening and setting up an external application in Facebook as part of the Gigya Setup process.


Clients with sites defined under Gigya's European data center should replace domain references to (http:// or https://) "socialize.gigya.com" (or "socialize.us1.gigya.com") with "socialize.eu1.gigya.com". To verify site location contact your implementation manager.
Domain references are defined in Gigya's dashboard, externally in social network app definition pages, and when using Gigya's SDKs to set the domain (in particular the APIDomain field in class GSRequest). 


Note: Facebook apps require a domain alias (CNAME) that redirects to Gigya, for example "http://login.yoursite.com" which redirects to an address assigned by Gigya customer services.  Please ask your customer service representative for the precise redirection definition. Facebook apps without a CNAME will not be able to share, as Facebook no longer supports sharing without a CNAME.


Phase 1 - Opening the Application in Facebook

  1. Log into your Facebook account.

  2. Open the Facebook developer's page at: https://developers.facebook.com/apps?ref=mb.
  3. In the top menu, click on "Apps" and select "Add a new app".
  4. In the "Add a New App" box, click on the "Website" icon.

Step 4.png


  1. In the "Quick Start for Website" wizard, click on the "Skip and Create App ID" button in the top-right corner.

Step 5.png


  1. In the "Create a New App ID" box:

new app id window.png


  1. Enter the Captcha and press 'Submit'. Note that after pressing submit, you receive no confirmation of a successful submit and the Captcha remains open. 


  1. Click on the "Settings" button on the left.
  • Copy the "App ID" and the "App Secret" strings (you will need to paste them in Gigya's website, as described in phase 2), use the Show button to see the "App Secret".
  • Enter your site's domain in the "App Domains" field. These are the domains within which OAuth will authorize your app to view data. For example, if you use the CNAME "login.mysite.com", the "App Domains" field must contain "mysite.com".​



  1. Click on the "Add Platform" button at the bottom of the Settings box and select "Website".  


Add platform


  1.  Enter your website's address in the "Site URL" and your mobile site (if available) , then click "Save Changes".


Note: To forcibly sign a user out of Facebook in socialize.logout, socialize.removeConnection or accounts.logout, the "Site URL" must match the name of your site.

 Enter website address and save changes


  1.  If you are defining an Android app for Facebook:


Click the "+Add Platform" button and add an "Android" platform.  You will need to enter your Android app's "Package Name" and the "Class Name" of its Main Activity as well as the app's key hash. The key hash is a unique app identifier generated with the Java keytool utility: for more information about this and setting up Android apps for Facebook see https://developers.facebook.com/docs/android/getting-started).  Note that Android apps can be added at a later stage by updating the Facebook app and going to the "Settings" button's "Basic" tab (https://developers.facebook.com/apps/621977507869949/settings/basic/). 

Facebook settings.jpg


  1. Select the "Advanced" tab of the Settings page:
  • Set "Native or desktop app?" to "No".
  • Set "App Restrictions" as you require.



  1. In the "Security" section of the "Advanced" tab set the following:
    1. Set the "Client OAuth Login" to Yes.
    2. In the "Valid OAuth redirect URIs" enter:
      • ​http://<CNAME>/GS/GSLogin.aspx?
      • https://<CNAME>/GS/GSLogin.aspx?
    3. If you are not using a CNAME for the connection to Gigya then in the "Valid OAuth redirect URIs" enter:
      • ​http://socialize.gigya.co​m/GS/GSLogin.aspx?
      • https://socialize.gigya.co​m/GS/GSLogin.aspx?​​


  • Apps not using a CNAME are unable to share to Facebook.
  • If your site is defined under one of Gigya's non-US data centers, replace socialize.gigya.com with socialize.<DC>.gigya.com (e.g. socialize.eu1.gigya.com for europe). Contact your IM to find out the region of your Data center.
  • To forcibly sign a user out of Facebook in socialize.logout, socialize.removeConnection or accounts.logout, the "Valid OAuth redirect URI" must match the name of your site.


  1. Make sure your domain is included in the list of valid OAuth redirect URIs.

Security settings


Note: Under Settings you will also find a "Migrations" tab which offers some newer options, including "Stream post URL security." This option is disabled by default. Enabling it will prevent your app from posting links that do not point to your specified website URL -- including any links in your Trusted Shared URL list. Enabling this option will also prevent Gigya's URL shortening service from working.
If you do turn on the "Stream post URL security" option, you will need to disable Gigya's URL shortening service. To do this set the shortURLs parameter to "never" in the Global Conf object (for details see Global Conf).


  1. Click the blue "Save Changes" button.


  1. Click on the "App Details" button on the left. For an explanation of the "App Details" fields see https://developers.facebook.com/docs/games/appcenter/guidelines.


App details - info


  1. In the App Details "Contact Info" section enter relevant details. A privacy policy URL is required by Facebook, other URLs are optional. Click on "Create New Page" to setup a Facebook page for your app.

Contact info


  1. In the "App Center Listed Platform" section, set Website to "Yes".

App center listed platforms


  1. Enter icons, banners, screenshots and videos in the relevant sections. For Facebook information on the requirements see https://developers.facebook.com/docs/games/appcenter/guidelines. The minimum requirements for these sections are:
  • Icons section - At least a logo
  • Banners section - At least a web banner and cover image.  
  • Screenshots - At least 3 screenshots are required.


  1. Click the "Localize" button on the left if you want to configure your app's details for viewing in other languages.


  1. Optional: Facebook provide an option to request public approval of your app. Note that this may take some time and is not required for logging in with Facebook.  
  • If you do want to get Facebook approval, click on the "Status & Review" button on the left, set your app to be available to the general public (unless it is still being tested) and then click "Start a submission":

Status & Review


  • A dialog box will open for you to select the Apps to be included in the submission (more than one app may be submitted at once).


  • A red triangle will appear next to "Status & Review" and any sections where additions are required. If you click on the App Details button, a message will tell you what items are missing.
    Ineligible for submission indicator  


  1. Optional: You can ask for login permissions beyond the basic ones. This will need to be submitted for approval by FB. Full list of additional permissions can be found here.
  • ​​If you want to ask for login permissions beyond the basic ones (email, public_profile and user_friends are the basic), you will need to include additional permissions by clicking on the "Add Items to this Submission" link.​​

​​                 File:010_Developer_Guide/82_Socialize_Setup/005_Opening_External_Applications/10_Facebook/clipboard_1399203886072.png


  • A pop-up window with a list of permissions will appear for you to select additional permissions. Select the additional items and click 'Add items'.

​​                 File:010_Developer_Guide/82_Socialize_Setup/005_Opening_External_Applications/10_Facebook/clipboard_1399204226622.png


  • ​You then need to click on the "Add Notes" link for each of the additional permissions.​

​​                 File:010_Developer_Guide/82_Socialize_Setup/005_Opening_External_Applications/10_Facebook/clipboard_1399204892154.png


  • After you click on 'Add Notes' you need to enter the following information for each item, and click 'save'.



  • In addition, on the Review Submission Form, you must upload a minimum of four screenshots that shows how the site is using Facebook in the app. 
  • Click the "Submit for Review" button to submit the app for approval.


Note: If you migrate from Facebook API v1 to v2, you will have to request enhanced permissions. See A Note on Facebook API Versions below.


Optional Settings (For Advanced Users)

Using Graph Actions

Facebook's Graph API allows you to publish stories on your users' Facebook timelines, describing actions users have performed in your website, such as "Jane Smith reviewed a recipe on Daily Recipe". You may use Facebook's Graph API through the Gigya API with the socialize.facebookGraphOperation API method.

To publish Graph stories, you must first:

  1. Set up a Facebook app as described in the previous section.
  2. Check the "Enable publishing user actions" check box in the Site Setup > Permissions page on Gigya's website.
  3. Define objects on your website using HTML meta tags, as described in Actions and Objects.
  4. Test all of the actions you intend to publish using your app. You cannot ask for approval for actions until you have used them at least once from your app.
  5. Submit your app for approval, including all actions you intend to use, as described in Submit Your Actions for Review.
  6. During the Social Login process in your website, the user will be presented with a Facebook dialog in which they can authorize your application to publish actions

Facebook's guide to Custom Stories on the Web provides a general introduction to stories and actions and describes the review process for apps that use Graph actions.

For further details of the review process, see Story Submission Process.

For a reference on Graph actions, see Using Actions.


Facebook Canvas

If you plan to use the Facebook Canvas Page, you have to define it here and then enable it in the Gigya settings (see Facebook External Application Canvas Page).

  1. Click the "Settings" button on the left.
  2. Click the "+ Add platform" button at the bottom of the Basic Settings box and select "Facebook Canvas".


  1. In the "Canvas URL" field, paste: http://<CNAME>/GS/SNLink.aspx?appid=<appid> ​

Note that you cannot use a specific HTML page as a canvas URL (use http://www.yoursite.com/canvas/, not http://www.yoursite.com/canvas.html).


If you are not using a CNAME, paste http://socialize.gigya.com/GS/SNLink.aspx ?appId=<appid> in "Canvas URL" and https://socialize.gigya.com/GS/SNLink.aspx?appId=<appid>in "Secure Canvas URL".

<appid> must be replaced with your App ID which is located at the top of the page.

If your site is defined under one of Gigya's non-US data centers, replace socialize.gigya.com with socialize.<DC>.gigya.com (e.g. socialize.eu1.gigya.com for europe). Contact your IM to find out the region of your Data center.

  1. Click the "Save Changes" button.


App Domains

If you are using a CNAME and would like to redirect users to other servers (i.e. for geographic distribution of load) and enable OAuth on additional subdomains, add your subdomains in the 'App Domain' field:

  1. Click the "Settings" button on the left.
  2. Enter your domain names in the "App Domains" field.
  3. Click the "Save Changes" button.
    Adding additional domains


Phase 2 - Configuring Facebook's Application Keys in Gigya's Website


  1. If you are not logged into Gigya, go to http://www.gigya.com/ and sign in. Then go to the Gigya Dashboard.
  2. Press the "Site Settings" button that corresponds to the domain you wish to configure. You will be redirected to the "Site Settings" page.


  3. select 'providers configuration' on the left hand side menu and click on 'Facebook'



  1. Paste your keys (the "Secret Key" and the "Application Id" from the end of phase 1) in the corresponding places:

  2. Select a Facebook API version to use with your app (Read more about Facebook API versions and permissions here).
  3. If you are using a CNAME, make sure to check the 'Enable CName' checkbox in the Facebook configuration window.
  4. Enable native SDK capabilities. Requires that your domain was entered in the "Valid OAuth redirect URIs" (see stages 10-16 above).
  5. If you are defining a canvas application, enter the canvas page url you defined in Facebook. 
  6. Click the "Save Settings" button (located at the lower right-hand corner of the page).


A Note on Facebook API Versions

To ensure smooth functionality, it is recommended that all of your Facebook apps use the same version of the Facebook API. Note that API v1 has been deprecated and cannot be used to create new apps: all Facebook apps created after April 30, 2014 are automatically assigned API v2 (see the Facebook upgrade guide). Therefore, if you create a new app, it will use v2, and if you have older apps that use v1, you should upgrade them to match the new app.

The upgrade may be mandatory for users of Single Sign-On, which requires that all sites in a group use the same API version. An app can use API v1 only as long as all the sites in your group are using v1. If you add a new site, with an app created after April 30, you must upgrade all the apps in the group to v2.

Thanks to Gigya's support for backwards compatibility, you can upgrade an app's API version without changing the app's implementation. Simply go to the "Facebook Configuration" dialog for the app and select the newer API version, as seen in step 4 above.

Differences you should expect when switching from v1 to v2 include:

  1. In v2, when logging into Facebook, you receive fewer properties from the Facebook profile by default. To get more properties by default, use the app configuration page on Facebook to request additional permissions. For more information about permissions in v1 and v2, see Facebook Permissions.
  2. The getFriendsInfo method now returns only those friends of the user who have granted permissions to your application on Facebook. However, the friend count property still reflects the user's actual number of friends.

Note that, while Facebook has also released Graph API v2.1 and v2.2, the availability of these versions does not affect your apps and does not require any further action on your part.

Phase 3 - Setting Up Your Facebook For Business Account

Facebook issues app-scoped user IDs to users who register to your app, meaning that a 'providerUID' obtained from Facebook is only valid in the scope of that particular app. Since each app is associated with a single site, clients with multiple sites are recommended to create a business account in Facebook in order to bind users' data from all sites under a single business entity. This step can be preformed at any point, and any existing Facebook app can be bound to the business entity that you create. 

Once you set up your business entity on Facebook, any user that registers to multiple sites is recognized across your different sites and his social data can be aggregated under a single identity. Gigya automatically recognizes your business and associates it to all of your apps, so no further configuration is needed other than setting up your Facebook business entity and associating all of your Facebook apps to your business.

App-scoped data can be obtained via the the identity object. The identity holds an array called 'mappedProviderUIDs' which contains pairs of Facebook 'Users ID' and the site API key that uses the associated app.

Make sure that all of your Facebook apps are using the same Facebook API version (see A Note on Facebook API Versions above).


That's it, Facebook configuration is complete! Please note that it might take up to 10 minutes for our system to become synchronized with Facebook.


Note: to learn how to localize your Facebook application to different languages, please refer to http://developers.facebook.com/docs/internationalization/.
Page statistics
32849 view(s) and 50 edit(s)
Social share
Share this page?


This page has no custom tags.
This page has no classifications.


You must to post a comment.