Hybris

Skip to end of metadata
Go to start of metadata

Overview

Create an immersive shopping experience with Gigya’s extension for Hybris. Gigya’s social technology combines the core elements that power e-commerce - product awareness and discovery coupled with customer acquisition and loyalty - into a comprehensive set of features and services that are designed to keep customers engaged as well as increase shopping cart conversions while on Hybris websites.

The Gigya extension provides two main Customer Identity Management packages:

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

  • Social Login: The Gigya extension can be used as an external authentication system, allowing users to sign up to your site using their social networks. Users can register and login to your site with their social network identities, which the site will manage as conventional Hybris user accounts.

The extension supports Hybris multi-site configurations. In addition, the Gigya extension provides a generic Gigya plugin that can be used to embed any of Gigya's social plugins within your Hybris websites, and a purchase synchronization feature that enables you to track user purchase activity using Gigya's Customer Insights analytics tool.

All features and user interfaces are fully configurable, require little time to install and can be controlled from the Hybris Administration Panel.

Please note that support for Gigya Social Login as a separate plugin will not be available in future versions of this extension, starting with Hybris 6.0. Social login will still be available as a feature of RaaS - Registration-as-a-Service.

Version and Compatibility

Gigya's extension v. 2.0 is compatible with Hybris 5.7.

Installation and Implementation

Prerequisites

Before installing the Gigya Extension for Hybris, make sure that:

  • The Hybris platform is installed.
  • The following custom Hybris extensions are installed: commercefacades, yacceleratorstorefront.
  • You have your Gigya API key.
  • You have your Partner Secret or you have created a User Key and User Secret (recommended).

    The Extension will use these credentials to access your data in the Gigya database. Creating a user key and user secret specifically for this extension is more secure than using your Partner Secret.

1. Install the Extension

To install the extension:

  1. Download the extension here.
  2. Copy the gigya-addon folder to ${HYBRIS_BIN_DIR}\custom folder.
  3. Add "gigyacommon" and "gigyalogin" to localextensions.xml.
  4. Run the following commands, replacing yourstorefront with your storefront name:

    ant all
    ant addoninstall -Daddonnames="gigyalogin" -DaddonStorefront.yacceleratorstorefront="yourstorefront"
    ant addoninstall -Daddonnames="gigyacommon" -DaddonStorefront.yacceleratorstorefront="yourstorefront"
    

2. Configure Basic Settings

Log into the Hybris Management Console. In the left sidebar, under Administrator, you should now see a Gigya folder.

If you are setting up your Gigya extension for the first time, right-click gigyaConfig and click Create. For subsequent edits to the configuration, click Search and open your gigyaConfig to edit it.

The general Gigya Administration tab opens:

Click to enlarge screenshot

In this tab, fill out the following fields (some are optional):

RequiredNameDescription
Yes gigyaApiKeyThe site's Gigya API key.
NogigyaDataCenter

The Gigya data center used by your implementation.

The options are:

  • us1.gigya.com for the US data center (default)
  • 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

NogigyaLoginBehavior (Deprecated)In this drop-down, you may choose between "loginExistingUser" or "Always login". The default is "loginExistingUser". See Adding Connections When the User is Not Logged In for information about this option.
NogigyaSiteSecret *The Partner Secret Key (not required if you have a User Key + User Secret).
NogigyaUserKey *Your Gigya User Key.
NogigyaUserSecret *Your Gigya User Secret.
 

* You must enter EITHER gigyaSiteSecret OR gigyaUserKey + gigyaUserSecret.

NomodeIn this drop-down, choose "social" if you want to use Gigya for social login or "raas" if you have acquired and plan to use the full RaaS service.
NoprovidersThe identity providers you wish to use. The default is "*" for all providers. To limit the service to specific providers, enter them in a comma-delimited list (e.g. "facebook,twitter").
NositeIn this box, click the Search button to display a list of sites. Choose the site you want to connect to the extension.

Finally, click Create to save your settings.

User data between Gigya and Hybris is synced based on Gigya's UID. For more information, see UID-Based Sync.

3. Configure Your Own Encryption (OPTIONAL)

By default, the extension includes encryption for the application key and secret. No configuration is required to set up encryption. 

