Magento 2

Skip to end of metadata
Go to start of metadata

 

 

For information about the Magento 1.x GConnector, see Magento 1.0.

Overview

The GConnector for Magento 2 is an extension that allows you to easily integrate Gigya's Registration-as-a-Service 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

This extension supports PHP versions 7.0.x and 7.1.x

Installation

For installation instructions, see Magento 2 - Gigya Extension Installation Guide .

Configuration

Basic Configuration

 

Before you can use RaaS in Magento 2.1, you have to configure your Gigya account. See Setting Up RaaS in Your Gigya Account for instructions.

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:

RequiredFieldDefaultDescription
API Key 

The Gigya API Key for your site, as displayed in the homepage of the Gigya Console.

Click to enlarge screenshot

Data CenterUSYour 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 UIAutoSelect 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 FallbackEnglishIf 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 ModeNoSelect Yes to turn on debug mode. When set to Yes, all API calls are logged. If set to No, only errors are logged.
Retry Attempts5The 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.

 

RaaS Screen-Sets

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

  1. In the Magento admin console, go to Stores > Configuration > Gigya Identity Management > Screen-Sets
  2. Under Login/Registration Screen-set:
    1. 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. 
    2. If you are using a different screen-set for mobile screens, specify that under Mobile Screen-set ID
  3. Repeat for the screens you wish to use in the Profile Update screen-set. 
  4. Click Save Config.

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:

File

<Gigya Extension root>/view/frontend/layout/customer_account_create.xml

Code Snippet
<referenceContainer name="content">
    <!-- remove original registration form -->
    <referenceBlock name="customer_form_register" remove="true" /> 
 
    <block class="Gigya\GigyaIM\Block\Form\GigyaRegister" name="gigya_customer_form_register"
        template="Gigya_GigyaIM::gigya_register.phtml">
        <container name="form.additional.info" as="form_additional_info"/>
        <container name="customer.form.register.fields.before" as="form_fields_before" label="Form Fields Before"
            htmlTag="div" htmlClass="customer-form-before"/>
    </block>
</referenceContainer>
Description

First, the layout file references Magento's original customer_form_register block and removes it.

Then a new block is defined using:

  • The PHP code from <Gigya Extension root>/Block/Form/GigyaRegister.php
  • The script from <Gigya Extension root>/view/frontend/templates/gigya_register.phtml.

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:

File

<Gigya Extension root>/view/frontend/layout/customer_account_login.xml

Code Snippet
<referenceContainer name="content">
    <referenceContainer name="customer.login.container" remove="true" />
    <block class="Gigya\GigyaIM\Block\Form\GigyaLogin" name="gigya_customer_form_login"
        template="Gigya_GigyaIM::gigya_login.phtml">
    </block>
</referenceContainer>
Description

First, the layout file references Magento's original customer.login.container container and removes it.

Then a new block is defined using:

  • The PHP code from <Gigya Extension root>/Block/Form/GigyaLogin.php
  • The script from <Gigya Extension root>/view/frontend/templates/gigya_login.phtml.

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:

File

<Gigya Extension root>/view/frontend/layout/customer_account_index.xml

Code Snippet
 <update handle="customer_account"/>
<body>
    <referenceContainer name="content">
        <block class="Gigya\GigyaIM\Block\Account\Dashboard\GigyaInfo" name="gigya_customer_account_dashboard_info"
            as="gigya_info" template="Gigya_GigyaIM::account/dashboard/gigya_info.phtml" cacheable="false"/>
    </referenceContainer>
</body>
Description    

A new block is defined using:

 
  • The PHP code from <Gigya Extension root>/Block/Account/Dashboard/GigyaInfo.php
  • The script from <Gigya Extension root>/view/frontend/templates/account/dashboard/gigya_info.phtml.

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:

<block class="Gigya\GigyaIM\Block\Form\GigyaLogin" name="gigya_customer_form_login" template="Gigya_GigyaIM::gigya_login.phtml"> </block>

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:

FileIn <Gigya Extension root>/view/frontend/templates/ - gigya_login.phtml or gigya_register.phtml
Method screenSetParams
Code Snippet
 var screenSetParams = {
    screenSet: "Default-RegistrationLogin",
    containerID: "gigya-login",
    startScreen: "gigya-login-screen",
    mobileScreenSet: "" // optional - for using separate mobile screen-set.
};

To configure screen-set parameters:

  1. Copy the relevant template file (gigya_login.phtml, gigya_register.phtml, or gigya_info.phtml) to the respective templates folder in your own theme.
  2. Edit your copy of the template file to change/add values in the screenSetParams object as needed.
    For example:
    • 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.

       var screenSetParams = {
          screenSet: "custom-RegistrationLogin",
          containerID: "myDiv",
          startScreen: "gigya-login-screen",
      };

      For full information about possible parameters and permitted values, see the accounts.showScreenSet documentation.

  3. 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:

    <block class="Gigya\GigyaIM\Block\Form\GigyaLogin" name="gigya_customer_form_login" template="MyTheme::gigya_login.phtml"> </block>

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. 

 

