Gigya Connector for Sitecore 7

Skip to end of metadata
Go to start of metadata

Overview

Gigya's Sitecore Connector is a powerful addition to any Sitecore website enabling a wide range of fully configurable customer identity management features that increase user engagement and time spent on your 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.

This document provides an overview of the Gigya supported functionality integrated with Sitecore. 

Main Features

Gigya Registration-as-a-Service

Registration-as-a-Service (RaaS)  is an end-to-end user management system package. This platform offers a comprehensive cloud-based user registration system that supports login by social networks while allowing sites to maintain a unified user database for both social and traditional site authentication. For additional information and advanced implementation options see Registration-as-a-Service.

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 conector supports multi-site configuration and single-sign-on (SSO).

The sitecore connector is developed and maintained by Xcentium. For more information and for troubleshooting please visit Xcentium.

Version and Compatibility

The Gigya Sitecore Connector is compatible with Sitecore version 7.2 or higher. 

The Gigya Sitecore Connector requires Gigya's Registration-as-a-Service (RaaS). RaaS is a premium package that requires activation. If it is not part of your site package please contact your Gigya Account Manager or submit a support form. You can also access the support page by clicking "Support" on the upper menu of Gigya's Admin Console.

Implementation

Gigya Setup

Set up each Sitecore site that you intend to use with Gigya using the Site Setup guide.

You will generate an Gigya API key for each site and a single Secret Key for your account.

Gigya's dashboard enables you to customize your plugins using menus and instant previews, generate the code for the customized plugin, and paste it into the Sitecore code. Plugin adjustment should only be done when adjustments to the base Sitecore integration of Gigya are needed.

Sitecore Setup

Installing the Connector Module

The Gigya Sitecore Connector is available at https://marketplace.sitecore.net/Modules/G/GigyaSitecore_Connector.aspx?sc_lang=en

The module is distributed as a Sitecore Package and should be installed using the Installation Wizard. To open the wizard, go to the Sitecore Desktop, click "Sitecore", click "Development Tools" and click "Installation Wizard".

Modifying the Sitecore Configuration Files

To configure the module to connect Sitecore with Gigya, you must make some manual changes to the following files:

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

Follow the instructions below.

  • 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 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.

The current version of the connector does not support Create User and Delete User operations. We recommend using Gigya’s screen-sets for these operations. For information about the security provider model, visit the MSDN Library.

Membership ProviderProfile Provider

Implemented:

  • Get user(s)
  • Authenticate
  • Update

Not implemented:

  • Create User
  • Reset Password
  • Delete User

Implemented:

  • Get user profile
  • Set user profile
  • Find user profiles

Not implemented:

  • Delete user profile

 

 

  • Configure Switching Providers:

For providers to work together with the standard Sitecore security providers and with other custom providers, you have to make the following changes to web.config:

  • Under system.web > membership > providers, change the realProviderName attribute of the sitecore provider element to "switcher":
<add name="sitecore" type="Sitecore.Security.SitecoreMembershipProvider,Sitecore.Kernel" realProviderName="switcher" providerWildcard="%" raiseEvents="true" />
  • In the system.web > profile element, change the defaultProvider attribute to "switcher":
<profile defaultProvider="switcher" enabled="true" inherits="Sitecore.Security.UserProfile, Sitecore.Kernel">
  • Add the Gigya API Key and Secret Key:
    • In the web.config file, in the <configuration> section, in the <config Sections> element, add the following line, inserting your API key in the appropriate place:
<section name="gigyaAPICollection" type="System.Configuration.NameValueFileSectionHandler, System, Version=4.0.0.0, Culture=neutral, PublicKeyToken=API-KEY-HERE" />
  • In the same element, add the secret key:
<add key="GigyaSecretKey" value="SECRET-KEY-HERE" />
  • Add the Gigya Site API Collections:

In the web.config file, under the <configuration> section, add a gigyaAPIKeyCollection element in the following format. Have a separate line for each one of your relevant sites, with the site name as the key and the Gigya API key as the value.

<gigyaAPIKeyCollection>
    <add key="default" value="API-KEY-FOR-ONE-SITE">
    <add key="SITE-NAME-HERE" value="API-KEY-FOR-THAT-SITE">
</gigyaAPIKeyCollection>
  • Add Domain-Provider Mappings:

Open the web.config file, and browse to the <switchingProviders> element in the <sitecore> section. This section contains two groups: <membership> and <profile>.

  • Add the following line to the <membership> group:
