Gigya Extension for Magento 2.0

Skip to end of metadata
Go to start of metadata

 

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

 

Overview

The GConnector for Magento 2.X 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.

Gigya is a Magento Silver Industry Partner

Version and Compatibility

This version of the extension (version 1.0 for Magento 2.0) is compatible with Magento Community Edition version 2.0 and Magento Enterprise Edition version 2.0.

Installation

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

Configuration

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 it is displayed in the Gigya admin console in the Dashboard screen (see screenshot).

Click to enlarge screenshot

DomainUSThe Gigya Domain or Data Center with which your site is associated. See Finding Your Site's Data Center for instructions.
Application Key The Gigya Application Key you created in Step 2.
Encryption Key Save Mode Select whether you saved the Encryption Key as a file or as an environment variable in Step 3.
Path to Your Key File 

If you have set Encryption Key Save Mode to File, provide the full path of the text file that contains the encryption key.

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.

Click to enlarge screenshot

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.

Implementation Guide

Limitations

The GConnector does not synchronize customer account changes from Magento to Gigya. In other words, if a customer account is created, deleted, or has its details updated through the Magento admin, this change will not be updated in the Gigya database.

Therefore, best practice when using the GConnector is to perform any changes to the customer account only through the Gigya RaaS screen-sets.

RaaS Screen-Sets

 

Before you can use RaaS in Magento 2.0, 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.

RaaS Registration Implementation

The extension 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.

RaaS Login Implementation

The extension 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.

RaaS Edit Profile Implementation

The extension 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>

Language Settings

By default, the Gigya screen-sets are presented in English. 

To change the language settings, in the Magento admin console, go to Stores > Configuration > Gigya Identity Management > General Settings.

For more details, see Step 3: Configure Basic Settings in the Installation Guide.

Field Synchronization

By default, the GConnector synchronizes the following user data fields from Gigya to Magento:

  • Email
  • First name
  • Last name

  See the relevant code in the Extension:

File <Gigya Extension root>/Controller/Raas/GigyaPost.php
MethodgigyaSetCustomerFields
Code Snippet
protected function gigyaSetCustomerFields(&$customer, $gigya_user_account) {
	$customer->setEmail($gigya_user_account->getGigyaLoginId());
	$customer->setFirstname($gigya_user_account->getProfile()->getFirstName());
	$customer->setLastname($gigya_user_account->getProfile()->getLastName());
	$customer->setCustomAttribute("gigya_uid", $gigya_user_account->getUID());
}
Description
  • This code uses Magento's $customer->set{attribute} methods for setting customer attributes. To see all the available methods in your version of Magento, go to Vendor/Magento/Customer/Model/Data/Customer.php.

Field Mapping

Mapping additional fields from Gigya accounts to the Magento database requires installing the Field Mapping module, then mapping the fields, and using a hook to convert data from Gigya's format to Magento's. 

1. Get the Extenstion

To get the extension:

  1. Log in via SSH and navigate to the Magento installation root.
  2. Run the following command: 

    composer require gigya/magento2-field-mapping
    If you experience problems with this step, make sure your root composer.json file supports non-stable versions. For example, you may need to remove the line prefer-stable:true and set minimum-stablility to beta.
  3. Perform a Magento upgrade using the following command:

     php bin/magento setup:upgrade

    Don't forget to clear the Magento cache after this process as well as after carrying out any other change.

Field Mapping section should now appear under the Gigya Identity Management  menu in Magento. 

2. Create Field Mapping File

Fields are mapped in a JSON file. Define the Magento field to be mapped to the Gigya field in your field mapping file as an array of JSON objects. Each object contains one mapping definition, i.e., one Gigya field to one Magento field. Save the file to an accessible location in the server.

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": "g2cms" // This definition is optional
  },
  {
    "cmsName": "middlename",
    "cmsType": "text",
    "gigyaName": "data.middle_name",
    "gigyaType": "string",
    "direction": "g2cms" //This definition is optional
  }
]

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

RequiredKeyDescription
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.
gigyaNameName of Gigya field (case sensitive).
gigyaTypeThe field data type in Gigya.
directionThe direction of the field mapping. Currently, only mapping from Gigya to Magento (g2cms) is supported.

3. Reference the JSON File 

  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

4. Use Hook to Transform Data

You can use a hook to transform data received from Gigya into a format that's compatible or convenient for use in Magento. A common use case is to transform 3 Gigya date fields birthDay, birthMonth and birthYear into one Magento date field with a DD/MM/YYYY format.  

  • Hook:  gigya_field_mapping_custom
  • Parameter: gigya_user

  

User Session Management

Session Synchronization between the Platforms

When the Gigya Extension is active, 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

The Extension sets the session expiration based on the "Online Minutes Interval" setting in the Magento admin (default: 15 minutes).

This value will determine the Gigya session length.

Note that there are differences between Gigya and Magento in session management:

  • In native Magento (without the Gigya Extension), "Online Minutes Interval" counts time the user is idle.
    For example, 15 minutes means that the user is logged out after 15 minutes without keyboard activity.
  • In Gigya, the session expiration setting determines session length from the moment of login.
    For example, 15 minutes means that the user is logged out after 15 minutes from the moment of login, whether the user has been active in the site or not.

In Magento with the Gigya Extension, the session is controlled by Gigya, so session length is counted from the time of login.

Make sure to set the session length appropriately (see How to Customize Session Expiration below).

How to Modify the Session Expiration Value

To set the session expiration value, change the expiration setting in Magento, and the Extension will synchronize that value automatically to Gigya:

  1. In the Magento admin, go to Stores > Settings > Online Now > Customer Configuration > Online Customers Options.

  2. In the Online Minutes Interval field, enter a value in minutes (default is 15 minutes).

  3. Select Save Config.

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.

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.

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>

 

Save

Save

Save

Save

Save

  • No labels