If you wish to configure your own encryption, you may do so by adding code to the local.properties file as follows.

  • Use custom key
  • Use custom key and signature
  • Use custom key, signature and encryption provider

Important

 Customized encryption should only be performed by admins with a good knowledge of Hybris customizations.

In the local.properties file, add lines according to the following example, with the encryption provider you are using. In this example, the provider is Bouncy Castle: 

encryption.provider.signature=BC
encryption.provider.class=org.bouncycastle.jce.provider.BouncyCastleProvider

symmetric.algorithm=256AND256BITAES-CBC-BC
symmetric.key.file=256bit-symmetric.key

When loading a Hybris instance, the public key will be generated inside the symmetric.key file.

You can specify the key directly inside the local.properties file. For more information, see Hybris documentation.

4. Set Up Social Login (OPTIONAL)

To use the extension in Social Login mode, you need to create a Social Login Component to use in your website.

The Gigya Social Login component can be inserted in any secure (HTTPS) page in your website, where it will display as social network buttons (see the setup section below for customization options):

New User Creation

When a user logs in through one of the available social networks, the user is created in the Hybris system if it does not exist already.

Setup

To set up Social Login:

  1. Open the Hybris Management Console.
  2. In the left sidebar, under Administrator, choose WCMS.
  3. Right-click Component and choose Create > GigyaSocialLoginComponent.

    Click to enlarge screenshot

  4. In the component, go to the Administration tab and fill out a Name and ID (e.g. "showLoginUI") and the Catalog Version.
  5. Scroll down to the Unbound section to configure Gigya parameters, such as buttonsStyle and containerID. You will find information about these parameters in the documentation for the Gigya JS API method socialize.showLoginUI.
  6. Optionally, you may use the advancedConfig setting to configure any other parameter that socialize.showLoginUI offers. Enter the parameters in JSON object format, for example:

    {"redirectURL": "http://www.example.com", "showTooltips": "false"}
    
  7. Click Create.

Now you can use the Hybris CMS Cockpit to insert the Gigya Social Login component into a web page.

5. Set Up RaaS (OPTIONAL)

Gigya's Registration-as-a-Service (RaaS) provides a complete, easy-to-use user management package. By inserting a Gigya RaaS component into your Hybris website, you embed one of Gigya's RaaS screen-sets, such as login, registration, or forgot password.

Each screen-set is a full implementation of a website flow, in which the user can progress through the necessary screens, enter information and make choices without any further design or implementation effort on your part. See Gigya's RaaS guide for detailed information about the service.

For example, you may define a Gigya RaaS Component for login and registration, which will add the following link to your site:

Login or Register

When the link is clicked by the user, the following dialog will pop up:

Click to enlarge screenshot

RaaS Screen-Sets and Flows

Gigya's RaaS offers the following screen-sets.

Screen-SetDescriptionImplemented Flows (Click link for more details and a flow diagram)
Default-RegistrationLoginAllows the user to log in or register. Also enables the user to initiate a password reset.Login, Registration, Forgot Password
Default-ProfileUpdateAllows the user to edit their profile.Update Profile
Default-ReAuthenticationEvoke this screen-set to require the user to re-authenticate anywhere added security is needed.Re-Authentication
Default-LinkAccountsWhen a user is trying to register with a social account that shares an email address with an existing registered account, this screen-set can be evoked to merge the two accounts.Link Accounts

New User Creation

RaaS includes social login in that it allows users to log in with a social network; otherwise they can register as a site user with a user ID and password. In any case, new users, whether they are social users (logged in with a social identity) or site users (registered in the site) are created both in the Gigya system and in your Hybris database.

Setup

To set up RaaS:

  1. Open the Hybris Management Console.
  2. In the left sidebar, under Administrator, choose WCMS.
  3. Right-click Component and choose Create > GigyaRaasComponent.
  4. In the component, go to the Administration tab and fill out a Name and ID (e.g. "RaasLogin") and the Catalog Version.
  5. In the Unbound section:
    • Choose the Screen-Set to be invoked by this component, such as "Default-RegistrationLogin" (see the Screen-sets guide for information).
    • Choose the Link Text the component will display, such as "Login". When the user clicks the link, the screen-set you chose will appear.
    • Choose the Mobile Screen-Set. This set of screens will appear if the user is using a mobile device.
    • Choose whether this is a profile editing flow (default is no. If a screen is not designated as Profile Edit, it can not write/change data in the database).
    • You may change the selections in Show Anonymous and Show Logged In if you want the component to be hidden from anonymous users or from logged in users, respectively. By default, the component is visible to everyone.
    • Choose the Start Screen - this is the first screen that will be shown from the available screens in the screen-set.

