Integrating with Gigya
Integration with Gigya is a multi-step process at the end of which you can invoke Gigya’s screen-sets or your own custom screens, to identify and authenticate users, allow them to log in with their site identity or social identity and store and validate their consent to your site terms and conditions. User and consent data is stored in Gigya’s database.
- This guide is a general walk-through to the initial steps you need to take to set up Gigya and help you get started. Implementation may greatly vary, depending on the nature of your site and business use cases.
- The guide does not walk you through data migration, QA and other relevant processes that should be completed before deployment.
What is the Gigya Console?
The Gigya Console is your access point to Gigya. It is the portal through which you:
- Manage the configuration of the site or sites that are integrated with Gigya.
- Access a suite of tools that display, query and analyze your user database
- Perform data transfers and imports
Your user in the Gigya Console (Console user) is associated with a PartnerID: a number that identifies your company’s Gigya assets. A single user can be a member of one or many such Partner environments. Your Partner and site IDs are displayed on the top bar. Click the selector icon to move between the different sites associated with your partner:
Before you begin, you should make sure users and applications are set up correctly with the relevant permissions. Read the full Console Administration guide, and about creating application and user keys.
The terms ‘site’ and 'API key' are used interchangeably. Any of your sites that integrate with Gigya should be defined in the Console (i.e., you should generate a unique API key for that site). Later, you can add a site description in the “Site Settings” page.
A site is created in one of our 5 available data centers: United States, European Union, Australia, Russia or China. When users are saved for that site, that data is physically stored in the relevant data center, thereby complying with various data residency regulations. For more information, see Identity Compliance. Note that it is possible to create a global site, where user data may be stored in different data centers according to their residency. For more information, see Global Access.
Parent & Child Sites
Site Groups are used when you own multiple sites and wish to provide your users with a different experience in each site, but to have a unified database of all users and a centralized place for configurations.
- A site group consists of one Parent site and one or more Child sites. Note that the Parent is not a live nor even a real site, but an API key that stores the global settings and the database for the site group.
- Any unique site (API key) can only be a member of one site group.
- All the sites within a given group share the same data center and database. The database is “hosted” on the Parent site.
- Child sites inherit most of their settings from the Parent, including permissions, policies, and more. Some settings can be overridden, as explained below.
Read more about site groups here.
Settings are configured at an API key level. Child sites inherit the Parent site settings by default. Some settings can be overridden on the Child level.
The following site settings are the ones usually configured:
The URLs of your domain need to be added to the ‘Trusted Site URLs’ section of the ‘Site Settings’ page. Wildcards can be used to enable subdomains and paths from the Top-Level-Domain.
CNAME and SSL
When Gigya allows a user to login or register via a social provider, a redirect occurs to allow for the display of the social provider’s login or registration page.
The URL used for that callback is:
- ‘socialize.<dataCentre>.gigya.com/GS/GSLogin.aspx’ for the US, EU and AU data centers
- ‘socialize.gigya-api.cn/GS/GSLogin.aspx’ for the Chinese data center
- ‘socialize.ru1.gigya.com/GS/GSLogin.aspx’ for the Russian data center
However, it is highly recommended that you implement your own CNAME in order to maintain consistent branding of the URLs within your site.
There are a number of reasons:
- Using a CNAME (and certificate) instead of socialize.gigya.com allows you to preserve the site branding and user experience that you've invested so much time and effort in.
- Because without one, every time your user is redirected from login.yoursite.com to Gigya's servers, their browser will warn them with a security message. Using an SSL certificate verifies that the redirect to Gigya's servers is a trusted process, thus eliminating this security popup for your site visitors experience.
- Using an SSL certificate also ensures that data transmitted to and from the browser is encrypted, reinforcing trust between you and your visitors and helping to prevent Man-in-the-middle attacks.
You will need to set up the CNAME and SSL certificate for all URLs added into the Trusted Site URLs table. For more information, see Obtaining and Setting Up Your SSL Certificate.
Configuring External Social Applications
Gigya uses external applications to deliver its services in social networks. The external applications act as mediators, enabling the Gigya service to provide the various functions it offers such as retrieving user information or sending notifications. Almost all social providers require the setup of a dedicated external application in order to enable social login on your site. For more information, see Setting Up External Applications.
Provider Configuration in Gigya
Once you have configured the external applications for the social providers with which users will register and login, you will need to complete the following steps:
- Visit the Providers Configurations page on Gigya’s Console
- Add the Application ID and Secret Key from the external application into the fields for the relevant social provider
- Enable the CNAME you have configured
- Ensure the widget for the social providers you have configured has been added into your implementation
Each social provider has a basic set of data that can be retrieved. This is enabled within the Gigya Console.
At the point of registration, a dialogue box will pop up asking if the user consents to allowing these fields to be retrieved; for example, the below is what a user receives when attempting to register using Facebook:
While you can request to retrieve these fields, a user can edit the data set that they consent for you to retrieve. In addition these basic permissions, some providers require extended permissions for the retrieval of additional data. For a full explanation, see Permissions.
Site policies apply to several aspects of registration, login and email subscription. They are configured on the Policies page of Gigya’s Console (see documentation), and/or by setting the policies object by calling accounts.setPolicies. They can be viewed using accounts.getPolicies.
Setting Child Policies
While child sites inherit the policies of their parents by default, certain policies can be overridden at a child level to allow you to set specific policies per individual API key.
To achieve this, simply select the ‘Override Master Settings Option’ at a child level:
The following policies can be overridden at a child level:
- Default Login & Registration Screen-Set
- Email Verification
Read here about the potential effect of overriding parent policies.
Screen-sets are premade user-facing screens, that together form a cohesive Gigya flow (such as a registration process). Read through the Screen-Set documentation before you begin customization.
Screen-Sets are a fast and easy way to enable Registration-as-a-Service and Consent Management using Gigya’s Drag & Drop UI Builder to produce front-end forms that are pre-integrated with Gigya’s CIAM platform. Read the UI Builder documentation for an extensive explanation on how to customize the screens.
- Display a UI element (such as a checkbox) only for a specific IP range
- Validate the user's ZIP code according to your own custom logic
- Inject AJAX when a certain condition is met
- Respond in real time to the user's input
You can use Markup Extensions to further customize the look-and-feel of your screens. Gigya’s Markup Extensions provide flexibility beyond the Screen-Sets UI Builder tool, allowing you to design custom HTML forms and enable Gigya to power the rest. The Screen-Sets UI Builder is essentially a markup generator, so the simplest way to get started is by using the Screen-Sets UI Builder, exporting the generated code, pasting it to your web page and tweaking the markup code to meet your specific design and flow needs.
You can store users in the Gigya database, without using Gigya’s screens at all, but your own custom screens. To do so, your developers should familiarize themselves with the Accounts API namespace, and read through the relevant API documentation.
The Gigya data schema, Identity Store, holds the user data that was captured during interactions with Gigya’s screens and flows. The schema includes the following namespaces:
- profile - Gigya out-of-the box fields, that contain all the basic and some extended account information. See the Profile Object documentation for more information.
- data - any custom fields you create, for storing any custom data. If no custom data fields were created, this namespace is empty of fields.
- subscriptions - custom fields, specifically designed to hold subscription information to various communication channels. If no subscription fields were created, or if your licence does not include communication preferences, this namespace is empty of fields.
- preferences - if your implementation includes Consent Management, you will have access to the ‘preferences’ object. A preferences object contains the data pertaining to one consent statement.
Schema fields can be created by using the Schema Editor, by calling accounts.setSchema, or when using the UI Builder.
It’s important to understand the data that you want to capture within the Identity Store before deciding on the fields which will make up your schema; this will be determined by a number of factors, including:
- Familiarizing yourself with the types of data that can be stored
- Reviewing the data that you currently capture via user registration
- Reviewing the data that you currently hold against your users in existing downstream systems
- Coming to a decision on what data will be required in Gigya to enable registration
- Coming to a decision on what data will be required in Gigya to facilitate functionality in downstream systems
- Coming to a decision on what data will be required in Gigya to synchronise with downstream systems
There are a number of emails that are sent to users from Gigya, triggered by user events, and dependent on your site policy. Before your site launches, make sure to review all the automatic emails that could be sent by Gigya, review the default emails, and customize them to your needs. You can customize the text and HTML of the emails themselves. A full explanation of email templates can be found here.
Depending on your site implementation, you may require additional setup of the following tools:
- Webhooks push notifications of account events to your server in near real-time and are most useful for notifying downstream systems of events that need to be acted on almost immediately.
- If you choose to implement Risk-Based Authentication as part of your site policies, you should use this guide for implementation
- Federated Login: You can offer users other authentication options, based on OpenID Connect and SAML protocols.
- Extensions: You may want to customize the validations and checks performed at the crucial points of registration, login and account update. Extensions grants you great flexibility to do that by injecting custom business login into existing flows.
- Data Store: An additional database for flexibly storing additional records that relate to your user records.
- GConnectors: Pre-built integrations between Gigya and prominent CMS and e-commerce solutions, for ensuring smooth flows in your online marketplace.
- IdentitySync: Gigya’s ETL tool (Extract, Transform, Load) for performing data extracts, exports and imports to third party platforms.
Ongoing Administration and Usage Tools
Gigya offers a host of tools to access, query and analyze your data pertaining to users, registrations, logins and consent. Following is a brief overview of some of these tools.
Identity access is an intuitive admin dashboard for viewing and managing your users. Admins can view a user profile and perform several actions, such as verifying an email address, resetting TFA devices and disabling a user’s access. They can also review extensive profile information such as demographics, user consent to various consent statements, communication preferences and more.
Audit Log and Consent Vault
Gigya offers two audit logs that store records of various admin and user actions. All actions performed within the Console, and several end-user actions, are saved to the Audit Log. Actions around users’ consent to the various consent statements, such as granting or revoking consent, are saved to the Consent Vault. Note that both of these are also reflected for each individual user, in Identity Access.
Reports allow your organization to monitor user activity and sort data about your users, providing a clear picture of site interactions and traffic data, assisting strategic decision-making about your website and business.
One type of reporting tool is Customer Insights. Customer Insights and Customer Insights Plus are visual user statistics tools that make use of social data gathered by your site and stored at Gigya. The reports include demographics, interests, social behavior, influence and revenue-generating activity. CI has a user-friendly, intuitive interface, designed to allow quick and easy cross segmentation of users by each of the available analytical categories without sacrificing flexibility.
Following is a list of sub-pages relevant to administration and setup: