Gigya CMS Integration Spec

for e-commerce Sites

About Gigya
Gigyas mission is to socialize the rest of the web.
We provide websites with a complete social infrastructure that creates immersive social
experiences for users and provides unparalleled customer insights for businesses.
Gigya equips businesses like ABC, Pepsi and Verizon with a comprehensive solution to socialize
their online properties. Our technology enables seamless registration with Social Login,
increases traffic and time spent on-site via Social Plugins and Gamification and transforms
marketing by leveraging permission-based social identity data.
Gigya works with more than 500 enterprises and touches more than one billion users per month.
Our platform extracts the real value from social networks, empowering online businesses to
attract, engage and understand users like never before.
Gigyas web site: http://www.gigya.com
Customers
Customers page: http://www.gigya.com/clients/
Example sites (an assortment of customer implementations):
http://developers.gigya.com/057_Example_Sites
CMS modules
Gigya has several CMS platforms modules & plugins available for downloaded for quick &
simple integration into sites. Gigya modules include:
Demandware:
Sandbox beta version of our latest cartridge: http://gigya01.tech-prtnrna01.dw.demandware.net/on/demandware.store/Sites-SiteGenesis-Site

Download link (current production version)

http://marketplace.demandware.com/Gigya/Gigya,default,pd.html

Drupal: http://drupal.org/project/gigya
ATG: http://developers.gigya.com/050_CMS_Modules/Gigya_Module_for_Oracle_ATG
Magento: http://developers.gigya.com/050_CMS_Modules/050_Magento

Features
Gigya modules for e-commerce CMS should support the following features:
Social Login register/login to the site with your social identity.

Account Linking link your existing site account with your social identity.

Sharing share products/orders with your social graph contacts.

Sharing a product or an order Using Gigyas share-bar.

Share an action suggesting users to share after completing a purchase, or

when entering items to cart.

Reactions - placing a Gigya Reactions bar on products, allows users to react to content in
your site and share their reaction to social networks.

Rating & Reviews for e-Commerce sites, replace the default review module
and enable customers to rate, review products and comment on others reviews.

Activity Feed - Gigyas Activity Feed can be displayed on the stores front-page, showing
recent site activity.

Gamification - Gamification plugins will be displayed on the users profile page, showing
the users achievements and driving them to engage in more site activity.

Settings & Configuration page customize & configure the UI and behavior of

Gigyas plugins.

Support extending Gigya functionality allow clients to extend Gigya plugins

& API functionality through dedicated functions which will not be overridden
in any Gigya module/plugin update.

Technical Details
User registration & login flow
This is the most important stage of the implementation process. Please also see Gigyas guide for
implementing Social Login at the link below. Its a must read.
http://developers.gigya.com/010_Developer_Guide/10_UM360/030_Social_Login
Guidelines:
As a general rule, the registration process should be as quick and effortless as possible.
When registering through a social network, the user will not be asked to choose a username or a password. Only his social credentials would be needed to login. The best
practice is for the registration process to not ask the users for any additional info when
registering through a social network.
2

The social login implementation should include displaying social networks icons on the
front page to initiate social login. The settings page will allow choosing which icons to
display and configure the icons size.

Implementation:
Prerequisites (further instructions at the guide on the URL above)
1

Implement the Social Login plugin.

Make sure to register to the onLogin event during page load.