Make sure that the screen-set IDs defined in your integration's settings match the screen-set IDs defined for your site in the Screen-Sets page in the Gigya console.

  • If your Gigya RaaS was set up in the Gigya Console after 10/26/2015, it is using new default screen-set names, which do not match the screen-set names used by this integration out-of-the-box. To set up your integration to use the correct screen-sets names, go to your integration settings and select Registration-as-a-Service settings. In the screen-set IDs table, copy the ID of every Web Screen-Set into the matching Mobile Screen-Set. For example, in the integration's default settings, the Registration/Login screen-sets are set to Default-RegistrationLogin and DefaultMobile-RegistrationLogin, for web and mobile, respectively. They should both say Default-RegistrationLogin.
  • If your site was set up in the Gigya console before September 2014, it will be using older screen-set names.

See Default Screen-Sets for more information.

Click to enlarge screenshot

  • Click Create.

Now you can use the Hybris CMS Cockpit to insert the Gigya RaaS component into a web page.

Additional Services

Field Mapping

By default, the following fields are mapped from Gigya to Hybris:

  • profile.firstName
  • profile.lastName
  • UID

How to Map a Simple Field



 

 

  1. In the HMC tree, open the Gigya Node and select Gigya Field Mapping.
  2. Under the General tab, give the mapping a name.
  3. Select the synchronization direction from the dropdown.
  4. Enter the names of the Hybris attribute name, the Gigya field name, and the Hybris type:
    • The Gigya attribute is the name of the field in Gigya, e.g. profile.gender.
    • If the Gigya field is a custom field (with the data prefix), select "Yes" under Custom
    • You can find the name and type of the Hybris attribute in the items.xml file, in the attribute qualifier. In the following example, the name of the attribute is "created" and the type is string:

      <attributes>
      	…
        <attribute qualifier="created" type="java.lang.String">
        		 <modifiers read="true" write="true"/>
         		 <persistence type="property"/>
        </attribute>
      <attributes/>
  5. Select the Gigya configuration or site you would like to apply the mapping to. 
  6. Click Create or Save

Complex attributes are Hybris attributes (or Gigya JSON objects) that hold other fields within. To map such fields, you need to enhance the converter (hook). For more information, see below.


Schedule Data Sync

The data in the mapped fields is synced automatically every time a user logs in. In addition, it is synchronized at periodic intervals, defined by two Hybris cron jobs. There are two cron jobs involved with updating data between Gigya and Hybris: GigyaToHybrisUpdateCronjob and HybrisToGigyaUpdateCronjob. By default, they are configured to run every 30 minutes, but you can change the frequency as you wish. To do so: 

  1. In the HMC tree, open the Gigya Module Cronjob folder. Right-click the relevant job and select Edit or Edit in new tab
  2. Select the desired frequency. 
  3. If the frequency you need is not in the list, either enter a cron expression or select Free Interval. Select the appropriate values from the dropdowns. 


Mapping Complex Fields - Advanced

For example, a complex attributes could be a Hybris product. They hold other models inside them: images, price groups, discounts etc.

Sample Hybris Complex Attribute
{
	USA: {
		Texas:{
			Dalas:{
				Population:1.281 million
				Elevation: 131m
				…
}
				}
		}
}

If you want to map attribute from inner layers of the JSON to an attribute in the GigyaUserModel you can set the Gigya attribute’s name, for example profile.countryThis will map attribute that is in the following structure:

{ 
 	Created:”21.03.2016”
 	Registered:”21.03.2016”
 	isActive:”true”
	 Profile:{
			   firstName:”John”
			   lastName:”Smith”
			   country:”USA”
  }
}

The Hybris attribute name is the name of the attribute inside the items.xml file and type system. For example if you have GigyaUserModel.getCountry(), you can write "country" in Hybris’ attribute name.

 

