Sitecore

Skip to end of metadata
Go to start of metadata

Overview

Gigya's connector for Sitecore integrates Gigya's Registration-as-a-Service with your Sitecore-based site. The Gigya connector provides full cloud-based user management, allowing users to register to your site using social network identities such as Facebook, Twitter, LinkedIn, Google and more. We offer a range of plugins integrating your site with the social networks through registration, login, sharing, comments, ratings, reviews and reactions. Plugins are extensible and customizable and can be added in Sitecore's page edit mode.

Integration Functionality

Gigya Registration-as-a-Service

Registration-as-a-Service (RaaS) is a powerful CIAM platform (Customer Identity and Access Management) that enables you to connect with your website and app users, and engage with your customers. RaaS helps you gather critical information about your users, store that information securely and leverage it for an enhanced customer experience. . 

User Profile Integration

You can use Sitecore User Manager to create and delete Gigya users. When using this Connector, users who log in or register to your Sitecore website through Gigya RaaS are not stored in the Sitecore database. Instead, the Sitecore Experience Platform enables you to view, create, remove, and update users who are stored in Gigya. 

To configure which data fields will be displayed for each user in the Sitecore Experience Platform, see Setting User Profile Properties (Field Mapping).

Content Personalization

Any Gigya user fields that are mirrored into the Sitecore Experience Platform are available for use in content personalization rules and conditions.

To create a condition based on a Gigya data field, in the Rule Set Editor, select the condition "where the specific field in the user profile compares to value" (in the Security section of the condition list), and edit "specific field" to a name of a field mirrored from Gigya.

 

Social Plugins 

The Gigya platform includes a series of plugins that integrate your site with users' social networks and create a compelling and fulfilling user experience. These plugins have a fully configurable user interface design:

  • Share – Users can easily Share posts with their social networks friends.
  • Comments – Gigya's Comments plugin enables site users to post comments and have discussions about published content on your site.
  • Loyalty – Also known as "Gamification", this is a social loyalty and rewards platform that can be easily embedded in your website, increasing site engagement and making your users' experience more enjoyable.
  • Reactions – The Reactions plugin allows users to react to content in your site and share their reaction to social networks.
  • Rating & Reviews – The R&R plugins give your customers an easy way to provide feedback on product and content across your site, and then share that feedback with friends in their social networks.

 

Multi-site and SSO Support

The Gigya connector supports multi-site configuration and single-sign-on (SSO). For more information about Gigya's multi-site support, see Site Groups and Single Sign-On

Version and Compatibility

Four versions of Gigya's connectors for Sitecore are currently available on Sitecore's marketplace, supporting the following Sitecore versions: 7.5, 8, 8.1 and 8.2.

Installation and Implementation - RaaS

To install the Gigya Connector for Sitecore 8 and enable Gigya Registration-as-a-Service (RaaS), perform the following:

Then, go back to the main Connector documentation page for configuration and implementation notes.

Prerequisites

To install the connector, you will need: 

1. Install the Connector Package

Download the package from the Sitecore marketplace: https://marketplace.sitecore.net/Modules/G/GigyaSitecore_Connector.aspx

The module is distributed as a Sitecore Package which can be installed using the Installation Wizard (Sitecore desktop > Sitecore > Development Tools > Installation Wizard).

Do not unzip the package. Instead, follow the prompts on the screen to install.

The package contains the following items:

  • Gigya Security provider assembly files
  • Gigya plugins – sub layout, rendering files
  • Gigya Security provider configuration files
  • Sitecore Items
    • Core Database
      • /sitecore/templates/Modules/Gigya Connector/User [Gigya user Profile template]
      • /sitecore/system/Settings/Security/Profiles/Gigya User [Gigya user profile item]
  • Master Database
    • Templates: /sitecore/templates/Gigya Connector/Modules  & sub items
    • Layouts: /sitecore/Layout/layouts/Gigya Connector/
    • Sublayouts: /sitecore/Layout/Sublayouts/Gigya Connector
    • Renderings: /sitecore/templates/Gigya Connector/Rendering Parameters
    • Module items: /sitecore/content/home

2. Modify the Configuration Files