Social network login (step #1 is done on the client side, 2-4 are done on server side)
Clicking one of the icons in the Social Login plugin will initiate a
login flow to the relevant social network. Upon successful login, an onLogin
event will be fired.
1

To avoid fraud, the Gigya signature should be verified. See further

instructions on the URL at the top of the section.
2

The next stage is checking if the user is new. To do this, check if

the isSiteUID field of the userObject parameter (received via the onLogin
event) is true.
3

If it is true this means that the UID is an ID that

your site has provided using the socialize.notifyRegistration method in a
previous login flow, and therefore the user is a returning user.
b If isSiteUID is false, this means the UID was
just generated by Gigya, hence the user is new. Continue to New user
sub-flow.
4 Once the UID exists in your system, identify the user, complete his
login process on your site and mark the user as logged-in.
a

New user sub-flow (all steps are done on the server side)
Check if any required data is missing. If so - ask user to fill
missing data (more info in the URL at the top of the section).
1

If not - check if the users email already exists in your system.

a

If email already exists - proceed to Link accounts

sub-flow.
If not - store the new user in your database. The site
user ID (siteUID) you designate for the user in this step will be used in
the next step.
b

To complete the account registration process, the

socialize.notifyRegistration API should be called. The method receives a
parameter named siteUID. Please set this parameter with the siteUID that you
used in the previous step. This will set the users ID in Gigya to be the same as the
ID your site has designated.
3

Return to step #4 under Social network login.

Link accounts sub-flow (all steps are done on the server side)
If the user has logged on from a social network that returns an
email address, he can choose to link the social account with his existing site
account (both share the same email address). He can also choose to cancel.
1

If the user clicked the Link Accounts button, he

will have to enter his site credentials. These will be authenticated by your
websites authentication system.
b If authenticated, the users siteUID (identifier in
your website) should be retrieved from the sites database.
2 If the user has logged on from a social network that does not return
an email address, he can choose to link the social account with his existing site
account, or enter a different email address. He can also choose to cancel. The next
steps are similar to 1a-1b.
a

Return to steps #3 and #4 under the New user sub-flow.

Site user login (all steps are done on server side)

When a user authenticates using your existing Login form or when
a new user registers using site registration, it is important to notify Gigya of the
user's new state, so as to provide consistent user experience. To implement this,
call the socialize.notifyLogin API method at the end of your existing login flow.
1

notifyLogin should be called by REST and not via Javascript.

Please see:
http://developers.gigya.com/037_API_reference/020_REST_API/socialize.notify
Login
3

Required parameters for socialize.notifyLogin:

siteUID - please set this parameter with the user

ID that you have designated for this user in your database.
b userInfo - a json object that is meant to provide
Gigya with the site users data. The object may include the following
a

fields: nickname, photoURL,thumbnailURL, firstName, lastName, gender,

age, email.
For example: userInfo={ firstName: "David", gender: "m", age:30 }.
If it is a new user, call the socialize.notifyLogin API method
with the newUser parameter set to true. This will enable Gigya to distinguish
between a new site user and a returning site user, allowing Gigya to analyze users'
login/registration behavior with or without Social Login and compare the ratio.
4

When receiving the notifyLogin response on server side, please

make sure to create a session cookie, so as to maintain the client application
synchronized with the user state. See further instructions on:
http://developers.gigya.com/010_Developer_Guide/10_UM360/030_Social_Logi
n#Site_Login_-_Synchronizing_with_Gigya_Service)
5

Using plug-ins to initiate login (plugin usage is done on the client side, actual login
procedure is server side)
Users should be able to login to your site via Gigyas plugins. To
implement this functionality, please follow this guide:
http://developers.gigya.com/010_Developer_Guide/10_UM360/080_Using_Plugi
ns_to_Initiate_Site_Login
1

The connectWithoutLoginBehavior parameter of Gigyas

Global Conf object will determine the precise login behavior when logging-in
from the plugins. See the Settings & Configuration section.
2

Logging Out (client side)

When a user logs out from your site, it is important to notify Gigya
of the user's new state. Within your site logging out flow, please call the
socialize.logout API method.
1

This needs to be done via your client application.

User profiles
Relevant Gigya information and functionality will be embedded into the platforms user profile
page and management sections.
Guidelines:
Gigyas showAddConnectionsUI plugin will be embedded into the user profile
page, in order to display the users social identities. The plugins showEditLinks
property will be set to True, in order to allow the addition and removal of identities.
http://developers.gigya.com/020_Client_API/020_Methods/socialize.showAddConnectio
5

nsUI
Relevant Gamification info will be displayed as part of the profile page. See the
Gamification section.
When deleting a user profile from the platforms user management section, a call
will be sent to Gigyas deleteAccount API, in order to remove the account from Gigya
as well.
http://developers.gigya.com/037_API_reference/020_REST_API/socialize.deleteAccount

Sharing
The Gigya module will support 2 types of sharing: Sharing of a product/order (via the Share-bar
plugin) & action sharing of an order, or when adding to cart (shared via an API).
http://developers.gigya.com/010_Developer_Guide/60_Sharing
Guidelines:
The module would enable to embed a Share-bar plugin on every product and order
page. The Share-bars configuration would allow choosing which social network
buttons will be shown in it (shareButtons parameter). Clients would also be able to
choose where to position the bar.
http://developers.gigya.com/020_Client_API/020_Methods/socialize.showShare
BarUI

When the site recognizes that the user has added an item to his cart, or placed an order,
action sharing will be initiated and the user will be prompt with the advanced sharing
dialog. The Settings & Configuration page would enable to configure the dialogs
showAlwaysShare and showNeverShare parameters. If the order contains multiple
items, the first item will be shared
http://developers.gigya.com/020_Client_API/020_Methods/socialize.showShare
UI

The userAction object defines how the shared content will be shown on the
selected social networks (with consideration to open graph tags).
http://developers.gigya.com/020_Client_API/010_Objects/UserAction_object

The userAction object is automatically pre-populated per the page content

(with title, description & media item). How ever, in certain situations, this automatic

pre-population may not fit the sharing intent. In such cases, the userAction data should be
overridden with the appropriate information. Title, Subtitle, Description,
LinkBack and Media Object should be set with relevant information.

When using the Share-bar from an order page, the Title of the userAction object should
mention the fact that the product was just ordered.

Reactions
The Reactions plugin allows users to react to content in your site and share their reaction to
6

social networks.
http://developers.gigya.com/020_Client_API/020_Methods/socialize.showReactionsBarUI
Guidelines:
A reaction bar will be displayed on every product page. Site owners can
disable/enable it by the configuration page.
The site owners will be able to configure the set of reaction buttons that will be
displayed on the Reactions bar. This is done by the Settings & Configuration page.
As with sharing, the userAction object controls the way information will appear
on social networks. See the Sharing section for more information.
Rating & Reviews
Gigyas Rating & Reviews plugins enable customers to rate, review products and comment on
others reviews. These can later be shared to social networks. The Reviews plugin is based on
Gigyas Comments plugin.
http://developers.gigya.com/010_Developer_Guide/18_Plugins/025_Rating_Reviews
http://developers.gigya.com/020_Client_API/020_Methods/socialize.showCommentsUI
Guidelines:

If the CMS features a reviews capability, the site owner will be able to define
Gigyas Rating & Reviews plugin to replace the generic functionality of the CMS.
http://developers.gigya.com/020_Client_API/020_Methods/socialize.showCom
mentsUI

The site will be able to use the Gigya Rating plugin instead of the generic CMS rating UI.
http://developers.gigya.com/020_Client_API/020_Methods/socialize.showRatingUI

Gigyas functionality will integrate with the existing Ratings & Reviews behavior of the
platform. e.g. if the platform allows to sort/search by rating, it will now be possible to do
this by Gigya rating.

The Comments streamID will be unique per every product on the site.

Each comment posted via the Gigya plugin, will also be saved via the generic
commenting system of the CMS.

The admin will need to setup a Comments category on Gigyas site settings
(see

http://developers.gigya.com/010_Developer_Guide/18_Plugins/025_Rating_Reviews#Set
ting_up_a_New_Comment_Category) and define the Comments category in the
modules Settings & Configuration page.

Users dont have to be logged-in in order to read reviews or comments.

Reviews can only be posted by logged-in users.

Permissions for posting comments are set in Gigyas site settings (see
http://platform.gigya.com).

Activity Feed
Gigyas Activity Feed plugin displays recent user activity on the clients website. Users can
display their own activity, friends activity or everyones activity. Display is subject to privacy
settings.
http://developers.gigya.com/010_Developer_Guide/18_Plugins/060_Activity_Feed_Plugin
Guidelines:
The plugin will be displayed on the front-page of the store.

The site admin will be able to configure which plugins would share to the Activity Feed
(i.e. controlling the plugins scope parameter) and control the privacy settings (i.e.
privacy parameter). See the Settings & Configuration section.

Gamification
Gigyas Gamification plugins will be displayed on the users profile page, showing the users
achievements and driving him them engage in more site activity.
http://developers.gigya.com/010_Developer_Guide/40_Gamification
Guidelines:
The User status and Achievements plugins will be embedded by default in the user
profile page:
http://developers.gigya.com/010_Developer_Guide/18_Plugins/035_Game_Mechanics_P
lugins
The Leader board plugin should be embedded on the store-front by default.
The site admin should be able to further customize the experience by placing any
of the plugins on any page he wishes to use them on his website.
The Notifications plugin is used to enable display of game notifications on every store
page. This is done by putting the gm.showNotifications API on every pages <body>
section.
http://developers.gigya.com/010_Developer_Guide/18_Plugins/035_Game_Mechanics_P
lugins/Notifications#quick_start_implementation
These plugins may be turned on or off via the Settings & Configuration page (see the
Settings & Configuration section).
Other settings for Gamification will be controlled via Gigyas site
(http://platform.gigya.com).
http://developers.gigya.com/010_Developer_Guide/40_Gamification
Basic configuration (Global Conf.)
Gigyas basic configuration is based on a JSON object that sets global Gigya variables before
loading all additional Gigya functionality. This allows these variables to be used within the
different Gigya features.
http://developers.gigya.com/020_Client_API/010_Objects/Conf_object

Guidelines:
This object should be called from every web pages head section and only once.
The actual settings that are defined by this object will be set by the site admin

within the modules Settings & Configuration page. Please see the next section for further
info.

Gigya modules Settings & Configuration page on the CMS

Admins will be able to define Gigya settings inside the modules Settings & Configuration page,
supporting the following settings: (at the very least)
Global settings: (via The Global Conf object:
http://developers.gigya.com/020_Client_API/010_Objects/Conf_object)

Set Gigya API (APIkey parameter) and Secret key (for usage on REST calls)

Set language - lang parameter (default = en)

Set global list of providers (list of social networks to allow sharing with) enabledProviders setting

Usage of short URLs - shortURLs parameter (default = never)

Session expiration - sessionExpiration parameter (default = 0, which means the

session terminates when browser is closed)

Enabling Googles Social Analytics (default = disabled)

http://developers.gigya.com/010_Developer_Guide/80_Reports/Analytics

Login: (via the showLoginUI API:

http://developers.gigya.com/020_Client_API/020_Methods/Socialize.showLoginUI)
1

Enable/disable Gigya Social Login (default = disable)

Set login button style - buttonStyle parameter; standard/fullLogo (default =

fullLogo)

Choose which providers to display - enabledProviders parameter (default = *)

Configure Connect without Login behavior - connectWithoutLoginBehavior

parameter (Default = loginExistingUser; part of the Global Conf object
mentioned in the Global settings paragraph).

Show Gigyas terms link - showTermsLink parameter (default = false)

Sharing:
9

http://developers.gigya.com/010_Developer_Guide/60_Sharing
1

General settings:
Enable sharing to activity feed - controlling the

scope parameter of the showShareUI API (default = both)

2

Share-bar settings: (via the showShareBarUI API:

http://developers.gigya.com/020_Client_API/020_Methods/socialize.showShareB
arUI)
Enable/disable Share-bar on product pages
Enable/disable Share-bar on order pages
Social networks to show on the Share-bar -

shareButtons (default = share,email,pinterest,twitter-tweet,googleplusone,facebook-like; pay attention to the fact that Pintrest requires
adding an image to the userAction object)
Share-bar layout - layout parameter (default =

horizontal)
Share-bar counter configuration - showCounts

parameter (default = right)

3

Share on action settings: (via the showShareUI API:

http://developers.gigya.com/020_Client_API/020_Methods/socialize.showShareU
I)
Enable/disable action sharing when placing an order
Enable/disable action sharing when adding to cart
Share providers to display - enabledProviders

parameter (default = *)
Show Always share checkbox on share dialogs -

showAlwaysShare parameter (default = unchecked)

Show Never share checkbox on share dialogs -

showNeverShare parameter (default = true)

Rating & Reviews: (via the showCommentsUI API:

http://developers.gigya.com/020_Client_API/020_Methods/socialize.showCommentsUI)
1 Enable/disable Reviews plugin

10

Enable/disable Ratings plugin

Set the Comments category ID - categoryID parameter
Set the Ratings category ID - categoryID parameter
Providers - enabledShareProviders parameter (default = *)
Enable sharing to Activity Feed - scope parameter (default=true)
Reactions: (via the showReactionsBarUI API:
http://developers.gigya.com/020_Client_API/020_Methods/socialize.showReactionsBar
UI)
2
3
4
5
6

Enable/disable the plugin

Configuring reaction buttons - reactions parameter. The page should allow

building the Reactions array which is sent via this parameter. This is done by
creating a new Reactions array, adding buttons to the array and configuring the
different attributes of each button.
http://developers.gigya.com/020_Client_API/020_Methods/socialize.showReactio
nsBarUI#Reaction_Object

Providers - enabledProviders parameter (default = *)

Count orientation - showCounts parameter (default = right)

Plugin layout - layout parameter (default = horizontal)

Allow multiple reactions - multipleReactions parameter (default = true)

Reaction count type - countType parameter (default = number)

Enable sharing to activity feed - scope parameter (default=true)

Activity feed: (via the showFeedUI API:

http://developers.gigya.com/020_Client_API/020_Methods/socialize.showFeedUI)
1

Enable/disable the plugin

Site name

Privacy level - will be set the privacy parameter globally for all relevant plugins
(default = private). APIs that are effected by this setting: showCommentsUI,
showReactionsBarUI and showShareUI

Gamification:
http://developers.gigya.com/010_Developer_Guide/18_Plugins/035_Game_Mechanics_P
lugins
1

Enable/disable Gamification (Relevant plugins are: Game status, Challenge

11

Status, Gigya challenge leaderboard and Achievements

http://developers.gigya.com/010_Developer_Guide/18_Plugins/035_Game_Mech
anics_Plugins)
2

Enable/disable game notifications

(http://developers.gigya.com/010_Developer_Guide/18_Plugins/035_Game_Mec
hanics_Plugins/Notifications)

Leaderboard time period - period parameter via the gm.showLeaderboardUI

API (default = 7 days)
(http://developers.gigya.com/020_Client_API/020_Methods/z_GM/gm.showLead
erboardUI#params)

Leaderboard user count - totalCount parameter via the gm.showLeaderboardUI

API (default = 12)
(http://developers.gigya.com/020_Client_API/020_Methods/z_GM/gm.showLead
erboardUI#params)

User data mapping (if supported by the CMS ) - map the Gigya user object
fields to the CMS supported fields. Should be considered on a per CMS system
basis.

Allowing site owners to further customize Gigya functionality than is offered by the
module:
1 Through defining global conf object parameters (affect all Gigya plugins) by a
JS code http://developers.gigya.com/020_Client_API/010_Objects/Conf_object
2 Through overriding the default parameters per plugin, by entering the params JS
code
Login plugin
http://developers.gigya.com/020_Client_API/020_Methods/Socialize.sho
wLoginUI
Share bar plugin
http://developers.gigya.com/020_Client_API/020_Methods/socialize.show
ShareBarUI
Reviews plugin
http://developers.gigya.com/020_Client_API/020_Methods/socialize.show
CommentsUI
Ratings plugin
http://developers.gigya.com/020_Client_API/020_Methods/socialize.show
RatingUI

12

Developer Resources
Gigya developer documentation: http://developers.gigya.com/
Server side SDKs (PHP, .NET, JAVA): http://developers.gigya.com/030_Server_SDKs
Client side API reference: http://developers.gigya.com/020_Client_API/020_Methods
Demo site (downloadable code):
http://developers.gigya.com/010_Developer_Guide/95_Demo_Site
Debugging tools: http://developers.gigya.com/010_Developer_Guide/90_Developer_Tools

13