Displays an Add Connections plugin, which makes it possible to establish connections to social networks. The plugin presents the available social network logos as connect options. Page contains working examples.


Displays an "Add Connections" plugin, which makes it possible to establish connections to social networks. The plugin presents the available social network logos as connect options. By default, the plugin displays the following providers: Facebook, Twitter, Google+, LinkedIn, MicrosoftYahoo!, Foursquare, renren, and VKontakte.

You may customize the displayed providers using the requiredCapabilities parameter or the enabledProviders and disabledProviders parameters.

The full list of possible providers is:  You may also set the requiredCapabilities parameter to login in order to add more providers, such as Google and AOL. See the complete list of providers capabilities.

The Add Connections plugin may be embedded in the page or displayed as a popup at the center of the page.


  • All new implementations of the add connections plugin must use version 2. Apply this by setting the version parameter in this API to 2.
  • If you plan on integrating the Add Connections plugin, we highly recommend reading the Adding Connections page, which is a step-by-step guide for integrating the Add Connections plugin in your site. 

Connecting to a Social Network

When a user clicks a social network logo, a small dialog box opens asking for the username and password. Afterwards, the window closes. This connects the user to the specific social network.

A connection is equivalent to an established session with the social network, and it may expire according to the social network's policy. A valid and active connection gives your site access to the user's social graph as well as the ability to perform various social actions, such as publishing a newsfeed report to the connected social network.  Some providers, such as Facebook, require that the user give permission to access their data on the first login. Yahoo asks for permission on every login.

An example of this plugin can be viewed on the Get Friends Info example page.

If the user is logged into the Gigya service:

  • The Gigya service automatically links the connected social network account to the user's site account. From that point onward, the user will be able to log into their site account using this social network.
  • The Gigya service associates the connection with the user's account. That is, if the user logs in on different computers using the same account, the connection will be automatically available.

If the user is not logged in, the connection is associated with the current user on the current computer using a cookie.


Plugin Design and Options

This is the default design of the plugin:

<div id="connectionsDiv">&nbsp;</div>
	gigya.socialize.showAddConnectionsUI({containerID: 'connectionsDiv'});
</script><br /><br />
<input type="button" value="Click here to open a popup." onclick="gigya.socialize.showAddConnectionsUI({version: 2});" />

The plugin's design is customizable through the use of the parameters listed below.


versionintegerGigya offers a new improved version of the Add Connections plugin. To use the new plugin set this parameter to "2". All new implementations are required to use the new version, although existing implementations without this parameter will continue to function.
actionAttributesJSON objectIn Gamification your users receive points for actions they perform on your site, in this case adding a connection grants the user points. Action Attributes may be used to annotate actions with additional information, such as the section of the web site that generated the action. If you set here the actionAttributes, each time a user adds a connection, the action also receives an attribute, for example "tv-show":"glee", which can mean that the action was performed on the "Glee" page of the site. 
authFlowstringUsing this parameter you may specify that the adding connection flow will use page redirects instead of using a popup. This gives a solution for environments where popups are unavailable (e.g. mobile web view controls). This parameter accepts two values:
  • "popup" (default)
  • "redirect" - the adding connection flow uses page redirects. When the adding connection process completes successfully, the user is redirected to the URL specified by the redirectURL parameter (see below). If the redirectURL parameter is not specified, the user will be redirected to the original page from which the adding connection process started.
    Notes: This option will only work if CNAME is configured.
    When using this mode, the onConnectionAdded event is not fired .
customButtonsarray of JSON objects
customButtoncustomButton object

This parameter is deprecated. Use customButtons, above.

You may define any OpenID provider as an authentication destination - read more about Adding a Custom OpenID Provider 

You may also define a SAML login provider - read more about Adding a SAML Login Provider.

disabledProvidersstringA comma-delimited list of providers that should not be displayed in the plugin. The valid provider names are:
For example, if you would like this plugin to show all providers but LinkedIn and Twitter, define: disabledProviders:"linkedin,twitter".
enabledProvidersstringA comma-delimited list of providers to be displayed in the plugin. The valid provider names are:
For example, if you would like this plugin to show only the icons of Facebook and Twitter, define: enabledProviders:"facebook,twitter".
headerTextstringSets the plugin's header text.

This parameter is relevant only if the authFlow parameter is set to "redirect" (see above). Set this parameter with a URL to which to redirect the user when they log-in with the adding connection process. Users who have already logged-in with another connection will not be redirected.

The following additional parameters are appended to the URL string: UID, UIDSig, timestamp, loginProviderloginProviderUID, nickname, photoURL, thumbnailURL, firstName, lastName, gender, birthDay, birthMonth, birthYear, email, country, state, city, zip, profileURL, provider.

