Important Note - Facebook SSL Security Requirement
Due to Facebook security restrictions on public, production Facebook apps, a secure (HTTPS) URL is required to deliver Jive content to Facebook. This means that if you plan on using the Facebook Extension you must have an SSL certificate installed in your Jive instance. If you do not currently have an SSL certificate installed, you can work with Jive Support, by filing a support case, in order to get this set up for you.
The purpose of this document is to describe the functionality of the Facebook App Plugin (aka Facebook Extension), hereafter referred to as "the plugin." This document currently references the version of the plugin that is compatible with Jive 5.0, but also is consistent with the configuration and setup of the Jive 4.5 version as well. The only visible difference is that of the user profile page in the Facebook Account Linking section, since the user profile page has been updated in Jive 5.0. The process is still very much the same, just that the account link block is displayed in a slightly different location in the sidebar.
Admin Console Configuration
The configuration of the plugin is located in the admin console under the System tab --> Management sub tab --> Facebook App sidebar item.
There are 2 separate sections within the configuration: General Settings and Facebook Apps
This section contains all of the base settings for the Facebook App Plugin, which includes the following:
- Enabled/Disabled - whether to enable or disable Facebook App authentication
- Note: this only controls the authentication portion of the plugin and not the plugin in its entirety. Even if disabled, the Facebook canvas can still be displayed.
- App ID for User Authorization (optional) - this is the Facebook App ID to use when linking Facebook accounts to Jive user accounts, see User Profile Configuration below.
- This can be any available app configured in the Facebook Apps section, described below. If not specified, the first app in the list will be used by default.
- Account Login URL - the URL to direct a user to when asking them to authenticate to Jive in order to then link their Facebook account.
- When not using an SSO in the community the URL should be <jiveUrl>/login.jspa, otherwise, the login page for the SSO should be referenced here.
- App Banner URL (optional) - the URL which points to a banner image to be displayed at the top of the Facebook canvas.
This section is where to define all of the Facebook Apps (aka Pages) that will interace with this Jive community. Use the input form at the bottom of the page to add new Facebook Apps. You can also use theinput form to update the settings of an existing App. If the App ID entered matches and existing App, already defined, then the existing App will be updated with the new settings. The settings for each App are defined as follows:
- App ID - this is the ID, provided by Facebook, for the given applicaiton
- App Secret - this is the secret key, provided by Facebook.
- Note: This value should be protected since it is responsible for insuring the authenticity of login requests.
- Container Type - Community or Social Group, these are the only 2 types of containers that are allowed to be used.
- Container ID - the Jive internal ID of the Community or Social Group.
- Container Activity - if checked, will only display activity in the stream that belongs to the specified container, otherwise global Jive activity will be displayed.
- Container Search - if checked, will only search for results within the specified container, otherwise a global search will be performed.
Note: regardless of the Activity/Search settings, a valid container must be specified so that content (in this case, currently only Questions) are posted in the proper place.
User Configuration: Facebook Account Linking
Unlike the previous version of the plugin, which attempted to integrate with Jive core user authentication and user provisioning, the current version of the plugin does not. The current plugin is completely independent, with respect to Facebook apps and Facebook user accounts. In fact no new users are ever provisioned by the plugin. What this means is that in order to contribute new content (post, like, comment, etc.) to the community, via Facebook, the following must be true:
- The user has an existing user account in Jive.
- If they do not, they will be directed to create one - either through the Jive user registration process, or through a customer-provided SSO.
- This is a little more work for the user, but also means no more duplicate user accounts and customers can control user account creation - a big plus.
- The user has connected their Facebook account to their Jive user account. This is what we are referring to as Facebook Account Linking
- Even if the user already has a Jive user account, they will be asked to manually link their accounts, via their user profile page - shown below.
If a user is viewing their own personal profile page, the following will be displayed. Note the newly added Facebook block in the sidebar:
Before the user has linked their Facebook account, they will see the following:
After the user has linked their Facebook account, the block will update as shown below:
If, when linking accounts, the user is already authenticated to Facebook then this linking and unlinking will be absolutely seamless. A small popup will be displayed to confirm the action, a second popup from Facebook will grab the proper authentication, and the link/unlink action will occur. If the user has not yet been authenticated to Facebook, when they select to link (or unlink) their account they will see the following, familiar Facebook login dialog:
Note: The user does NOT have to manually go through this process prior to visiting the Facebook page. If the user has not done so (either not created an account or not linked to Facebook) then the user will be directed through the process from the Facebook canvas itself, which will be documented below.
The Facebook App Canvas
This section will describe the plugin canvas - this is the view of what will be displayed within the Facebook App and what allows the surfacing of Jive community content to Facebook. In other words, this is what you really all came here to see. The rest was all setup, this is where the real action takes place for the user.There are three main things a user can do from within the canvas:
- View Recent Activity
- Search for Content
- Create Content (Communicate)
Note: the user does NOT have to be linked to Jive or authenticated to Jive to do the first 2 items. Any user can view activity or search for content, only when attempting to create content within Jive is authentication to Jive required.
View Recent Activity
This is what is shown by default within the canvas:
This should be relatively self-explanatory, it is just a listing of the recent activities within Jive. This may be limited to a single container, or global, depending on the App settings in the admin console. There are links back to the original content in Jive, the author's Jive user profile, and the Jive container for each and every item. Clicking on "View likes" or "View replies" under each item will expand to display the people who have liked an item or who have replied to an item. Clicking the same "View" link will subsequently collapse the block and hide it from view.
Ten activities are shown by default. When there are more activities that can be displayed, the following will be shown:
Clicking on "More Activities" will then load the next collection of ten activities and append them to the current list.
Search for Content
At the top of the canvas there are two controls - one for asking a question and another for performing a search. Ask a Question is the default control:
Clicking on the Search control will change the input for slightly:
After a search is entered and submitted, the lower tab will automatically switch to "Search Results" and the results will be rendered in an identical manner to that of the activity stream:
Everything that applies to the activity stream, with respect to available links, showing likes and replies, and showing more search results, also applies to search results as well. The consistency of the experience between the two tabs should make it easy for a user to interact with either activity stream content or search results.After performing a search, clicking back on the Recent Activity tab will automatically reload the latest 10 activities.
Create Content (Communicate)
There are a few different ways that a user may interact with the canvas in order to create content:
- Ask a Question
- Like Content
- Reply to Content
Before discussing exactly how a user can create content, let's step back a moment and discuss what is required of the user when they actually attempt create content. When an attempt is made to create content the following validations are done:
- User has their Facebook account linked to an existing Jive account
The user must accept, by clicking "Allow" on the dialog box in order to create content. If the user does not accept, and clicks "Cancel" then the dialog will close and the content creation action will be ceased.
If the user has not linked a Jive account to Facebook, the following dialog will be displayed:
Clicking on the "Log in to Jive..." link at the bottom of the dialog will take the user to the Login URL defined in the admin console configuration. Once the user has logged into Jive they will automatically be forwarded to their user profile page and will be scrolled down to the Facebook Account Link section in order to link their Facebook and Jive accounts.
Now that this has been completed, we can move on to the subject of content creation.
Ask a Question
By default the control input at the top of the page defaults to the Ask a Question form, which looks like the following:
Once the user enters the input text field the input will change slightly to signify a post is being created:
The user then enters the question that would like to ask and clicks the "Post" button. This will then post the question to the community and will also automatically collect all pertinent information about the discussion and prepend it to the top of the activity stream.
Let's use the following item as an example:
When liking content a user may choose to like a top-level item itself, or may also choose to like an specific comment/reply. Clicking the "Like" link, on either a piece of content or a reply, will update any pertinent like count or list of users. It will also change the state of the "Like" link to "Liked". Once an item has been liked, the "Liked" link can be then clicked to remove the current user's like from the item.
Note: In some cases, the like link will be completely disabled. This is the case when a user is the owner of a piece of content. Within Jive a user cannot like their own piece of content, so in that case, for an authenticated user displaying their own content/reply, the like link will be disabled. Also not that this does not take affect until a user has actually authenticated to Jive, which means they must first attempt to create some piece of content before this takes affect. So the first time activity is displayed, or content is searched, the like link will always be available - but in either case, link availability aside, a user will never be able to successfully like their own item.
Reply to Content
Again, let's reference the example image above. There are two ways to bring up the comment/reply box in order to reply to content: either click the Comment link at the end of the author block on the content item itself, or alternatively if the item already has replies, click the "View replies" link which will show all existing replies as well as the reply input form.
Simply typing a reply and hitting enter will submit a reply. The display block for the replies will also update to show the reply which the user just submitted.