Field Mapping

Default Mapping

The GConnector  references a default JSON file that maps the data of the following fields from Gigya to Magento:

  • UID
  • Email
  • First name
  • Last name
  • Gender
  • 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: 

Parameter NameDescription
cmsNameName 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".
cmsTypeThe field data type in Magento - int (short/long), string (varchar(X)), date, Boolean, text.
gigyaNameName of Gigya field (case sensitive).
gigyaTypeThe field data type in Gigya.
direction

The direction of the field mapping. Supported values:

  • g2cms - syncs values from Gigya into Magento's database. Any modification perfomed on Magento's side can be overwritten by the data in Gigya.
  • cms2g - syncs values from Magneto into Gigya's database. Any modification perfomed on Gigya's side can be overwritten by the data in Magento.
  • both - bi-directional sync

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: 

[  
  {
    "cmsName": "prefix",
    "cmsType": "text",
    "gigyaName": "profile.nickname",
    "gigyaType": "string",
    "direction": "both" 
  },
  {
    "cmsName": "middlename",
    "cmsType": "text",
    "gigyaName": "data.middle_name",
    "gigyaType": "string",
    "direction": "both" 
  }
]

Reference the JSON File 

Once your file is saved,  reference it in the field mapping module. 

  1. In Magento, navigate to Stores > Configuration > Gigya Identity Management > Field Mapping
  2. Specify the full path and file name of the field mapping JSON file.
  3. 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. 

Hook: gigya_pre_field_mapping

Fired upon synchronization from Gigya to Magento. 

Parameters:

  • gigya_user - the Gigya user object.
  • customer - an empty Magento user object.

 

Hook: pre_sync_to_gigya

Fired upon synchronization from Magento to Gigya. 

Parameters:

  • 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

<?php
/**
 * 
 */

namespace Gigya\GigyaIM\Observer;

use Gigya\CmsStarterKit\user\GigyaUser;
use Gigya\CmsStarterKit\user\GigyaProfile;
use Magento\Framework\Event\ObserverInterface;
use Magento\Customer\Model\Data\Customer;
use Magento\Framework\Event\Observer;

/**
 * DefaultCMSSyncFieldMapping
 *
 * Default g2cms field mapping implementation. For now only attributes gender and date of birth (dob)
 *
 * To be effective one have to declare this observer on event 'gigya_pre_field_mapping'.
 */
class DefaultCMSSyncFieldMapping implements ObserverInterface
{
    /**
     * Method execute
     *
     * @param Observer $observer
     */
    public function execute(Observer $observer)
    {
        /** @var GigyaUser $gigyaUser */
        $gigyaUser = $observer->getData('gigya_user');

        /** @var GigyaProfile $gigyaProfile */
        $gigyaProfile = $gigyaUser->getProfile();
        /** @var Customer $magentoCustomer */
        $magentoCustomer = $observer->getData('customer');

        // 'Translate' the gender code from Gigya to Magento value
        switch ($gigyaProfile->getGender()) {
            case 'm':
                $magentoCustomer->setGender('1');
                break;

            case 'f':
                $magentoCustomer->setGender('2');
                break;

            default:
                $magentoCustomer->setGender('3');
        }

        // 'Translate' the date of birth code from Gigya to Magento value
        $birthDay = $gigyaProfile->getBirthDay();
        $birthMonth = $gigyaProfile->getBirthMonth();
        $birthYear = $gigyaProfile->getBirthYear();

        if ($birthDay && $birthMonth && $birthYear) {
            $magentoCustomer->setDob(
                sprintf(
                    '%s-%s-%s',
                    $birthYear,
                    str_pad($birthMonth, 2, '0', STR_PAD_LEFT),
                    str_pad($birthDay, 2, '0', STR_PAD_LEFT)
                )
            );
        }

        // 'Translate' the subscribe boolean code from Gigya to Magento value
        $customerData = $gigyaUser->getData('subscribe');
        if (isset($customerData['subscribe'])) {
            if ($customerData['subscribe'] === 'false') {
                $gigyaUser->setData(array_merge($customerData, ['subscribe' => 0, 'data' => ['subscribe' => 0]]));
            }
            if ($customerData['subscribe'] === 'true') {
                $gigyaUser->setData(array_merge($customerData, ['subscribe' => 1, 'data' => ['subscribe' => 1]]));
            }
        }

        // Test kids
        $gigyaData = $gigyaUser->getData();
        if (array_key_exists('kids', $gigyaData)) {
            $kidValue = $gigyaData['kids'];
            if ($kidValue === 'Kid1') {
                $magentoCustomer->setData('gigya_first_kid', 'Hello!');
            }
        }

        // Test subscription
        $subscription = $gigyaUser->getSubscriptionById('june11th_01');
        if ($subscription) {
            $food = array('hpouhf');
            $magentoCustomer->setData('gigya_pets_nickname', json_encode($food));
        }
    }
}

 

