Gigya Job Openings

Using RaaS with Magento

Skip to end of metadata
Go to start of metadata

« Back to Gigya Extension for Magento 1.x

 

Overview

The Gigya Extension for Magento offers complete support of Registration-as-a-Service  (RaaS), Gigya's end-to-end user management system.

Using RaaS within a Magento site requires some additional configuration. The necessary steps are detailed below.

Click to enlarge screenshot

When RaaS is applied in Magento, it replaces and overrides the Magento user management system. To access the Magento dashboard and sign in as an administrator after activating Gigya's RaaS, enter /index.php/admin after your site's URL (e.g. http:///index.php/admin). This option is only accessible to users with Magento admin privileges.

RaaS Basic Implementation

Setting up RaaS involves the following steps:

1. Migrate Your User Data

If you are already using Magento's user management you will need to migrate your Magento user DB to RaaS. Please contact your Gigya Customer Engagement Executive to perform this migration.

2. Configure Gigya for RaaS

  • Enable RaaS: RaaS is a premium package that requires separate activation. If it is not part of your site package please contact your Gigya Implementation Consultant.
  • Make sure that email is a unique identifier: This is a Magento requirement, and you'll need to adjust RaaS Policies configuration accordingly. Go to the Policies page in the Gigya admin console. You need to be logged in to access this page. The Policies page may also be accessed by clicking Settings in the upper menu and then Policies in the left menu: 
    Click to enlarge screenshot

    1. Set Login Identifier to "Email" - this will make sure that Email is your sites unique login identifier.

    2. Set Link Accounts Support to "All identities" - This will make sure uniqueness of email in the system. If any account on the system uses the email entered by the user as a login identifier, the user is prompted to link the social network to that account.
  • Remove the "Create new account" link from the "Link Account" screen: Since Magento requires unique email per account, this link would lead to an error, because it allows creating a second account with the same email. Follow the steps below.
  1. Go to the Screen-Sets page, after logging into the Gigya Admin Console.
  2. Locate the Default-LinkAccounts screen-set and click its UI Builder link.
  3. In the UI Builder window's Screens list (on the left), select the Link Account screen.
  4. Locate the "To create new account, click here" link at the bottom of the screen (see screenshot), and erase it by clicking the X next to it.
  5. Click the Save Button.

Click to enlarge screenshot

Adding Required Fields to the RaaS Registration flow

The Magento Customer object requires the Firstname and Lastname fields. If these fields are not provided by RaaS, the module generates them. Do the following to define profile.firstName and profile.lastName as required fields in RaaS which users can fill in during registration/login:

  1. Log into the Gigya Admin Console and go to the Screen-Sets page.
  2. Locate the Default-RegistrationLogin screen-set, and click its UI Builder link.

  3. Set First Name and Last Name to be required user registration fields:

    1. In the UI Builder window's Screens list select the Registration screen.
    2. Click First Name to select it. Its details will appear on the right under Properties.
    3. In Schema (below the properties) check the Required checkbox.
    4. Click Last Name to select it and then check the Required checkbox for that as well.
    5. In the UI Builder window's Screens list, select the Registration Completion screen.
    6. Drag a new textbox into the screen (from the Controls on the bottom left).
    7. Click on the textbox to select it. Its details will appear on the right under Properties.
    8. Change Mapped Field to Profile->firstName; change Label to "First Name".
    9. Repeat steps f-h for the Last Name field (Profile->lastName).
  4. Click the Save button.

If your screen-sets were defined before September 2014 they may use different screen-set names, i.e. "Login-Web" and "Mobile-Login". See earlier screen-set versions for more information.

3. Configure RaaS Settings in Magento

After installing the Gigya Extension as described in Magento 1.0 and configuring the Gigya global settings:

  1. In the Magento console, go to System > Configuration > Gigya User Management.
  2. Select Registration-as-a-Service. Confirm or edit the settings as needed.
  3. Test your RaaS settings by going to your front-end site and trying to log in.

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.

Required?FieldDefault Description
Login/Registration Screen Sets - The screens used for new user registration and existing user login. For more information, see the UI Builder tool and the Default Screen-Sets. Changes to these settings require prior definition of screen-sets.
Session ManagementMagento

Choose whether the session is managed by Magento or Gigya. When the session is led by Gigya, define the length of the session as follows:

  • In the Magento console, under Gigya Global, scroll down to Advanced configuration and set the sessionExpiration parameter to the length of the session, in seconds. For example:

    {
    'sessionExpiration': 30000
    }

  • If a value is not defined for sessionExpiration or if the session is led by Magento, the length of the session is determined by the general session configuration for Magento: In the General settings, under Web > Session Cookie Management, the number of seconds defined for the Cookie Lifetime.

Web Screen Set IDDefault-RegistrationLoginName of a web screen-set containing the screens used in managing user login.
Mobile Screen Set ID Name of a mobile screen-set containing the screens used in managing user login (if different from the web screen-set).
Login Screen IDgigya-login-screenName of the initial user login screen. This is a screen defined in the web and mobile screen-sets (with the same name in both). The default screen set uses the same screens with different CSS.
Register Screen IDgigya-register-screenName of the new user registration screen. This is a screen defined in the web and mobile screen-sets (with the same name in both). The default screen set uses the same screens with different CSS.
Profile Screen Sets - The screens used for entering and updating user profile information.
Web Screen Set IDDefault-ProfileUpdateName of a web screen-set containing the screens used in entering user profile details.
Mobile Screen Set ID Name of a mobile screen-set containing the screens used in entering user profile details (if different from the web screen-set)..
Override Magento Links
Override Magento LinksYes
  • Select Yes to override the Magento Login, Registration and Edit Profile links, so that instead of sending visitors to the Magento page, redirecting the user to the relevant Gigya RaaS screens instead of Magento pages.
    If you use the default Gigya theme (skin), the links are already installed as default, but if you use your own theme, you will need to insert the RaaS classes in the relevant places.
  • Select No if you don't want to use these links but to display the screen-sets embedded in the page (see DIV IDs section).
DIV IDs
Login 

Specify HTML DIV IDs to embed the respective screen-sets in the page.

Leave these fields empty to have the screen-sets appear as pop-ups.

Register 
Profile 

Customization

Adding Gigya Screen-Sets Elsewhere in the Site

By default, the Gigya extension implements the Gigya RaaS screen-sets by overriding the Login, Registration and Profile links in the default theme.

To add screen-sets elsewhere in the site:

  1. In the page template HTML, add a DIV container for the desired screen-set. For example, to display the Gigya RaaS registration screen-set in your store's checkout page, add the following in the checkout page template: <div id="gigyaRegister"></div>
  2. In the Gigya User Management settings in the admin console, specify the ID of the DIV under the relevant field. For the above example, specify "gigyaRegister" in the Login field.

Using the Generic Screen-Set Block

For added flexibility, the extension offers the generic screen-set block, which allows you to add a Gigya screen-set anywhere in the site using different parameters than those you specified in the RaaS Settings page.

To use the generic screen-set block:

  1. In your desired XML layout page, add a block defined as follows:

    • For all pages except one-page checkout:

      <block type="Gigya_Social_Block_Raas_ScreenSets" template="gigya/raas/screenset.phtml" name="myBlockName">
      	<action method="setData">
      		<name>params</name>
      		<value>
      		    <parametername1>value1</parametername1>
      		    <parametername2>value2</parametername2>
      			...
      		</value>
      	</action>
      </block>
    • For the one-page checkout page:

      <block type="Gigya_Social_Block_Raas_ScreenSets" template="gigya/raas/onepage/screenset.phtml" as="login" name="gigya.onepage.login">
      	<action method="setData">
      		<name>params</name>
      		<value>
      		    <parametername1>value1</parametername1>
      		    <parametername2>value2</parametername2>
      			...
      		</value>
      	</action>
      </block>
  2. Inside the <value></value> tags, specify each parameter as <parametername>value</parametername>.

    • You can set any parameter that is listed as a parameter of Gigya's accounts.showScreenSet API method.
    • In addition, the text parameter (optional) sets the text for the link that the user will click to bring up the screen-set pop-up. If you set the text parameter, the screen-set will be rendered in pop-up mode.

Notes:

  • You must specify either the text parameter (which will render the screen-set in pop-up mode) or the containerID parameter (which will cause the screen-set to be embedded in the page).
  • In embedded mode, the block renders a DIV with the ID specified in containerID. To display multiple instances of a screen-set on the same page, you must pass a unique containerID value to each one.
  • The block code does not perform validation on the parameters/values before sending them to Gigya. Passing parameters that don't exist etc. will cause an error.
  • The block code does not take into account the user's logged-in/logged-out state. Whichever screen-set you specify, e.g. a login/registration screen-set, will be rendered regardless of whether the user is already logged in. To recognize and handle the user's state, you can use Magento's <customer_logged_out> and <customer_logged_in> layout handles, as described in this tutorial ("Doing different things for logged in vs. not logged in users" section).

Examples

Example #1 (in any page except checkout): The following XML will render the "custom-registration-login" screen-set, starting with the "custom-register-screen" screen, in a container DIV with the ID "gigya-registration".

<block type="Gigya_Social_Block_Raas_ScreenSets" name="raas.screens" template="gigya/raas/screenset.phtml">
	<action method="setData">
		<name>params</name>
		<value>
		    <containerID>gigya-registration</containerID>
		    <screenSet>custom-registration-login</screenSet>
		    <startScreen>custom-register-screen</startScreen>
		    <cid>test</cid>
		</value>
	</action>
</block>

Example #2 (in one-page checkout): The following XML added to the checkout page will render the "Default-RegistrationLogin" screen-set, starting with the "gigya-login-screen" screen, in a container DIV with the ID "your-container-id".

<block type="Gigya_Social_Block_Raas_ScreenSets" as="login" name="gigya.onepage.login" template="gigya/raas/onepage/screenset.phtml">
	<action method="setData">
		<name>params</name>
		<value>
			<containerID>your-container-id</containerID>
			<screenSet>Default-RegistrationLogin</screenSet>
			<startScreen>gigya-login-screen</startScreen>
		</value>
	</action>
</block>

Session Management

When RaaS is activated, the login session is controlled by Gigya. If the system finds that the user is logged into Gigya but not logged into Magento, or vice versa, the Magento session will be created or ended to match the Gigya session.

Examples:

ScenarioMagento StatusGigya StatusResult
Gigya session is timed out but the Magento session hasn't ended yet.User logged inUser not logged inIn the next Magento page load, the user will be logged out of Magento.
The user has logged in through Gigya but a Magento session was not created due to an error.User not logged inUser logged in

The user will be able to retry logging in.

Field Mapping

Once RaaS overrides Magento's user management, the user profile is managed by Gigya and saved in Gigya's database. However, specific user data fields are synchronized between Gigya and Magento.

Fields are synchronized for a user when the user logs in, registers, or updates their profile.

Fields are also synchronized when a Magento administrator makes changes to user's details through the Magento admin console. In this case, the new values are copied to Gigya.

Default Mapping

By default, the following fields are synchronized:

  • Gigya UID

  • First Name

  • Last Name

  • Email

Adding Fields to the Mapping

To map additional user data, beyond the default fields, follow the instructions below:

  1. Locate the user field in Gigya that you want to map.

    Gigya Data StructureDescriptionExample
    Account object (see documentation)Contains general fields such as the Gigya UID, time created, last login etc. Also contains the profile object and the data object.UID
    Profile object (see documentation)Holds personal data such as name, gender, age, address and more.profile.gender
    Data objectCan be used to hold custom data about the user.data.test1
  2. Find the relevant field in Magento or create a custom field if necessary.

  3. If this is your first time configuring the field mapping in this implementation:

    • Choose a name for the file and a path in the server, e.g. /Gigya/Social/etc/mappings.json.
    • In your local.xml file, add the path to the configuration file as follows. Note: You have to specify the full path from the server root.

      <global><gigya><mapping_file>some_path_to_a_file</mapping_file></gigya></global>
       
      For example:
      <global><gigya><mapping_file>/usr/share/gigya/magentoee/app/code/community/Gigya/Ds/etc/mappings.json</mapping_file></gigya></global>
  4. In the mapping configuration file, enter the field mapping as an array of JSON objects, with an object for each mapped pair.

Example: The following configuration file specifies the following:

  • The profile.gender field from Gigya should be copied into the gender field in Magento
  • The data.test1 field from Gigya should be copied into the custom1 field in Magento and vice versa (bi-directional mapping).
[
  {
    "magentoName": "gender",
    "magentoType": "int",
    "gigyaName": "profile.gender",
    "gigyaType": "string",
    "direction": "g2cms"
  },
  {
    "magentoName": "custom1",
    "magentoType": "string",
    "gigyaName": "data.test1",
    "gigyaType": "string",
    "direction": "both"
  }
]

For each field pair (each object in the array), the following parameters are specified:

Required?KeyDescription
magentoNameField name in Magento (case sensitive)
magentoTypeThe field data type in Magento - int (short/long), string (varchar(X)), date, Boolean
gigyaNameField in the Gigya schema
gigyaTypeThe field data type in Gigya
directionOptional key to specify the mapping direction. The options are:
  • g2cms - copy the field value from Gigya to Magento

  • cms2g - copy the field value from Magento to Gigya

  • both (default value) - update the field value in both directions

The mapping configuration file can only be used to map simple field types, such as integers and strings. To map arrays and complex objects, or to format data or perform any manipulations, use event observers.

Using Events and Observers for Advanced Field Mapping

To map complex fields or to customize your mapping further, you can use Magento's Events and Observers.

Gigya provides the following events for field mapping:

  • gigya_pre_field_mapping: This  event is triggered before user data coming from Gigya is updated in Magento.
  • pre_sync_to_gigya: This  event is triggered before user data from Magento goes out to Gigya.

You can register observers for these events in order  to intervene in the middle of the data transfer process and manipulate the data:

 

See our sample module on Github for an example of a custom module for Magento that uses the Gigya extension's events to define custom field mapping.

How to Customize Field Mapping: Gigya to Magento

To perform advanced field mapping from Gigya to Magento:

  1. Create a mapping in the mapping configuration file as explained in the previous section. 
    • For example, mapGigya's profile.birthDay to Magento's birthdate field, dob. This is not a useful mapping as is because profile.birthDay contains only the day of month, not the full birth date, but we will adjust it using the observer.
  2. Register an observer for the gigya_pre_field_mapping event. This goes in the frontend section of the config.xml file.
  3. In the observer, use getGigyaAccount() to get all Gigya account data:

    $gigyaAccount=$updater->getGigyaAccount();

    This allows you to access individual fields using:

    • $gigyaAccount['<fieldname>'] for fields in the Account object
    • $gigyaAccount['profile']['<fieldname>'] for fields in the Profile object
    •  $gigyaAccount['data']['<fieldname>'] for fields in the Profile object
  4. Adjust the Gigya account field values as necessary to produce the information you want to map into Magento.

    •  For example, use the following code to turn Gigya's profile.birthDay field into a full birthdate field:

      $gigyaAccount['profile']['birthDay'] = $gigyaAccount['profile']['birthYear'] . "-" . $gigyaAccount['profile']['birthMonth'] . "-" . $gigyaAccount['profile']['birthDay'];
  5. Use setGigyaAccount() to enter your changes. This information will now be imported into Magento based on the mapping specified in the mapping configuration file.

See the full observer method:

public function convertDobFromGigya($observer) {
	$updater = $observer->getData("updater");
	$gigyaAccount = $updater->getGigyaAccount();
	$gigyaAccount['profile']['birthDay'] = $gigyaAccount['profile']['birthYear'] . "-"
		. $gigyaAccount['profile']['birthMonth'] . "-"
		. $gigyaAccount['profile']['birthDay'];
	$updater->setGigyaAccount($gigyaAccount);
}

How to Customize Field Mapping: Magento to Gigya

To perform advanced field mapping from Magento to Gigya:

  1. Create a mapping in the mapping configuration file.
  2. Register an observer for the pre_sync_to_gigya event. This goes in the adminhtml section of the config.xml file.
  3. In the observer, use getCmsArray() to get an array of Magento user fields:

    $cmsArray=$updater->getCmsArray();
  4. Adjust the necessary fields to produce the information you want to map into Gigya.

  5. Use setCmsArray() to enter your changes. This information will now be imported into Magento based on the mapping specified in the mapping configuration file.

See the full observer method:

public function convertDobToGigya($observer) {
	$updater = $observer->getData("updater");
	$cmsArray = $updater->getCmsArray();
	$dateParts = explode("-",$cmsArray['dob']);
	$cmsArray['birthYear'] = $dateParts[0];
	$cmsArray['birthMonth'] = $dateParts[1];
	$cmsArray['birthDay'] = $dateParts[2];
	$updater->setCmsArray($cmsArray);
}

 

Save

Save

Save

Save

Save

Save