To configure the module’s Sitecore-Gigya connection, you must make some manual changes to the following files:

  • Web.config
  • /App_Config/Security/Domains.config
  • /App_Config/Include/Sitecore.Gigya.Connector.config
  • /App_Config/Sitecore.config


Add a New Domain

Open the /App_Config/Security/Domains.config file and add the following line to the domains element:

<domain name="gigya" ensureAnonymousUser="false" defaultProfileItemId="{0A9F94CB-8CDC-4D8C-8FD0-DF6D69723620}"/>

The defaultProfileItemID attribute defines the profile item that is used for users from the domain if the profile isn’t set for the user explicitly. This is also used by Sitecore’s user manager to represent Gigya profile data in Sitecore.


Configure the ASP.NET Security Providers

The connector module leverages the ASP.NET security model architecture. It includes a custom implementation for Membership and Profile provider that directly interacts with Gigya’s API.

  • If you have Require email verification checked in the RaaS Policies, you will not be able to create Gigya users from Sitecore user manager.
  • When creating Gigya users in Sitecore User Manager, only the email and password fields are utilized. Other fields are ignored.

 

For information about security provider model please visit the MSDN library.

Service

Functionality

ImplementedNot Implemented

Membership provider

Get user(s)

Authenticate

Update

Create User

Reset Password

Delete User

Profile provider

Get user profile

Set user profile

Find user profiles etc.

Delete user profile


Add the Machine Key

Generate the machinekey node under the <system.web> node in the Web.config file (see for example instructions here). This key will later be used for encrypting / decrypting the Gigya application secret stored in /sitecore/system/Modules/Gigya Connector (see below). Your node should look like the following:

<machineKey decryptionKey="[GENERATED KEY]" validation="SHA1" decryption="AES" />

 

Add the Gigya API Key

  • In the Web.config file, go to the <configSections> element in the <Configuration> section and add the following:

    <section name="gigyaAPIKeyCollection" 
    	type="System.Configuration.NameValueFileSectionHandler, System, 
    	Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089" />
  • Also in <Configuration>, add a list of your Gigya domains, each with its own Gigya API Key, as follows:

     

    <gigyaAPIKeyCollection>
    	<add key="default" value="Gigya API key for site #1" />
    	<add key="site name #2" value="Gigya API key for site #2" />
    	<add key="site name #3" value="Gigya API key for site #3" />
    	...
    </gigyaAPIKeyCollection>

    For the key enter the site name or "default"; for the value enter the Gigya API Key. For example:

    Note: If you only have one domain, enter it as the default.


Set the Gigya Data Center

Open the Web.config file, and browse to the <appSettings> element in the <Configuration> section and add the following key:

<add key="GigyaDataCenter" value="<YOUR GIGYA DATA CENTER>"/>

For example:

<add key="GigyaDataCenter" value="us1.gigya.com"/>

If you do not know your data center, see Finding Your Data Center.

The Russian data center and the Chinese data center are only available via their corresponding region-specific Gigya Consoles, so all sites on https://console.ru1.gigya.com can only use the Russian data center and all sites on https://console.cn1.gigya-api.cn can only use the Chinese data center.

 

Set the Gigya Search Timeout Value

Open the Web.config file, browse to the <appSettings> element in the <Configuration> section and add the following:

<add key="GigyaSearchTimeoutInSeconds" value="60"/>


Configure the Switching Providers

For providers to work together with the standard Sitecore security providers (and other custom providers), you must make the following changes to the Web.config file:

  • Change the realProviderName attribute value of the Sitecore provider element under system.web > membership > providers to switcher. It should look like this:

     <add name="sitecore" 
    	type="Sitecore.Security.SitecoreMembershipProvider, Sitecore.Kernel" 
    	realProviderName="switcher" 
    	providerWildcard="%" 
    	raiseEvents="true" />
  • Change the defaultProvider attribute value of the system.web > profile element to switcher. It should look like this:

    <profile defaultProvider="switcher" enabled="true" inherits="Sitecore.Security.UserProfile, Sitecore.Kernel">

Add Domain-Provider Mappings

Open the Sitecore.config file and browse to the <switchingProviders> element in the <sitecore> section.

