Gigya Job Openings

socialize.addConnection REST

Skip to end of metadata
Go to start of metadata

Any reference to OpenID or OpenID Provider on this page is referring specifically to the OpenID OAuth 2.0 Protocol. For information pertaining to OpenID Connect, please see our OpenID Connect documentation.

This method may only be used if you are implementing Gigya's REST API in compliance with OAuth 2.0.

Description

This API serves as an end point for connecting the user to a specified* social network. This API requires user interaction. To add a connection, redirect the user to the specified URL and pass the required parameters. When the addConnection process completes - either successfully or with an error - the Gigya server redirects the user to the URL defined in the redirect_uri parameter and appends response parameters.

Technically speaking, a connection is an established session with the social network and it expires according to the social network policy. A valid and active connection will give your site access to the user's social graph and ability to perform various social actions, such as publishing a newsfeed report to the connected social network.

* The social network to connect to is specified using the "provider" required parameter. You may find more details in the parameter description below.

 

Note:
If the user is logged in to the Gigya service:

  • Gigya will automatically link between the connected social network account and the user's site account. As a consequence, from now on the user will be able to log into his site account using this social network.
  • Gigya will associate the connection with the user's account. This means that 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 will be associated with the current user on the current computer using a cookie.

Supporting Providers

This operation currently supported by the following providers:

Facebook, TwitterYahoo, MicrosoftLinkedIn (Note: messenger has been replaced by microsoft, however, for backward compatibility, either can be used) 
, Google+, InstagramRenren, Vkontakte, mixi, Odnoklassniki, YahooJapan and WeChat.

Request URL

Where <Data_Center> is:
  • us1.gigya.com - For the US data center.
  • eu1.gigya.com - For the European data center.
  • au1.gigya.com - For the Australian data center.
  • ru1.gigya.com - For the Russian data center.
  • cn1.gigya-api.cn - For the Chinese data center.

If you are not sure of your site's data center, see Finding Your Data Center.

Parameters

RequiredNameTypeDescription
 oauth_tokenstringThe OAuth access token for the user. Read more in The OAuth 2.0 protocol. This must be passed over HTTPS; requests made over non-SSL connections will return an error invalid_token (errorCode 403025).
x_providerstringThe provider to connect to. The optional values for this parameter are: 'facebook', googleplus, 'twitter', 'yahoo', 'microsoft', 'line', 'linkedin', 'qq', 'renren', 'sina' , vkontakte , wechat (Note: messenger has been replaced by microsoft, however, for backward compatibility, either can be used), 'googleplus', 'instagram', 'renren','vkontakte', 'mixi', 'odnoklassniki', 'yahoojapan' and 'wechat'. Also SAML providers are supported - the format of the provider name is "saml-".
redirect_uriURLThe URL to redirect to after the addConnection completes. The URL must be verified against the registered domain for this API key.
response_typestringMay be either "code" or "token"
statestringA string that will be passed as another parameter to the redirect_uri after the login completes.
x_langstringDefines the language of Gigya's user interface and error message. For the list of languages supported, please refer to the languages table.
x_extraPermissionsstringA comma-delimited list of extended permissions to request from the user. This parameter gives the possibility to request extended permissions in addition to the permissions that Gigya is already requesting. Refer to Facebook's extended permissions page for the complete list of Facebook permissions.

For example, if you wish to RSVP to events on the user's behalf and to send sms messages to the user, define: x_extraPermissions="rsvp_event,sms". To request Google wallet permissions define: x_extraPermissions="wallet".

x_displayModestringThe display mode of of the Facebook login page. The valid values are:
  • 'popup' (default) - displays Facebook's popup login dialog
  • 'page' - displays Facebook's full login page
  • 'touch' - used on smartphone mobile devices, like iPhone and Android

 

Response Data

FieldTypeDescription
 
errorCode integer The result code of the operation. Code '0' indicates success, any other number indicates failure. For a complete list of error codes, see the Error Codes table.
errorMessage string A short textual description of an error, associated with the errorCode, for logging purposes. This field will appear in the response only in case of an error.
errorDetails string This field will appear in the response only in case of an error and will contain the exception info, if available.
fullEventName string The full name of the event that triggered the response. This is an internally used parameter that is not always returned and should not be relied upon by your implementation.
callId string Unique identifier of the transaction, for debugging purposes.
time string The time of the response represented in ISO 8601 format, i.e., yyyy-mm-dd-Thh:MM:ss.SSSZ or
statusCode integer The HTTP response code of the operation. Code '200' indicates success.
This property is deprecated and only returned for backward compatibility.
statusReason string A brief explanation of the status code.
This property is deprecated and only returned for backward compatibility.

 

statestringThe state string passed by your application as parameter to the login endpoint. (See Parameters above).

A field that does not contain data will not appear in the response.

 

 

Response Example

<?xml version="1.0" encoding="utf-8" ?> 
<socialize.addConnectionResponse xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="urn:com:gigya:api http://socialize.gigya.com/schema" xmlns="urn:com:gigya:api">
  <statusCode>200</statusCode> 
  <statusReason>OK</statusReason> 
  <callId>ee8137def00643138fae7168940bbc9e</callId> 
  <time>2015-03-22T11:41:32.318Z</time>
</socialize.addConnectionResponse>