For information about the Magento 1.x GConnector, see Magento 1.0.
The GConnector for Magento 2 is an extension that allows you to easily integrate Gigya's Customer Identity with your Magento store. With the GConnector, you can easily implement such features as authentication, profile management, data analytics and third-party integrations. Increase registration rates and identify customers across devices, consolidate data into rich customer profiles, and provide better service, products and experiences by integrating data into marketing and service applications. The GConnector helps you integrate Gigya RaaS in your Magento stores quickly and easily, without compromising the unique look and different requirements and needs of each Magento store.
The connector includes the following features:
- Multi-site support (SSO)
- Field mapping
- Data Store sync
- Back office (bi-directional) sync (configured via field mapping)
- UID-based sync
- Session management
Version and Compatibility
The latest version of the extension is compatible with Magento Enterprise Edition versions 2.2.x and 2.3.0.
This extension supports PHP versions 7.0.x and 7.1.x
For installation instructions, see Magento 2 - Gigya Extension Installation Guide .
The Gigya Extension replaces the sign-in, registration, and customer account info pages in Magento's default theme (<Magento root>/customer/view/frontend/layout/ folder) by providing layout XML files that override the default layout files.
After installing, configure the basic Gigya settings in Magento:
In the Magento admin console, go to Stores > Configuration > Gigya Identity Management > General Settings.
Enter the following details:
The Gigya API Key for your site, as displayed in the homepage of the Gigya Console.
|||Data Center||US||Your site's data center. See Finding Your Site's Data Center.|
|||Application Key||The Gigya Application Key you created in step 2 of the installation process.|
|||Path to Your Key File|
The full path of the file that contains the encryption key. For more information, see step 3 of the installation process.
|||Language Mode for Gigya UI||Auto||Select the language in which to present the Gigya UI in your site, or select Auto to have the language auto-selected based on your site/store language.|
|||Language Fallback||English||If you have set Language Mode for Gigya UI to Auto, select the language to be used if the page language is not supported by Gigya. For a list of the languages in which Gigya is available see Advanced Customizations and Localization.|
|||Debug Mode||No||Select Yes to turn on debug mode. When set to Yes, all API calls are logged. If set to No, only errors are logged.|
|||Retry Attempts||5||The number of retries to perform if an end-user's profile fails to save in the Magento back office. Retries are performed one minute apart, and stop when one of the attempts succeeds, or the specified number has been reached.|
Roles and Permissions: Best Practice
The Gigya extension creates a new permission in Magento: Edit Gigya General Settings. Only users with this permission can configure the Gigya settings page.
We recommend that after you install the extension as described above, you do the following:
Go to System > Permissions > User Roles > New Role and create a role called Gigya Major Admin.
Go to Role Resources and add the permission Edit Gigya General Settings to the new role.
You can configure Gigya's screen-sets for Magento in the Magento admin console, or by adding code.
Configuring Screens in the Magento Admin Console
- In the Magento admin console, go to Stores > Configuration > Gigya Identity Management > Screen-Sets.
- Under Login/Registration Screen-set:
- Under Desktop screen-set ID, specify the name of the Gigya screen-set to use for login and registration. If you want it to be different from the default, remove the checkmark from Use system value, then specify the name.
- If you are using a different screen-set for mobile screens, specify that under Mobile Screen-set ID.
- Repeat for the screens you wish to use in the Profile Update screen-set.
- Repeat for any custom screen-sets you are using, e.g., Default-LiteRegistration.
- Select the Sync Data option if you want any data entered by the user synced to Magento when the form successfully completes. Synchronization is done in accordance with the configured field mapping schema.
- Click Save Config.
Configure Display of Configured Screen-Sets
Navigate to Content -> Widgets -> Add Widget -> Continue -> Widget Options to configure the Display Widgets.
You can select either Embed or Popup as the Display Type.
Configure Screens Using Code
Gigya Registration and Login
The connector implements RaaS registration by providing a new customer_account_create.xml layout file that replaces Magento's default "Create an Account" page.
See the relevant code in the Extension:
<Gigya Extension root>/view/frontend/layout/customer_account_create.xml
First, the layout file references Magento's original customer_form_register block and removes it.
Then a new block is defined using:
The other RaaS functions are implemented in a similar way.
The connector implements RaaS Login by providing a new customer_account_login.xml layout file that replaces Magento's default "Sign In" page.
See the relevant code in the Extension:
<Gigya Extension root>/view/frontend/layout/customer_account_login.xml
First, the layout file references Magento's original customer.login.container container and removes it.
Then a new block is defined using:
Gigya Update Profile
The connector implements RaaS Edit Profile by providing a new customer_account_index.xml layout file that replaces Magento's default "Account Info" page.
See the relevant code in the Extension:
<Gigya Extension root>/view/frontend/layout/customer_account_index.xml
A new block is defined using:
How to Add RaaS Screen-Sets to Other Pages/Themes
To implement RaaS screen-sets in other pages or in your own custom theme files, invoke the RaaS blocks as defined in the Gigya Extension's XML files above.
For example, to implement the Gigya Login screen-set in a custom layout file, add the following code:
How to Customize the Screen-Set Options
By default, the GConnector calls Gigya's default screen-sets and passes minimal parameters:
See the relevant code in the Extension:
|File||In <Gigya Extension root>/view/frontend/templates/ - gigya_login.phtml or gigya_register.phtml|
To configure screen-set parameters:
- Copy the relevant template file (gigya_login.phtml, gigya_register.phtml, or gigya_info.phtml) to the respective templates folder in your own theme.
- Edit your copy of the template file to change/add values in the screenSetParams object as needed.
Change screenSet if you have created or renamed a screen-set when setting up RaaS in Gigya.
Set containerID to the ID of a <div> element on the page in which you want the login or registration form to appear.
For full information about possible parameters and permitted values, see thedocumentation.
In the file in which you invoke the screen-set block (see How to Add RaaS Screen-Sets to Other Pages/Themes), make sure to point to your theme's copy of the template file (template="<your theme path>::gigya_login.phtml").
For example, if you copied and modified the gigya_login.phtml file into a theme called "MyTheme", invoke the screen-set as follows:
Using Gigya Screens for Guest Checkout
If guest checkout is disabled in the Magento admin, when a user clicks Proceed to Checkout, Gigya's login/registration screen will pop up.
The GConnector references a default JSON file that maps the data of the following fields from Gigya to Magento:
- First name
- Last name
- Date of birth
Create a Custom Mapping
You can create your own JSON files that includes field mapping definitions that suit your needs. Referencing this file will override all default field mappings, except for Gigya's UID, the mapping of which is built in to the module. Therefore, we recommend that you use the existing JSON file as a baseline for your custom mapping, and customize as necessary. The field mapping file can be saved anywhere on the server, providing that the Unix user running the server (usually "www-data") has read access to it.
Each field mapping definition is a single JSON object, and includes the following parameters:
|cmsName||Name of Magento field (case sensitive). When mapping a Gigya user field to a Magento custom field, you need to indicate that this is a custom field, by adding the prefix "custom_" to the cmsName, e.g. "custom_vipCustomer".|
|cmsType||The field data type in Magento - int (short/long), string (varchar(X)), date, Boolean, text.|
|gigyaName||Name of Gigya field (case sensitive).|
|gigyaType||The field data type in Gigya.|
The direction of the field mapping. Supported values:
Example: The following file maps the profile.nickname field from Gigya to the prefix field in Magento and the data.middle_name field from Gigya to the middlename field in Magento:
Reference the JSON File
Once your file is saved, reference it in the field mapping module.
- In Magento, navigate to Stores > Configuration > Gigya Identity Management > Field Mapping.
- Specify the full path and file name of the field mapping JSON file.
- Click Save Config
Use Hook to Transform Data
In some cases, you may want to map fields between Gigya and Magento that have different types, or that have different logic. For example, gender in Magento is an integer, with 3 possible values: "1" for male, "2" for female, "3" for undefined. The corresponding Gigya gender field is a string, that accepts "m", "f" and "u". An example of a field having the same type but different logic is date of birth: at Gigya, this is comprised of 3 separate fields, one each for day, month and year. At Magento, this is one field.
The GConnector includes two hooks that can be used to transform the data in these cases.
Fired upon synchronization from Gigya to Magento.
- gigya_user - the Gigya user object.
- customer - an empty Magento user object.
Fired upon synchronization from Magento to Gigya.
- customer - the Magento user object.
- gigya_user - an empty Gigya user object.
The following is an example of how to add custom data transformation hooks.
Default CMS Sync Field Mapping
Default Gigya Sync Field Mapping
Session Synchronization between the Platforms
When the GConnector is configured, the Magento user session mirrors the Gigya user session:
- When a user logs into Gigya in your site, they are also logged into Magento.
- When a user logs out from Gigya, they are also logged out from Magento.
To configure the length of the users' session:
- Go to Stores > Configuration > Gigya Identity Management and select Session Management.
- In the Session Management configuration window, under Mode, choose between a fixed or extended mode.
- Fixed: The duration of the session equals to the defined session duration. Once that time has passed, the user is logged out.
- Extended: The session is restarted when the user performs actions that entail calls to the server.
- Specify the Session Duration.
- Save configurations.
Data sync between Gigya and Magento is based on Gigya's UID. This way, user information is independent of any input provided by the user (such as name or email), and passed consistently between systems, so as to provide a seamless integration and improve the users' experience. The UID field is created automatically in Magento when installing the GConnector. When configuring Gigya for CMS integrations, the email is always the login identifier (included in the loginID).
In Magento, the users' email serves as their identifier. Therefore, the email field in Magento is mapped to the emails stored in Gigya's loginID. This cannot be overridden by field mapping.
The login/registration flows in this case require that at least one email that is recognized in Gigya as a login identifier is unique to the user. After a user logs in or registers, the flow is as follows:
- Following Gigya's onLogin event, the UID is passed.
- The GConnector checks if the UID exists in the Magento database:
- Login: If the UID exists in the database, the system makes sure that at least one of the emails in the loginID is unique to this user, logs the user in and sets that email address in Magento. If all of the user's loginID emails are saved to other users (other UIDs), the user will not be logged in, and will receive an error.
- Register: If the UID does not exist, the system makes sure that at least one of the emails in the loginID is unique to this user, registers a new user and sets that email address in Magento. If all of the user's loginID emails are saved to other users (other UIDs), the user will not be logged in, and will receive an error.
You can check to see whether users have a UID, or write a Gigya UID for users if it's missing in Magento. This information is stored in the customer_entity_varchar table. The UID is saved as a value linked to an attribute (#135), with the code gigya_uid.
The GConnector for Magento 2 supports multi-site installations, and single sign-on (SSO). On Magento, you should configure each site separately. Defining the sites as a group is done on Gigya. For more information, see Site Groups and Single Sign-On.
When configuring an SSO segment, the session management of all sites in the segment should share the same definition:
- Fixed: when all sites in the segment are set to fixed session management, the start of the session is counted from the first site to which the user logged in.
- Dynamic: when all sites in the segment are set to dynamic session management, the session is restarted with every call to the server. The best practice is to set the session duration to the same length for all sites that share an SSO segment.
Disable The Gconnector for a Site in a group
You can disable the Gigya GConnector on specific sites of a group by entering the Gigya Identity Management > General Settings tab for the site and changing the Enabled field to No.
The Gigya Extension's logs can be found inside the Magento system logs.
In regular mode (when Magento's debug mode is off), the Extension only logs its error messages, in the following structure:
In debug mode (when Magento's debug mode is activated), the Extension logs every call to the Gigya API as follows:
Request: The API call
- Response: The native response message/object
Single Sign-On (SSO)
The Extension supports Single Sign-On (SSO), meaning that you can define two or more of your Magento stores as a site group with shared login sessions. For more information and instructions, see Site Groups and Single Sign-On in the Gigya documentation.
This module supports user deletion. To enable user deletion, you must first configure an AWS bucket.
You can remove users in one of two ways:
- Full delete
- Tag deleted user
Choosing Full delete is not recommended as it runs completely automatically and deleted users can never be recovered. This means that if you accidentally delete a user that has an active invoice, there will be no way to recover the users information.
It is recommended to choose the Tag deleted user option. This will add a flag to the user that you can then run a cron job on so you can ensure that there are no outstanding business related issues that require the user's data, then you can delete the user.
To enable user deletion, go to the User Deletion tab of the Gigya Identity Management module.
Set the Enabled field to Yes.
Set Deletion Type to Tag deleted user.
Set the Job Frequency you prefer.
Enter an Email on Success email address; this is required and must be a valid email address.
Optionally, add an Email on Failure email address.
Finally, add the details to your AWS bucket where the CSV file from Gigya IDX is stored.
You can also find a deletion log in magento/var/log.
- 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.
- You can test to see whether the module is installed correctly by logging into a site where the GConnector is installed using Gigya screens, then opening the browser's developer tools and typing gigyaCMS.authenticated. If you have logged in successfully, this should return "true".
|When loading the site, a "Service Temporarily Unavailable" message is displayed.|
Sometimes Magento fails to delete the .maintenance flag after performing maintenance tasks.
To delete it:
|Magento doesn't load correctly after changes have been made.||To clear all cache or generated files, clean the following folders, except for .htaccess files:|
When trying to log into the admin console the following message is displayed: "You did not sign in correctly or your account is temporarily disabled".
Run the following command from the Magento root folder:
- After installation be sure that you have run:
- php bin/magento setup:upgrade
- Then clear the cache using both:
- php bin/magento cache:clean
- php bin/magento cache:flush