This section contains three groups: membership, roleManager, and profile.

  • Add the following line to the <membership> group, placing it as the first line in the group:

     <provider providerName="gigya" storeFullNames="false" wildcard="%" domains="gigya"/>
  • Add the following line to the <profile> group, placing it as the first line in the group:

     <provider providerName="gigya" storeFullNames="false" wildcard="%" domains="gigya"/>

The “Switching Providers” section of the config file should now look like this:



Configure the Membership Provider

Add the following element to the system.web > membership > providers section of the Web.config file. If you have a <clear /> tag, delete it and replace with the following:

<add name="gigya" type="GigyaSecurityProvider.GigyaMembershipProvider, GigyaSecurityProvider" 
	applicationName="sitecore" />

Configure the Profile Provider

Add the following element to the system.web > profile > providers section of the Web.config file. If you have a <clear /> tag, delete it and replace with the following:

<add name="gigya" 
	type="GigyaSecurityProvider.GigyaProfileProvider, GigyaSecurityProvider"
	readOnly="false" applicationName="sitecore" />

Set User Profile Properties (Field Mapping)

The Profile Properties determine the data fields that will be displayed in the Admin Manager for each user.

To define a profile property, add a line to the system.web > profile > properties section of the web.config file as follows:

<add type="System.String" name="<PROPERTY NAME>"
	customProviderData="gigya|<CUSTOM PROPERTY PREFIX><PROFILE FIELD NAME IN GIGYA>" />

Attribute

Description

name

Give the property a unique name.

type

.NET type of the property. Currently only System.String is supported

customProviderData

The data required for the profile provider to provide this property:

  • gigya: Tells Sitecore that this property is to be handled by the connector module.
  • Custom Property Prefix (OPTIONAL): Use the prefix is "d_" if the data field is part of Gigya’s data object. Do not use a prefix for any property that is part of Gigya's Profile object. To use a different prefix please also update “GigyaCustomPropertyPrefix” setting.
  • Profile Field Name in Gigya: firstName, lastName etc. See Gigya's Profile object documentation for a list of the available fields.

Example

Use the lines below to have the following fields displayed for each user in the Admin Manager: first name, last name, nickname, age, gender, birth day, birth month, birth year, country, state, city, address, zip, bio, thumbnail URL, and time zone.

 <!-- gigya profile fields-->
  <add type="System.String" name="SocialProviders" customProviderData="gigya|socialProviders" />
  <add type="System.String" name="FirstName" customProviderData="gigya|firstName" />
  <add type="System.String" name="LastName" customProviderData="gigya|lastName" />
  <add type="System.String" name="Nickname" customProviderData="gigya|nickname" />
  <add type="System.String" name="Age" customProviderData="gigya|age" />
  <add type="System.String" name="Gender" customProviderData="gigya|gender" />
  <add type="System.String" name="BirthDay" customProviderData="gigya|birthDay" />
  <add type="System.String" name="BirthMonth" customProviderData="gigya|birthMonth" />
  <add type="System.String" name="BirthYear" customProviderData="gigya|bithYear" />
  <add type="System.String" name="Country" customProviderData="gigya|country" />
  <add type="System.String" name="State1" customProviderData="gigya|state" />
  <add type="System.String" name="City" customProviderData="gigya|city" />
  <add type="System.String" name="Address" customProviderData="gigya|address" />
  <add type="System.String" name="Zip" customProviderData="gigya|zip" />
  <add type="System.String" name="Bio" customProviderData="gigya|bio" />
  <add type="System.String" name="ThumbnailURL" customProviderData="gigya|thumbnailURL" />
  <add type="System.String" name="TimeZone" customProviderData="gigya|timezone" />
<!-- end gigya profile fields-->

<!-- custom gigya fields-->
<!--<add type="System.String" name="d_Familiarity" customProviderData="gigya|d_familiarity" />-->

Extend the Sitecore Profile Item Template

After you have defined the custom properties in the Web.config file, you should extend the Sitecore template to make the properties accessible from the Sitecore CMS security applications. To make the properties accessible:

  • Start Sitecore CMS and login as an administrator and switch to the core database
  • Open the Content Editor, and in the content tree, browse to the /sitecore/templates/Modules/Gigya Connector/User template
  • Add a new field to the template and set its name to exactly the same value as the appropriate property name (for example, Country) in the Web.config file. Set the type to Single-Line Text and select the shared check box.