These parameters are equivalent to the User object fields. Please find the parameters' description in the User object reference page.

If the redirectURL parameter is provided the callback function is not called and the onConnectionAdded event is not fired.

Note: We strongly advise providing a secure HTTPS URL.


You can set the requiredCapabilities parameter to login in order to add more providers such as Google and AOL. If you do not use this property, the only networks you can add/remove via the enabledProviders and disabledProviders properties are the default friends class of networks, e.g.,:

  • Facebook
  • Twitter
  • Google
  • LinkedIn
  • Yahoo
  • Fiursquare
  • Renren
  • VKontakte
sessionExpirationintegerThis parameter defines the time in seconds that Gigya should keep the social network session valid for the user. To end the session when the browser closes, please assign the value '0'. If this parameter is not specified, the session will be valid forever.
showEditLinkBooleanShow or hide the "Edit" link. Clicking the "Edit" link opens a popup dialog that enables the user to edit his connection status to each of the social networks. Note: The "Edit" link only appears when connected to a social network. 
showTermsLinkBooleanShow or hide the "Terms" link. Clicking the "Terms" link opens Gigya's Legal Notices page.
showTooltipsBooleanThis parameter's default value is true. When set to true, a tooltip will be displayed when you mouse-hover over a social network icon. The tooltip presents the social network's full name.
showWhatsThisBooleanWhen this parameter is set to true, rolling over the Social by Gigya link at the bottom of the plugin causes a hint to pop up with a description of the Add Connection plugin. By default the value of this parameter is false. In order for the What's this tooltip to appear, the width of the plugin must be at least 150px and the height must be at least 100px. Use the whatsThisText parameter if you want to change the default hint text.
UIConfigstring (XML)

An XML string describing changes to the default design of the plugin.
For example:

<texts color=\"#00006D\"></texts>
<background background-color=\"#CACACA\" frame-color=\"#2424FF\"></background>

For more information contact us by filling in a support form on our site. You can also access the support page by clicking "Support" on the upper menu of Gigya's site.

whatsThisTextstringThis parameter is relevant only if the showWhatsThis parameter is set to "true". Use this parameter to define the text that appears in the pop-up (see screenshot above). The default text is "Add more connections to your account.".
 Events Registration Parameters 
onLoadfunction refA reference to an event handler function that will be called when the plugin has finished drawing itself.
onErrorfunction refA reference to an event handler function that will be called when an error occurs.
onClosefunction refA reference to an event handler function that will be called in one of the following scenarios:
  • If the plugin is displayed as a popup the event will be fired when the plugin is closing.
  • If the plugin is embedded in page the event will be fired when the user clicks a button that indicates the dialog should be closed. In this case the dialog will not hide itself automatically.
onConnectionAddedfunction refA reference to a function that is called when the user is successfully connected to a provider.
onButtonClickedfunction refA reference to an event handler function that will be called when one of the plugin's buttons is clicked.
useHTMLBooleanDeprecated. The Add Connections plugin is available in both Flash and HTML versions. By default, the HTML version is used. You may override the default behavior. Setting this parameter with the value 'false', will force Gigya to use the Flash version.


onClose Event Data


onConnectionAdded Event Data

eventNamestringThe name of the event: 'connectionAdded'.
sourcestringThe source plugin that generated this event. The value of this field is the name of the plugin's API method, in this case 'showAddConnectionUI'.
Note: This field will not be available if the source of this event is not a plugin (e.g., if the source is a socialize.addConnection API call)
contextobjectThe context object passed as a parameter to the plugin/method that triggered this event, or null if no object was passed.
userUser objectUser object with updated information for the current user.
providerstringThe name of the social network to which the user connected.

onButtonClicked Event Data

buttoncustomButtons objectThe object representing the custom button that has been clicked. If the clicked button is not a custom button, no customButton object will be returned.

Global Event Triggered

By using this plugin, the following global event may be triggered: onConnectionAddedand indirectly, if the 'Edit' link is displayed and the user opens the Edit Connections plugin, onConnectionRemoved might also be triggered.

To register an event handler use the socialize.addEventHandlers API method. Read more about onConnectionAdded and Events.

Code Sample

var context = {
	msg:'This is my params.context.msg'

var params = { 
    captionText:'This is my caption text',
    headerText:'This is my header content',

function myOnClose(evt) {
	evt['msg'] = 'The plugin has just been closed';
	var msg = 'Event name is : ' + evt.eventName +'\n';
	msg+= 'evt[\'msg\'] is : ' + evt['msg']+'\n';
	msg+= 'context.msg is : ' + evt['context']['msg'];            
params['onClose'] = myOnClose;