<provider providerName="gigya" storeFullNames="false" wildcard="%" domains="gigya"/> 
  • Add the following line to the <profile> group:  
<provider providerName="gigya" storeFullNames="false" wildcard="%" domains="gigya"/> 
  • Configure the Membership Provider:

Add the following element to the system.web > membership > providers section of the web.config file:

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

Note that the applicationName should be "sitecore".

  • Configure the Profile Provider:
    • Add the following element to the system.web > profile > providers section of the web.config file:
 <add name="gigya" type="GigyaSecurityProvider.GigyaProfileProvider, GigyaSecurityProvider" readOnly="false" applicationName="sitecore" />

Note that the applicationName should be "sitecore".

  • Add the following profile properties to the system.web > profile > properties section of the web.config file:
<!-- 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" />-->
  • Add a profile Property:

Define the properties by adding the following element to the properties section:

<add type="System.String" name="<Property name>" customProviderData="gigya|<custom_property_prefix><Gigya_Property_Name>" /> 
  • name: The unique name of the property
  • type: .NET type of the property: currently only System.String is supported
  • customProviderdata: Any data required by the provider serving this property.
    • gigya: Means that this property is to be handled by the connector module.
    • custom_property_prefix: Required only if the property is part of Gigya's data object. Do not use for a property that is part of Gigya's profile object. The default value is "d_". if you want to use a different prefix, update the "GigyaCustomPropertyPrefix" setting accordingly.
    • Gigya_property_name: "firstName", "lastName", etc.

 

  • Extend the Sitecore Profile Item Template:

Having defined the custom properties, the next step is to extend the Sitecore template to make the properties accessible from the Sitecore CMS security applications.

  • Start Sitecore CMS and log in as an administrator.
  • 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 with a name matching the appropriate property name (e.g. "Country") in the web.config file. Set the type to "Single-Line Text" and select the "Shared" checkbox.

 

  • Other Settings:
 <!-- javascript location for gigya's socialize.js. Note: API key will be added by the connector. default:http://cdn.gigya.com/JS/socialize.js -->
<setting name="GigyaJSUrl" value="http://cdn.gigya.com/JS/socialize.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_"/>

Adding 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 the following WebControl:

<%@ Register TagPrefix="gigya" Namespace="Gigya.GigyaConnector.Helpers" Assembly="Gigya" %>

Add the following scripts:

<gigya:GigyaScriptRenderer runat="server" ID="gigyaScript" />
<script type="text/javascript" src="/Scripts/gigyaconnector.js"></script>

For some plugins, you may choose providers (such as Facebook) within the header. The default setting for the scripts includes Facebook, Twitter and 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.

Implementing the Gigya Plugins

Enabling the Gigya Plugins

The connector module includes Sitecore Sublayouts (web forms) and View Renderings (MVC) for the following Gigya plugins:

  • Registration-as-a-Service UI Builder
  • Share
  • Share Bar
  • Follow Bar
  • Comments
  • Ratings and Reviews

To enable them on your site, you must first update your placeholder settings to include these sublayouts/renderings as allowed controls.

For more details see http://sdn.sitecore.net/upload/sitecore6/64/client_configuration_cookbook_sc64-usletter.pdf.

The plugins are extensible and customizable. They user Sitecore's parameter templates to define sublayout/rendering parameters. To extend or limit the options available for each plugin, go to /sitecore/system/Modules/Gigya Connector and update the options.

Adding a Gigya Plugin

To add a Gigya plugin to your content:

  1. In the page editor, select an appropriate placeholder (that has been configured to include the relevant plugin).
  2. Select the desired plugin from the list of renderings (sublayouts).
  3. Save and reload the page

Registration-as-a-Service Integration - Login, Registration and Profile  

The Connector module includes code to handle authentication and profile updates. To enable authentication, include the following:

Web Forms

  • 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>     

 See the UI Builder guide for more information.

  • 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);
}  
  • Ensure you have included <script type="text/javascript" src="/Scripts/gigyaconnector.js"></script> to 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>

 See the UI Builder guide for more information.

  • In the <head> section of your layout file, ensure that you have included
<script src="@Url.Content("~/GigyaConnector/Scripts/gigyaconnector_mvc.js")" type="text/javascript"></script>
  • Authentication is handled by a controller that is invoked by loginEventHandler and logoutEventHandler defined in gigyaconnector_mvc.js.

 

Personalization    

XCentium’s Gigya 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:

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

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

  • Publish and test.

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.