Click to enlarge

From now on when you edit any user from Gigya in the Sitecore User Manager, you will see the added profile property in the Edit User dialog box in the Profile tab.

Click to enlarge


Enter the Application Key and Secret

Go to /sitecore/system/Modules/Gigya Connector/Module Information and enter the relevant values for the application key and secret. 

The key is encrypted every time you save this definition.



Other Settings

Add the following element to the Configuration > Sitecore > Settings section of the Web.config file:

 <!-- javascript location for the gigya.js Web SDK.
     Note: API key will be added by the connector
     default:http://cdn.gigya.com/JS/gigya.js-->
     
<setting name="GigyaJSUrl" value="https://cdns.gigya.com/JS/gigya.js"/>

<!-- name of gigya user cache default: GUserCache -->
<setting name="GigyaUserCacheName" value="GigyaUserCache"/>

<!-- total user cache size default: 100MB -->
<setting name="GigyaUserCacheLength" value="100MB"/>

<!-- duration (minutes) for which user's would be cached default: 20 -->
<setting name="GigyaUserCacheDuration" value="20"/>
     
<!--security domain name for gigya connector. This is only relevant for gigya RaaS.
    Default: gigya
    Note: if you wish to update this domain please also update domains.config and web.config -->
<setting name="GigyaUserDomainName" value="gigya"/>

<!--prefix for properties stored in gigya's "data" field.-->
<setting name="GigyaCustomPropertyNamePrefix" value="d_"/>


3. Include the Gigya JavaScript 

To enable Gigya on your site you will need to add the following script to the <head> section of your Layout file:

MVC

@Html.Raw(PluginConfigHelper.GetGigyaHeaderScript())
<script src="@Url.Content("~/GigyaConnector/Scripts/gigyaconnector_mvc.js")" type="text/javascript"></script>

WebForms

<%@ Register TagPrefix="gigya" Namespace="Gigya.GigyaConnector.Helpers" Assembly="Gigya" %>
<gigya:GigyaScriptRenderer runat="server" ID="gigyaScript" />
<script type="text/javascript" src="/Scripts/gigyaconnector.js"></script>

For some plugins Gigya recommends adding providers to the header. The default setting for the scripts includes facebook, twitter, linkedin. If you wish to add more, navigate to /sitecore/system/Modules/Gigya Connector/Share/Provider Settings and add the provider name to the list:

Click to enlarge


4. Enable Login, Registration, and Profile Update through Gigya

We recommend using Gigya’s Screen-Sets for login, registration, and profile updates.

The connector module handles authentication and profile edits. To enable authentication include the following code:

Webforms

  • On a sublayout include the following code

    <asp:Placeholder ID="phLoginControls" runat="server" Visible="false">
    	<li>
    		<a href="#" onclick="gigya.accounts.showScreenSet({
    			screenSet:'Default-RegistrationLogin'}); ">
    			Login</a>
    	</li>
    	<li>
    		<a href="#" onclick=" gigya.accounts.showScreenSet({
    			screenSet:'Default-RegistrationLogin',
        		startScreen:'gigya-register-screen}); ">Register</a>
    	</li>
    </asp:Placeholder>
    
    <asp:Placeholder ID="phLoggedInControls" runat="server" Visible="false">
    	<li>
    		<a href="#" onclick=" gigya.accounts.showScreenSet({
    			screenSet: 'Default-ProfileUpdate' }); ">
    		Edit Your Profile</a>
    	</li>
    	<li><a href="#" onclick=" gigya.accounts.logout(); ">Logout</a></li>
    </asp:Placeholder>
    
  • Include the following in the code behind file

    protected void Page_Load(object sender, EventArgs e) {
    	ToggleLoginControls();
    }
    
    protected void LoginUser() {
    	string uid = WebUtil.GetQueryString("uid", string.Empty);
    	bool loginUser = WebUtil.GetQueryString("lgn", "0") == "1";
    	if (string.IsNullOrEmpty(uid) || !loginUser)
    		return;
    	string domainUserName = GigyaSettings.GigyaUserDomainName + "\\" + uid;
    	if (User.Exists(domainUserName)) {
    		Log.Audit("Gigya Connector - user found for uid = {0}".FormatWith(domainUserName), this);
    		if (AuthenticationManager.Login(domainUserName, true)) {
    			Log.Audit("Gigya Connector - sucessfully authenticated uid = {0}".FormatWith(domainUserName), this);
    		}
    		else {
    			Log.Audit("Gigya Connector - could not authenticate uid = {0}".FormatWith(domainUserName), this);
    			// log out to be safe
    			AuthenticationManager.Logout();
    		}
    	}
    	else {
    		Log.Audit("Gigya Connector - could not find user for uid = {0}".FormatWith(domainUserName), this);
    		AuthenticationManager.Logout();
    	}
    	WebUtil.Redirect("/", true);
    }
    
    private void LogoutUser() {
    	bool logoutUser = WebUtil.GetQueryString("lgn", "1") == "0";
    	if (!logoutUser)
    		return;
    	AuthenticationManager.Logout();
    	WebUtil.Redirect("/", true);
    }

Make sure you have included <script type="text/javascript" src="/Scripts/gigyaconnector.js"></script> in the <head> section of your layout file

MVC

On a view rendering include the following code:

<ul class="nav navbar-nav navbar-right">
@{
	if (!Sitecore.Context.User.IsAuthenticated) {
		<li>
			<a href="#" onclick="gigya.accounts.showScreenSet({
				screenSet:'Default-RegistrationLogin' });">
				Login</a>
		</li>
		<li>
			<a href="#" onclick=" gigya.accounts.showScreenSet({
				screenSet: 'Default-RegistrationLogin', startScreen: 'gigya-register-screen' });">
				Register</a>
		</li>
	}
	else {
		<li>
			<a href="#" onclick=" gigya.accounts.showScreenSet({
				screenSet: 'Default-ProfileUpdate' }); ">
				Edit Your Profile</a>
		</li>
		<li><a href="#" onclick=" gigya.accounts.logout(); ">Logout</a></li>
	}
}
</ul>

Make sure you have included the following line in the <head> section of your layout file:

<script src="@Url.Content("~/GigyaConnector/Scripts/gigyaconnector_mvc.js")" type="text/javascript"></script> 


 

 

Implementing the Engagement Add-Ons (Social Plugins)

The connector module includes Sitecore Sublayouts (web forms) and View Renderings (MVC) for several Gigya social plugins.

Configuring Plugin Properties

Comments

The Comments plugin enables site visitors to add comments to a page. For more information, see Comments.

Click to enlarge

Comments Plugin Properties:

PropertyDescription

Category ID

Enter a name for the comments/reviews category.
Stream IDEnter a name for the comments/reviews stream.
Version of the comments category

Enter "2" to use version 2 of the Comments/Rating & Reviews plugin (see more information).

The Category ID and Stream ID fields are required. If you leave one of them empty, Sitecore will allow you to save the properties, but the plugin will not load.

 

Rating & Reviews

The Rating & Reviews plugin enables site visitors to rate your content and add their reviews. For more information, see Rating & Reviews.

Click to enlarge

Rating & Reviews Plugin Properties:

PropertyDescription

Category ID

Enter a name for the comments/reviews category.
Stream IDEnter a name for the comments/reviews stream.
Version of the comments category

Enter "2" to use version 2 of the Comments/Rating & Reviews plugin (see more information).

The Category ID and Stream ID fields are required. If you leave one of them empty, Sitecore will allow you to save the properties, but the plugin will not load.

Reactions

The Reactions plugin displays a row of reaction buttons, such as "Funny", "Geeky" and "Inspiring", which site visitors can use to express their opinion of the content and then share that opinion through their social networks. For more information, see Reactions.

Click to enlarge

Reactions Plugin Properties:

PropertyDescription
Button Style

Select from the drop-down list:

SelectionSample Output
Button+Icon+Text
Button+Text
Button+Icon
Icon+Text
Icon Only
Button setThe details of the buttons to display, formatted as an array of JavaScript objects. See the Reactions Setup page in the Gigya Console for more information and a button building wizard.
Counter Style

