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 settings configuration.
A site group consists of exactly one Parent site and one or more Child sites. Any unique site can only be a member of one site-group. All the sites within a given group share the same datacenter. Child sites inherit most of their settings from the Parent, including permissions, policies, and more. The Parent site is also host for the database used by all of its group members. In a site group, each site must use its own dedicated API key.
Within a site group, users are shared across all sites in the group along with their user data. Once a user registers to a member site of a site group, their account is valid and the user is considered a registered user on all sites that are members of that group.
Single Sign-On (SSO) is a feature which allows a user to be seamlessly signed in to one site after signing in to another. Within a site group, you can define a sub-group of sites, known as SSO Segments, which share an SSO experience. SSO manages a single session for a user for all the sites in the segment, so that when a user is logged in to one site, they are logged in and gain immediate access to all other sites in that segment, saving them the trouble of authenticating separately to each site in the segment. Each site can belong only to one segment.
An overview of the flow is shown in the following diagram:
The following guide explains the various aspects of implementing site groups and SSO in a multi-site scenario. The guide consists of the following:
Watch an Instructional Video
If you have a Gigya Academy membership, you can watch instructional videos about this and other Gigya products. To access Gigya Academy content, you should first make sure you are logged into the Gigya Console.
Site Groups - Best Practices
Within a site group, users are shared across all sites in the group along with their user data. This means that all data accumulated, such as achievements accrued through Loyalty - Gamification and User Behavior, are available for use on all member sites, enabling site owners to create a cross-site experience for users, rewarding their engagement on all the different platforms.
The following section describes the best practices for creating a site group.
Selecting a Parent
When Creating New Sites
As a best practice implementation, it is recommended not to use an existing working site as a Parent.
You should create a new, dummy *, site, within the data center that will be used by this site group, that will act as the Parent site in your group. This site will aggregate all the user data and concentrate the group's settings and policies.
* A dummy site is a domain that you own, but is not a live site accessed by your users. After adding the site to your Gigya account, the dummy will have a Gigya API key and database.
Remember that in a site group, each site must use its own dedicated API key.
When Grouping Active Sites
If you are creating a site group out of currently active sites, or adding active websites that already contain user data to a site group, the data on the added site will be lost** unless imported.
Recommended Best Practice is to export all user data prior to adding the site to a Site Group.
You will need to perform an import of the data to the Parent site's database in order to avoid losing the data previously aggregated.
You should consider, however, that not all data can be transported between sites, and some data loss may occur. User data will be preserved in the case of a valid login token. If a user was not logged in for a while, his login token will be expired and the data would only be available upon the user's following login.
Read the Data Migration Section for more information.
** The data will not really be lost, but will be inaccessible to the group members, including the site that originally controlled it.
To configure Site Groups:
- Open the Site Groups tab, in the Admin tab of Gigya's Console.
- Click Create Site Group.
- In the Create Site Group window:
- Select the Parent site from the dropdown.
- Enter a relevant description for this site group.
- If sites in the groups share an SSO experience, check the SSO enabled box. See below for more information on configuring SSO Segments.
- Click the Add Sites button to select the sites which will be added. Only partner sites that share this data center, and that are not assigned to a different site group, will be displayed.
- Click Create.
Parent sites and data centers cannot be changed later down the line.
Social Network Apps
Every site that performs social actions, e.g., login with Facebook, needs to have a social network app (SNAPP) associated with it.
Your SNAPP acts as a link between your site and a specific social network, e.g., Twitter, so when a user registers to your website using his social identity, he grants your website permissions to retrieve information and perform actions (in accordance to the set of permissions requested) on his behalf through your app.
There are two approaches to maintaining social network apps in a site group. Each approach has its pros and cons, it's up to you to decide which suits you better.
Defining a unique app for each child site - This approach maximizes flexibility when regarding social permissions. Each site can define its own set of permissions, retrieving different data and performing different actions.
Since each app has its own unique set of permissions, user authorization will be required for each site individually when accessing a site for the first time.
Also note that with this approach, adding a connection will only affect the user's connections on the site they are currently logged into, and will not be reflected on other member sites, whereas with a single app on an SSO group, adding a connection will also change the user's state on all member sites.
* When using multiple apps with Facebook for a site group, it is required to keep all apps using the same Facebook API version . You are also required to configure a business entity for your sites, to aggregate and transfer data across all sites in the group easily.
Defining a single app for the group - This approach maximizes control over app settings and reduces app maintenance, since only one app is maintained.
With a single app, all sites share the same permissions, and are able to retrieve the same data and perform the same actions (though they are not required to).
Since only one app is used, new users will only have to be authorized once, on the first site that they log in to. This contributes to transparent registration, as a user who has been authorized once will be authenticated automatically in all sites in the group.
Important: Make sure to have all your sites require the same permission set when more than one site within the group use an app on any particular social network.
It is important to note that some social networks advise against using a single app on more than one site categorically. For this reason, when defining SNAPPs it is recommended to make sure that the social network does not advise against using one app for more than a single site.
Among the leading social networks (Facebook, Google+, Twitter and Linkedin), Facebook is the only one that advises against sharing an app on multiple sites.
When Setting up the permissions within your Site Group, it is important to ensure that all the sites within the group use the same permissions set and that these permissions are defined and configured correctly within the Parent and Child Permissions pages of the Gigya Console. If you are using either the same app or multiple apps that request different permissions from the same SN you may incur failures, as the different providers treat the requested permissions differently. I.e., when using LinkedIn, the permissions checked at the Parent level are going to be requested regardless of whether the Child site's app requires them or not.
When creating a site group out of active sites (i.e., sites that already have registered users and a social database), a data import can be performed, migrating the data from any given site into a the master database.
Data import is performed in cooperation with your Implementation Consultant. Contact your IM to start the process.
Migration of data from several external sites into Gigya has its implications, as well as some preliminary requirements.
Site data is exported in a JSON file, and inserted into the destination site's database. To import data from one DB to another, the data structure of the JSON file should match the data schema of the destination site. Make sure that field values match their values in the destination schema, (e.g., a field that holds textual 'boolean' values such as 'true' or 'false', cannot be imported into a Boolean field, even though they are logically the same).
Not all data is supported when using this method to transfer data.
For more information on how data migration is performed, and which data fields are supported contact your IM. You can also read our import guides.
The Implications of Site Groups
A site group uses a single database for all the data aggregated from multiple child sites. This database is associated with the parent site, although all child sites can access it and contribute to it.
When a site is removed from a group, it is also denied access to the group's database and becomes a standalone regular site.
If this site was previously active before joining the current site group, it will revert to using its original database.
The site will only have access to the data collected in its original database, prior to joining the group. All data aggregated while it was a part of the group will be unavailable to that site.
If the site was not active before, it will have no data.
Recommended Best Practice is to configure your site group members in advance when possible, and avoid removing or adding sites to an active site group.
- Defining which data fields will be part of the Account data storage.
- The type of each field.
- Which fields are required and which are optional.
Sites that use RaaS and are part of a the same site group must all contain an identical data schema, as all sites of a site group use the same data base (of the parent).
Child sites, however, can maintain their own unique 'required' fields apart from those of the Parent, it is important to ensure that any fields required at child level be available in the Registration Completion screen of the group's active screen-set.
When using different schema field requirements, users of one site may be missing required data as per another site's data schema and will be unable to use sites that do not support the required data. Users that are missing required fields will be pending registration on any site that requires those fields until adding the required data. They will be prompted for the missing required fields upon their following login via the Registration Completion screen, in order to complete their registration.
Make sure to include any required fields in your 'Registration completion' screen, as well as in the 'Registration' screen.
If a field is required at the Parent level and the field is not set at the child, the user will be unable to complete their registration.
Data displayed on all sites will be identical and will provide an overview of the group's user base, demographics, and preferences.
Read more in the Identity Access guide .
Most site policies are set on the Parent site and affect the entire group.
The Policies page on child sites will show the current site policy settings but will not enable the user to edit them, with the exception of a selected few.
- Go to the Policies page for the relevant child site.
- Check the Override master settings checkbox for the relevant configurations (e.g., Additional Security Measures).
- Click Save Settings.
These are the settings that can be overridden by a child site:
- Default login and registration screen-sets
- Email verification
- CAPTCHA requirement for new registrations
- The sending of the following automated emails:
- New user welcome
- Password reset confirmation
- Account deletion confirmation
Some policies can only be activated or disabled on the master site, but can be fine-tuned on each member site.
For information on overriding policies in a child site when using the REST API, see Overriding Master Configurations.
Permissions can be unique per site or shared among all sites, depending on the number of SNAPPs defined in the group, however, it is important to make sure that when using a single app for multiple websites, Permissions for all sites must be identical and defined at both the Parent and Child level.
For more information read the Social Network Apps section.
By default, all of a group's child sites share the parent's screen-sets.
Use Custom Screen-Sets For A Child
To use unique screen-sets for a child member of an SSO group, go to the child's Gigya Dashboard and enter the Screen-Sets tab.
If the child does not yet have any screen-sets, the page will look similar to the following, where the Current site's screen-sets section is empty:
You can now either Duplicate an existing screen-set from the parent to customize, or to begin to use a unique screen-set, you can add a new collection to the site using the Add New Collection button.
When duplicating screen-sets, it is recommended to change the name - if both child and parent have screen-sets of the same name, the child screen-set always overrides the parent's.
Once you add the new collection, you can edit it just like any other screen-set using the built-in UI Builder.
Before deploying your screen-sets, you have to enable the Override master settings option in the site's Policies and select the appropriate RegistrationLogin screen-set from the available drop-down menus.
If both a child and parent have a screen-set with the same name, when calling accounts.showScreenSet from the child's API key, the child's screen-set will always be the one displayed.
Use A Specific Parent Screen-Set For A Child
A member site can choose its own default screen-set out of the available parent screen-sets or from any screen-sets created on the child itself from the Policies tab by checking the Override master settings checkbox.
By default, group sites share the same Email Templates.
However, by checking the Override master settings checkbox on the email templates page in the console, any given child site can add or change its set of email templates to be unique.
When operating Loyalty (GM) in a site group, user engagement is rewarded through your entire platform and across all sites.
This means that although Challenges are unique for each site in the group, users' earnings (i.e., points and actions completed) are aggregated per user and shared across all sites in the group.
This way, a user is being awarded for his contribution on the entire platform, and not only on a single site, while at the same time allowing each site to maintain an individual character and provide different challenges and different rewards for different actions.
If an action is defined at the Child level and that action is used in a challenge that is defined at the Parent level, the points will roll up to the Parent.
Challenges that are created at the Parent level are available to all Children.
Actions that are created at the Child level are available at the Parent level as virtual actions, i.e., the Parent can not edit the action but can use it in other challenges.
A Child can not see another Child's actions.
- If a challenge created at the Parent utilizes virtual actions from Child A, Child B will have access to the challenge but not that action (from Child A).
An action that exists on a Child will always override a Parent action of the same name.
Child Actions override Parent Actions with the same name Even If The Child Action Is Disabled!
This is especially important regarding the Gigya _default Challenge which exists on all sites. If your SSO Group utilizes Gigya Default Actions, these Actions MUST be configured at the individual Child Level. See Loyalty Configuration and Administration - Exporting GM Settings for how to streamline the configuration process.
Recommended Best Practice is to always create uniquely named Challenges and Actions at the Parent level for use throughout the SSO group, if all children will use these same settings.
The Group Custom User Actions table on the Actions page of the Gigya Console will not appear on Child sites.
Points accumulated for a challenge created at the Parent level will be available to all Children, even if the points were generated by another Child.
- Actions to be shared among multiple Children should be created at the Parent level and all Children will be able to call gm.notifyAction on those actions.
The Reports tab in the Console displays data for the selected site only. Even though data is shared between sites, the reports differentiate between sites and display only relevant data.
Global Configuration in Site Group Scenarios
For example, parent site A has only Facebook listed under enabled social providers:
This is the configuration for child site B:
In this case, a user of child site B that wishes to log in with a social network, will be offered only Twitter as an option. To append Twitter to the existing setting (Facebook) rather than override it, the child site configuration would be:
Now the user of child site B will be offered both Facebook and Twitter as social login options.
Single Sign-On (SSO)
SSO is only supported via client-side SDKs.
Single Sign-On is a means of authenticating users and managing their login sessions between applications and websites. After an SSO connection is established between apps, users need only authenticate to one of the websites or apps to be automatically authenticated and logged in to the other. Gigya offers an out-of-the-box option for connecting child sites of a site group to SSO Segments.
When a user logs into one of the member sites of a segment, a Gigya session starts for that user. When the user later loads a page of a different member site (that belongs to the same segment), Gigya automatically recognizes that the second site belongs to the same SSO segment, and fires an onLogin event, which is sent to the second site. The user is automatically logged into the second site, and the onLogin event should be handled to perform the actions necessary for a logged-in user.
Note: The onLogin event will not include a context object if the login was triggered by another site.
When a user logs out from one of the member sites, Gigya logs the user out of all other sites in the relevant segment, and fires an onLogout event, that terminates that user's active Gigya sessions in sites that belong to the segment.
To configure SSO successfully, create a logout URL for every member site in the group. This is a page that contains the Gigya script and issues a call to accounts.logout / socialize.logout accordingly, effectively logging out the active user when the page is loaded. A logout URL must be public facing and not behind a firewall (even in a development environment) so that Gigya APIs can access it.
Once all is set up, Gigya will recognize when a call to accounts.logout or socialize.logout comes from a site that belongs to an SSO segment, and will call the logout URL of each visited member site of the segment, thus logging the user out of all SSO group sites.
Keep in mind that this process only terminates Gigya sessions. If you manage site sessions independently, you will need to terminate those sessions explicitly, as Gigya cannot terminate your site session for you.
Assign SSO Segments
To configure the sites of the SSO group:
- In the Site Groups page, in the Admin tab of Gigya's Console, click the Parent Site ID or the Edit Site Group icon .
- Make sure the SSO enabled box is checked.
- All sites in the group are assigned to the DEFAULT SSO Segment initially. To assign them to a different segment, click the value under SSO Segment and type the name of the relevant segment. For example, assign the first three sites in the group a segment of "1" to group them into one segment, and the next two sites the segment "2" to group them into a separate segment.
- Add the relevant Logout URLs.
- Save changes.
The SSO feature relies on 3rd party cookies (3pc). In some browsers, 3pc is disabled by default (e.g., Safari), meaning that SSO will not work for users using those browsers.
Users who block third party cookies will need to log in as well. For a potential workaround, see Supporting SSO on Browsers That Block Third-Party Cookies.
Member Site Policy Override
When overriding policy for individual member site in a site group configuration, it is important to bear a number of items in mind:
- When overriding email verification policy in individual member sites, if a user first registers to a site that does not require email verification and then subsequently navigates to a member site that does, the user will be required to complete the email verification process for the second site, even though they were not required to do so with the first.
- When required fields are overridden by a member site, if a user first registers to a site that does not require a particular field and then subsequently navigates to a site that does require that field, the user will be required to complete the registration process and fill in any required information. In this case, make sure the required field is included in the Registration Completion screen.
How it Appears on the Console
In the home page of the Gigya console, you will see a list of the sites associated with your partner ID.
Site groups are visually grouped together. The master site has a collapse / expand control next to its name:
All sites under that node, are its child sites.
The site groups will appear first in the console, followed by the individual sites (i.e., not members of any group).