Walkthrough: Configuring Social Connector to work with a social network

Last updated Tuesday, April 12, 2016 in Social Connected for Developer, Administrator

After you have installed the Social Connected module, you must configure the Social Connector before website visitors can log in to your website using social network credentials.

This walkthrough outlines how to:

Create a social network application

Before you can link your website to a social network, you must first create an application. The Social Connected module receives visitors' profile information from a social network via the social network application.

You can create applications and link to the following social networks:

  • Facebook
  • Twitter
  • LinkedIn
  • Google+

Create a Facebook application

To create a Facebook application:

  1. Go to https://developers.facebook.com/apps and create an application on the website platform.
  2. In the Facebook application, fill in all the required fields.
  3. Add a website platform.
  4. Enter the URL of the webpage where you want to place the login controls.

    social connected create a facebook app 01

  5. In the App Domains field, enter all the CD and CM domains, and in the Site URL field, enter the CM domain:

    social connected create a facebook app 02

    If your Sitecore instance uses a scaled environment, Social Connector requires that the base domain for all the Content Delivery (CD) and Content Management (CM) servers is the same.

  6. On the pane on the left, click Status & Review, and click the switch to make your app publicly available.

    social connected make facebook app available

Facebook Business Manager

Note

You can use this functionality of Social Connected starting from Sitecore XP 8 Update-2.

In case you plan to assign different Facebook applications to different Facebook login controls, you should perform additional configuration.

Starting from version 2.0, Facebook Graph API introduces application-scoped user IDs, which means that an ID of the same person is different between Facebook applications.

To allow Social Connected properly match users across different applications, you should set up the Business Manager and link it to all Facebook applications you are planning to use on your site. For more information on how to set up the Business Manager, visit the following website: https://business.facebook.com/

Create a Twitter application

To create a Twitter application:

  1. Go to https://dev.twitter.com/apps and create a new application.
  2. In the Twitter application, fill in all the required fields.

    social connected create a twitter app 01

  3. Enter the URL of the webpage where you want to place the login controls.
  4. Set the application permissions to Read, Write and Access direct messages.

    social connected create a twitter app 02

Create a LinkedIn application

To create a LinkedIn application:

  1. Go to https://www.linkedin.com/secure/developer and create a new application.
  2. In the LinkedIn application, fill in all the required fields.
  3. Enter the URL of the webpage where you want to place the login controls.

social connected create a twitter app 03

Create a Google+ application

To create a Google+ application:

  1. Go to https://console.developers.google.com/project and create a new project.
  2. In the Google+ project, enable Google+ API.

    social connected create a google app 01

  3. On the Credentials page, create a new client ID.
  4. In the Create Client ID dialog box:
    • In the Authorized Javascript origins field, enter http://hostname
    • In the Authorized redirect URI field, enter:

      http://hostname/layouts/system/Social/Connector/SocialLogin.ashx?type=google_access

      http://hostname/layouts/system/Social/Connector/SocialLogin.ashx?type=google_add

      http://hostname/layouts/system/Social/Connector/SocialLogin.ashx?type=access

      where hostname is the name of the host that is running the website.

    If your Sitecore instance uses a scaled environment, in the Authorized redirect URI field, enter the same URIs replacing hostname with all the CD and CM domains, for example:

    social connected create a google app 02

  5. On the Credentials page, in the Public API access section, click Create new Key.

Create a Sitecore item for a social network application

After you have created a social network application, you must create a Sitecore item for it. This Sitecore item contains connection keys that Sitecore uses to work with the social network application.

To create a Sitecore item for the social network application:

  1. In Sitecore, in the Content Editor, open the sitecore/system/social/applications/default folder.
  2. Create an item based on the sitecore/templates/system/social/application template.

    Important

    The sitecore/system/social/applications/default folder must contain only one item for a social network. If you want to use several web applications for one social network, you must create new items for each web application in the sitecore/system/social/applications folder.

  3. In the new item, fill in the Application Id, Application Secret, Public API key (for Google+ only) and Network fields:

    Field

    Value

    Application Id

    Facebook – the App ID value

    Twitter – the API Key value

    LinkedIn – the API Key value

    Google+ – the Client ID value

    Application Secret

    Facebook – the App Secret value

    Twitter – the API Secret value

    LinkedIn – the Secret Key value

    Google+ – the Client Secret value

    Public API key

    Google+ – the API Key value

    Network

    Networks/Facebook

    Networks/Twitter

    Networks/LinkedIn

    Networks/Google+

    Picture 1

Configure access to a visitor’s profile information

The first time a visitor logs in to your website with their social network credentials, the social network asks the visitor to grant your website access to the information on their social network profile. You can configure a set of fields that the social network application requests access to.