How to display the number of clicks on each reaction. Select from the drop-down list:

SelectionSample Output
Vertical
Horizontal
None

Share Bar

The Share Bar plugin displays a row of sharing buttons to help your visitors share your content to their various social networks. For more information, see Share Bar.

Click to enlarge

Share Bar Plugin Properties:

PropertyDescription
Display Style

Select from the drop-down list:

SelectionSample Output
Icons Only
Icons + Text
Share + Icons Only
Share icon

Select an icon for general sharing:

SelectionIcon
Style 1
Style 2
ProvidersSelect the provider buttons you want to include in the Share Bar.
Counter Style

Select from the drop-down list:

SelectionSample Output
Horizontal
Vertical
None

Share

The Share plugin enables you to display a sharing pop-up whenever site visitors perform a share-worthy action, e.g. submitting a comment. For more information, see Share.

Share Plugin Properties:

PropertyDescription
Show Email Button

Select whether you want to display the "Email" and "More" buttons in the Share popup:

Show More Button

Adding the Plugins to Your Site

To enable these plugins on your site, you will need to update placeholder settings and include these sublayouts/renderings as allowed controls. For more details, see the Sitecore Client Configuration Cookbook.

Click to enlarge

Once you have configured the placeholder, you will be able to add these plugins in page edit mode (see instructions below).

The plugins are extensible and customizable. They use Sitecore’s parameter templates to define sublayout/rendering parameters. The modules includes a basic set of options for each plugin, to extend or limit the options available for each plugin, navigate to /sitecore/system/Modules/Gigya Connector and update the options. 

To add a Gigya plugin to a page:

  • In the Sitecore Content Editor, navigate to Sitecore > Content and select your site.
  • Select Presentation >  Details.
  • In the Layout Details window, select the Final Layout tab and click the Edit link for the Default layout.
  • In the Device Editor window, select the Controls tab and click the Add button.
  • In the Select a Rendering window, Select the desired plugin in the Gigya Connector > Plugins folder.
  • Enter the name of the placeholder you want to add the plugin to, check the "Open the Properties" checkbox and click Select.
    Click to enlarge
  • Select or enter the appropriate properties (see details for each plugin above) and save.
  • In the Publish tab select Publish > Publish Item.
  • In the Publish Item window, make sure the Publish subitems and Publish related items options are not checked, and click the Publish button.

 

 

Session Management

When a use is logged in to your site, their session is controlled by Sitecore's session settings, and the session is synced from Sitecore to Gigya. 

  • When the Sitecore session expires, the connector logs the user out from Gigya. 
  • When the Sitecore session is extended, the controller calls accounts.setPolicies to set the session length accordingly.

Personalization

The connector for Sitecore ships with custom rendering rules for Sitecore’s rules engine. With the help of these custom rules you can:

  • Personalize content for one user or for a group of users
  • Market and target content that is based on a user’s online behavior, both on and off the site

The following is a step-by-step explanation on what the site needs to do in order to configure personalization:

The connector’s custom conditional rendering rules allow marketers to manipulate presentation components on the site in real time. 

In order to configure a conditional rendering rule that reads user’s profile:

  1. Navigate to the page where you want to set up personalization.
  2. Select the component you want to personalize.

  3. Select a rendering rule that reads the user’s profile, configure the rule, and select a different data source for the component.

  4. Publish and test.

Logs

Logs for Sitecore are kept in the Sitecore instance data directory (by default, this is the Data folder in the same folder that contains the Website folder). The Gigya module does not keep separate logs  but uses the existing logging practices and settings.

Troubleshooting

General

  • The server clock must be set to GMT+0, otherwise errors and unexpected behaviors may occur. We recommend using NTP daemon to ensure that the server time is accurate.
  • Gigya screen-sets must entirely replace any login, registration etc. screen provided by the CMS. The CMS registration, login and edit profile screens should not be rendered at all. Otherwise, the Gigya screen is placed inside the CMS screen and both will behave unexpectedly. 
  • After changing the value of the application key, you should re-enter the application secret.
 

 

  • No labels