The Hybris GConnector uses a custom converter whose bean ID is gigyaCustomerAccountConverter. To map complex fields, you need to extend this converter, by creating a populator which is added to the converter's list of populators. This is advanced configuration, and requires developer expertise in Hybris. 

To customize a converter: 

  1. Define a custom ID and class for your Hybris populator, for example:

    <bean id="gigyaCustomerKidsPopulator" class="com.gigya.login.service.converters.populators.GigyaCustomerKidsPopulator "/>
  2. Example structure for a populator: 

    public class GigyaCustomerKidsPopulator implements Populator<GSResponse, GigyaUserModel>
    {
     private static final Logger LOG = Logger.getLogger(GigyaCustomerKidsPopulator.class);
    
     @Override
     public void populate(GSResponse gsResponse, GigyaUserModel customerModel)
     {
       customerMode.setKids(gsResponse.getData().getInt(“kids”));
    //More implementation
    }
    }
  3. In the spring of the extension, assign modifyPopulatorList as a parent to your bean. For example, if the name of your bean is gigyaCustomerKidsPopulator, the code would look like this: 

    <bean parent="modifyPopulatorList">
       <property name="list" ref="gigyaCustomerAccountConverter"/>
       <property name="add" ref="gigyaCustomerKidsPopulator"/>
    </bean>

Available converters: 

Converter NameModel
gigyaCustomerAccountConverterGigyaUserModel
gigyaLoginIDsConverterLoginIDsModel
gigyaCustomDataConverterGigyaCustomDataModel

In addition, the gigyaCustomDataReverseConverter is available for converting custom data from Hybris back into Gigya's data (custom) fields. 

Generic Gigya Plugin

The Generic Gigya Plugin allows you to choose any social plugin offered by Gigya insert it into your Hybris website as a component. The functionality and design of each plugin can be customized extensively using Gigya API parameters.

Some of the Gigya plugins are:

  • Share Bar displays a bar of buttons for sharing to social destinations.
  • Comments allows users to add comments in your pages.
  • R&R give your customers an easy way to provide feedback on product and content across your site.
  • Reactions displays a one-click reaction buttons bar, allowing users to easily interact with posts or content on your site.
  • Loyalty plugins add a level of gamification to your website, including Achievements and Leaderboard.

For a full list of social plugins and usage guides, see the Gigya Plugins documentation.

To create the component:

  1. Open the Hybris Management Console.
  2. In the left sidebar, under Administrator, choose WCMS.
  3. Right-click Component and choose Create > GigyaGenericPluginComponent.
  4. In the component, go to the Administration tab and fill out a Name and ID and the Catalog Version.
  5. Scroll down to the Unbound section and enter the function name. This can be any function in the Gigya JS API. For example, to use Gigya's Share Bar plugin, enter "socialize.showShareBarUI". see the Gigya Plugins documentation for descriptions and technical details of the available plugins.
  6. Enter the parameters of the function according to the Gigya JS API documentation. Enter the parameters in JSON object format, i.e. {"key1": "stringvalue1", "key2": "stringvalue2"}.
    For example:

    Click to enlarge screenshot

  7. The Show Anonymous and Show Logged In radio buttons allow you to specify whether the plugin will be visible to anonymous users and to logged-in users. By default, it is shown to everyone.
  8. Click Create.

Notes:

  • For sharing plugins, if a userAction object isn't passed in the function parameters, the plugin will look for an image with relevant Open Graph tags within the same page, and share that image. If no image has Open Graph tags, the plugin will share the largest image in the page.
  • Some Gigya plugins allow user registration. To enable users to register from within a Gigya plugin embedded as a component, make sure to set gigyaLoginBehavior to "Always login" in the General Setup.

Purchase Synchronization

Once you activate the Gigya extension, Gigya's Signals service (if it is available) begins to count user purchases and purchase amounts. Note that Signals is a premium feature and requires separate activation. Information from Signals is used in Customer Insights and the accumulated purchase values will show under Revenue Activity in Customer Insights.

Customer Insights allows you to analyze your website's performance by cross-referencing social network information, such as demographics and Facebook Likes, against the customers' activity on your site, including purchases.

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.

Save

Save

Save

Save

  • No labels