Default Gigya Sync Field Mapping

<?php
/**
 * 
 */

namespace Gigya\GigyaIM\Observer;

use Gigya\CmsStarterKit\user\GigyaSubscription;
use Gigya\CmsStarterKit\user\GigyaSubscriptionContainer;
use Gigya\CmsStarterKit\user\GigyaUser;
use Gigya\CmsStarterKit\user\GigyaProfile;
use Magento\Customer\Model\Data\Customer;
use Magento\Framework\Event\ObserverInterface;
use Magento\Framework\Event\Observer;

/**
 * DefaultCMSSyncFieldMapping
 *
 * Default cms2g field mapping implementation. For now only attributes gender and date of birth (BirthDay BirthMonth BirthYear)
 *
 * To be effective one have to declare this observer on event 'pre_sync_to_gigya'.
 *
 */
class DefaultGigyaSyncFieldMapping implements ObserverInterface
{
    /**
     * Method execute
     *
     * @param Observer $observer
     */
    public function execute(Observer $observer)
    {
        /** @var GigyaUser $gigyaUser */
        $gigyaUser = $observer->getData('gigya_user');

        /** @var Customer $magentoCustomer */
        $magentoCustomer = $observer->getData('customer');
        /** @var GigyaProfile $gigyaProfile */
        $gigyaProfile = $gigyaUser->getProfile();

        // 'Translate' the gender code from Magento to Gigya value
        switch($magentoCustomer->getGender()) {
            case 1:
                $gigyaProfile->setGender('m');
                break;

            case 2:
                $gigyaProfile->setGender('f');
                break;

            default:
                $gigyaProfile->setGender('u');
        }

        // 'Translate' the date of birth code from Gigya to Magento value
        $dob = $magentoCustomer->getDob();

        if ($dob !== null && trim($dob) !== '') {
            $date = new \Zend_Date($dob, 'YYYY-MM-dd');
            $birthYear = (int)$date->get(\Zend_Date::YEAR);
            $birthMonth = (int)$date->get(\Zend_Date::MONTH);
            $birthDay = (int)$date->get(\Zend_Date::DAY);

            $gigyaProfile->setBirthDay($birthDay);
            $gigyaProfile->setBirthMonth($birthMonth);
            $gigyaProfile->setBirthYear($birthYear);
        }

        // Test kids
        $kidValue = $magentoCustomer->getCustomAttribute('gigya_first_kid')->getValue();
        if ($kidValue === 'Kid1') {
            $gigyaUser->setData(array('kids' => 'Kid2'));
        }

        // Test subscription
        $subscription = new GigyaSubscription(null);
        $subscription->setTags('["dsofuhdspu","dsfhdf","gqsfdqsf","qdfdsfdqsf"]');
        $gigyaUser->addSubscription('june11th_01', $subscription);
    }
}

 

  

Session Management

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.

Session Expiration

To configure the length of the users' session: 

  1. Go to Stores > Configuration > Gigya Identity Management and select Session Management
  2. 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. 
  3. Specify the Session Duration
  4. Save configurations.

Gigya recommends using dynamic sessions whenever inside an SSO group. For additional information, see Managing Session Expiration.

To enable single-logout for a site group, see GConnector Single Logout In SSO Groups.

UID-Based Sync

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:

  1.  Following Gigya's onLogin event, the UID is passed. 
  2. 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. 

 

 

Multi-Site Support

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.

 

Logs

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:

    Date: <DATE>,kibana call id:<CALL ID>, API call: <API CALL>,Error: <GIGYA'S NATIVE ERROR MESSAGE>
  • 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.

 

User Deletion

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.

 

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.

 

 

Magento-Related Troubleshooting

  • 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". 
IssuePossible Solution
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:

  1. Navigate to the var folder under site root

  2. Check if the .maintenance.flag file exists (e.g. by typing ls -a)

  3. If it exists, delete it and reload the site.

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:
  • pub/static

  • var/cache

  • var/generation

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:

php bin/magento admin:user:unlock <username>
  • 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

 

 

Internal Note:

 

FAQ

 Does the GConnector support Magento REST endpoints?

 Yes and no, since Magento REST endpoints can be used for numerous different actions, including catalog management, orders management, front and back connection, customer creation, updating, and more.

We do not list all the specific APIs used by Gigya and work on a deeper level, e.g., in the 'model'. So, if the Magento API uses the 'customer model', the GConnector can retrieve and send data to Gigya.

Additionally, it is important to note that when a customer first logs in, the GConnector actually creates an account in Gigya which is then sent to Magento afterwards. The connector can only send customer data to Magento if the user already exists in the Gigya database, so it is not possible to use the Magento customer creation API in conjunction with the GConnector.

 

  

Save

Save

Save

Save

Save

  • No labels