The following image, shows an example of the dialog box that a social network user sees the first time they log in to the website with their social network credentials:

social connected access to profile info

To set the list of fields that the social network application can access in the visitor's profile on a social network:

  1. Open the [website_root]\app_config\include\social\sitecore.social.profilemapping.[network_name].config file.
  2. In the configuration section for the social network, in the configuration section for the field that you want the social network application to use, set the field enabled parameter to true.
  3. If the field is private, you must set its permission parameter according to the official social network documentation.

Important

Do not disable the fields that are enabled by default because this might affect the way that they are presented on your website.

For example, to get access to the Groups’ field on Facebook, the field section in the Sitecore.social.profilemapping.Facebook.config file should look like this:

<!-- 'Groups' field. -->
<!-- The Groups that the user belongs to. -->
<field enabled="true" originalKey="" sitecoreKey="fb_groups" permission="user_groups" access="/me/groups" text="Groups" />

For more information about user profile fields, see the official documentation of the social network:

Request approval for Facebook application permissions

This information is only relevant to Facebook applications.

After you have set the list of fields that the Facebook application can access in the Facebook visitor's profile, you must get Facebook approval for permissions. The permissions relate to a field or group of fields. Facebook requires approval for some permissions before you can get access to the fields with those permissions.

For the Social Connected module and the Experience Profile application to work correctly, a Facebook application must have access to the following permissions:

Permission

Description

Requires Facebook approval

public_profile

Used in the Social Connector, personalization, and in the Experience Profile

Gives access to a subset of a user's public profile fields:

  • id
  • name
  • first_name
  • last_name
  • link
  • gender
  • locale
  • age_range

No

user_friends

Used in the Social Connector

No

email

Used in the Social Connector and personalization

No

user_birthday

Used in the Social Connector, personalization, and in the Experience Profile

Yes

user_education_history

Used in the Social Connector, personalization, and in the Experience Profile

Yes

user_interests

Used in the Social Connector, personalization, and in the Experience Profile

Yes

user_likes

Used in the Social Connector, personalization, and in the Experience Profile

Yes

user_location

Used in the Social Connector, personalization, and in the Experience Profile

Yes

user_relationships

Used in the Social Connector, personalization, and in the Experience Profile

Yes

user_religion_politics

Used in the Social Connector, personalization, and in the Experience Profile

Yes

user_website

Used in the Social Connector, personalization, and in the Experience Profile

Yes

user_work_history

Used in the Social Connector, personalization, and in the Experience Profile

Yes

read_stream

Used in the Social Connector and personalization

Yes

publish_actions

Used in content posting and goal posting

Yes

manage_pages

Used in content posting

Yes

The other fields that you enable in the Sitecore.Social.ProfileMapping.Facebook.config file might require Facebook approval.

You can read more about permissions with Facebook login on Facebook's website.

You can also find more information about Facebook's review guidelines on their website.

Configure and add the social network log-in control

After you have created a social network application and a Sitecore item for it, and you have configured access to the visitor's profile information, you can configure and add a social network log-in control to your website. The visitors use this control to log in to your website.

You can add log-in controls in the same way that you add new components on the webpage. The controls are located in the sitecore/layout/sublayouts/social/connector folder. For the MVC layout, use the Social Connected renderings in the sitecore/layouts/Renderings/Social MVC/Connector folder. You can customize this control by changing images, texts, and so on.

By default, the social network control uses the social web application that is stored in the sitecore/system/social/applications/default folder.

To set a non-default social network application for the social network control in the UI:

  1. In the Content Editor, select the item that you want to place a login control on.
  2. On the ribbon, in the Presentation tab, click Details.
  3. In the Layout details dialog box, add the Login with <social network> control.
  4. Click the control and in the Application field, select the application that you want the control to use.

To set a non-default social network application for the social network control using the API, pass the Application Key and Application Secret values of the application to the API using the ApplicationCredentials class.

To set the webpage that the visitor is redirected to after they have entered social network credentials and granted access to their profile information:

  1. In the Content Editor, select the item presentation details.
  2. Add a Social Connector control.
  3. Edit the control.
  4. In the Callback URL field, enter the URL of the webpage.

    If this field is blank, the module uses the URL of the current item.

Improve the performance of Social Connector

After you have performed all the required configuration actions, you can reduce the time that the Social Connector spends on finding an existing user when the website visitor logs in to your website. To do this, in the web.config file, in the configuration/system.web/profile/properties section, paste the following string:

<add type="System.String" name="SC_SocialNetworkId" />
Send feedback about the documentation to docsite@sitecore.net.