(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.
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 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:configuration accordingly. Go to the
Set Login Identifier to "Email" - this will make sure that Email is your sites unique login identifier.
- 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.
- Go to the Screen-Sets page, after logging into the Gigya Admin Console.
- Locate the Default-LinkAccounts screen-set and click its UI Builder link.
- In the UI Builder window's Screens list (on the left), select the Link Account screen.
- 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.
- Click the Save Button.
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.firstName and .lastName as required fields in RaaS which users can fill in during registration/login:
- Log into the Gigya Admin Console and go to the Screen-Sets page.
Locate the Default-RegistrationLogin screen-set, and click its UI Builder link.
Set First Name and Last Name to be required user registration fields:
- In the UI Builder window's Screens list select the Registration screen.
- Click First Name to select it. Its details will appear on the right under Properties.
- In Schema (below the properties) check the Required checkbox.
- Click Last Name to select it and then check the Required checkbox for that as well.
- In the UI Builder window's Screens list, select the Registration Completion screen.
- Drag a new textbox into the screen (from the Controls on the bottom left).
- Click on the textbox to select it. Its details will appear on the right under Properties.
- Change Mapped Field to Profile->firstName; change Label to "First Name".
- Repeat steps f-h for the Last Name field (Profile->lastName).
- 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:
- In the Magento console, go to System > Configuration > Gigya User Management.
- Select Registration-as-a-Service. Confirm or edit the settings as needed.
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.
|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.|
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:
|||Web Screen Set ID||Default-RegistrationLogin||Name 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 ID||gigya-login-screen||Name 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 ID||gigya-register-screen||Name 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 ID||Default-ProfileUpdate||Name 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 Links||Yes|
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.
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:
- 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>
- 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:
In your desired XML layout page, add a block defined as follows:
For all pages except one-page checkout:
For the one-page checkout page:
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.
- 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).
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".
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".
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.
|Scenario||Magento Status||Gigya Status||Result|
|Gigya session is timed out but the Magento session hasn't ended yet.||User logged in||User not logged in||In 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 in||User logged in|
The user will be able to retry logging in.
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.
By default, the following fields are synchronized:
Adding Fields to the Mapping
To map additional user data, beyond the default fields, follow the instructions below:
Locate the user field in Gigya that you want to map.
Gigya Data Structure Description Example 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 see documentation)object ( Holds personal data such as name, gender, age, address and more. profile.gender Data object Can be used to hold custom data about the user. data.test1
Find the relevant field in Magento or create a custom field if necessary.
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.
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).
For each field pair (each object in the array), the following parameters are specified:
|||magentoName||Field name in Magento (case sensitive)|
|||magentoType||The field data type in Magento - int (short/long), string (varchar(X)), date, Boolean|
|||gigyaName||Field in the Gigya schema|
|||gigyaType||The field data type in Gigya|
|||direction||Optional key to specify the mapping direction. The options are:|
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:
- 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.
- Register an observer for the gigya_pre_field_mapping event. This goes in the frontend section of the config.xml file.
In the observer, use getGigyaAccount() to get all Gigya account data:
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
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:
- 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:
How to Customize Field Mapping: Magento to Gigya
To perform advanced field mapping from Magento to Gigya:
- Create a mapping in the mapping configuration file.
- Register an observer for the pre_sync_to_gigya event. This goes in the adminhtml section of the config.xml file.
In the observer, use getCmsArray() to get an array of Magento user fields:
Adjust the necessary fields to produce the information you want to map into Gigya.
- 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: