Facebook Connect and KickApps
From KickApps API Reference
Note: Facebook has made changes to the Facebook Connect platform by deprecating Template Bundles. If you are still using template bundles, your Facebook Connect functionality may break on December 20th. Please update your code as described below.
The following documentation is written for KickApps' Facebook Connect version 2. If you are using an older version of the script, you must upgrade as soon as possible to prevent any disruptions in your Facebook Connect service.
To check which version you are using, simply look at the JavaScript file that you are including.
- facebookConnect.js is the legacy version.
- facebookConnect.v2.js is the current version.
If you are upgrading your implementation, you can skip to Configure Facebook Connect on your KickApps community
Facebook Connect is a Facebook feature that allows your KickApps site to post updates to a member's Facebook profile. This helps increase exposure to your KickApps community by leveraging the Facebook newsfeed.
This documentation is split into two parts. The first part deals with Facebook and setting up your application and activity stream templates. The second part deals with your KickApps site, and how you can enable Facebook Connect in it.
Contents
|
Configure a Facebook application and templates
Sign up for Facebook Developers group
Sign into your Facebook account and follow the link below to add the Facebook Developer Application
http://www.facebook.com/developers
Set up your application
Once you have installed the Developer application, you should be taken to the “My Applications” page as seen here:
Now, Click on “Set up new Application” and you will be taken to the following page:
Enter your Application Name here. You can call your application anything you want, but remember that it will be displayed to the users of your website so choose carefully. Congratulations, you have created a Facebook Application. Now we need to configure it for use with your KickApps Community.
After saving your new application, the first screen you see shows you the Essential Information and Basic Information, as seen below:
Make note of the API Key located in the Essential Information section. You will need this to configure Facebook Connect for your KickApps Community.
In the Basic Information section, the Description, Icon, and Logo are optional fields, but we recommend that you enter at least a description and an Icon. The Icon will be displayed in your users’ newsfeed. If you do not upload an Icon, a dotted grey line will be shown. Next, click on the Connect link on the left side bar underneath Canvas. You should now see the screen below:
Under Connect URL, you must enter the callback URL for your Facebook Connect application. KickApps hosts this file for you, but you must construct this URL such that it matches your community’s domain.
For example, the KickDeveloper community is hosted on http://community.kickdeveloper.com so our Connect URL would be: http://community.kickdeveloper.com/ . If your site is not DNS masked, your Connect URL would be http://affiliate.kickapps.com/ .
Under Base Domain enter your base domain. If your site were http://community.kickdeveloper.com you would enter kickdeveloper.com as the Base Domain. If your site is not DNS masked, you would enter kickapps.com as the Base Domain.
At the bottom of the page, press Save Changes. You are done configuring your application.
Configure Facebook Connect on your KickApps community
Note: As of KickApps 4.0, Facebook Connect is supported but is not surfaced as a feature in the Affiliate Center. It must be manually configured. In future versions of the KickApps platform, we will support the configuration of Facebook Connect straight from the Affiliate Center.
Add Facebook Connect to your Global Page Template
- Login to your KickApps Affiliate Center and navigate to the Global Page Template by selecting Configure > Pages then selecting Global Page Template from the left side.
- Insert the following code in the Footer Code text box:
<script src="http://static.ak.connect.facebook.com/js/api_lib/v0.4/FeatureLoader.js.php" type="text/javascript"></script>
<script type="text/javascript" src="http://affiliate.kickapps.com/js/facebookConnect.v2.js"></script>
<script type="text/javascript">
Ka.FacebookConnect.init({
apiKey: 'YOUR-API-KEY',
buttonHtml: '<p><img src="http://static.ak.fbcdn.net/images/icons/favicon.gif" /> <input class="ka_fb_connect ka_button" type="checkbox" /> Publish this activity to Facebook</p>',
autoChecked: true,
autoScroll: true
});
</script> - In the above code, replace YOUR-API-KEY with your Facebook Application’s API Key as noted in the Essential Information listed in step 1.
- buttonHtml is an HTML string that will be inserted onto the page wherever Facebook Connect is supported. You may customize this HTML. The only required element in this HTML is:
<input class="ka_fb_connect" type="checkbox" />
Note: If a checkbox with the class "ka_fb_connect" is not found, the Facebook Connect feature will not function properly.
- autoChecked is a Boolean property that denotes whether or not you want the Facebook Connect feature to be checked off and enabled by default. Your users still have the option to uncheck it if they so choose.
- autoScroll is a Boolean property that denotes whether or not you want the Facebook Connect box to automatically re-center when the page is scrolled.
Facebook Connect Events
Our Facebook Connection implementation defines two events:
For these events to work, you must listen to them before you execute the Ka.FacebookConnect.init() method.
Select which features you want to support
By default, the KickApps Facebook Connect implementation supports and enables the following features:
- Media Uploads
- add-audio
- add-blog
- add-photo
- add-video
- Media Commenting
- media-audio-commenting
- media-blog-commenting
- media-photo-commenting
- media-video-commenting
- Media Favoriting
- media-add-favorite
- Member Profile Commenting
- member-profile-commenting
- Member Community Joining
- member-join-community
- Group Join
- group-join
- Message Board Discussions
- message-board-create-discussion
If you would like to modify which features are enabled you can do so by using the following code:
<script type="text/javascript">
Ka.events.listen('fbc-before-init', function(){
var actions = Ka.Settings.FacebookConnect.actions;
actions['media-video-commenting'].enabled = false;
});
</script>
Note This event must be listened for before the Facebook Connect script is initialized.
Customizing the buttonHtml for a given feature
You can customize the HTML markup for the checkbox for any actionby adding a property called 'buttonHtml' like the following code:
<script type="text/javascript">
Ka.events.listen('fbc-before-init', function(){
var actions = Ka.Settings.FacebookConnect.actions;
actions['media-video-commenting'].buttonHtml = '<div><input class="ka_fb_connect" type="checkbox" /></div>';
});
</script>
Note This event must be listened for before the Facebook Connect script is initialized.
Template strings
Our implementation is pre-configured with a bundle of template strings defined by the following keys in the Ka.Messages.FacebookConnect object:
- DEFAULT_STORY_TITLE
- ACTION_LINK_TEXT
- DIALOG_PROMPT
- ADD_MEDIA_BLOG
- ADD_MEDIA_BLOG_TITLE
- ADD_MEDIA_PHOTO
- ADD_MEDIA_PHOTO_TITLE
- ADD_MEDIA_AUDIO
- ADD_MEDIA_AUDIO_TITLE
- ADD_MEDIA_VIDEO
- ADD_MEDIA_VIDEO_TITLE
- MEDIA_COMMENT_BLOG
- MEDIA_COMMENT_PHOTO
- MEDIA_COMMENT_AUDIO
- MEDIA_COMMENT_VIDEO
- MEDIA_ADD_FAVORITE
- MEMBER_PROFILE_COMMENT
- MEMBER_JOIN_COMMUNITY
- GROUP_JOIN
- GROUP_LEAVE
- MESSAGE_BOARD_CREATE_DISCUSSION
Example
Ka.Messages.FacebookConnect.ADD_MEDIA_BLOG = "{*actor*} added a new blog entry titled "($mediaTitle)" at ($siteName).";
Ka.Messages.FacebookConnect.ADD_MEDIA_BLOG_TITLE = "Check out this new blog entry on ($siteName)";
If you would like to see the contents of all of the strings, you can either view the source of the script (facebookConnect.v2.js) or you can run the following command in the Firebug console:
console.dir(Ka.Messages.FacebookConnect)
Modifying Template Strings
For Facebook Connect, each action has a body and a title. The key for the title of an action is the same key for the action with '_TITLE' appended to it. If a title is not found for a given action, the DEFAULT_STORY_TITLE will be used.
In our implementation, media comments do not have specific titles. In other words, we have defined an action called MEDIA_COMMENT_BLOG but have not defined MEDIA_COMMENT_BLOG_TITLE so when commenting on a blog, we will use the default story title, DEFAULT_STORY_TITLE.
<script type="text/javascript">
Ka.events.listen('fbc-before-init', function(){
var msg = Ka.Messages.FacebookConnect;
msg.ADD_MEDIA_BLOG = "{*actor*} posted '($mediaTitle)', a sweet new blog!!";
msg.ADD_MEDIA_BLOG_TITLE = "Woohoo! A new blog was posted on ($siteName)!";
});
</script>
Note This event must be listened for before the Facebook Connect script is initialized.
String Tokens
These strings are dynamically created based on the tokens inside of them. String tokens must be enclosed in parenthesis and prefixed with a dollar sign. Supported tokens will be automatically replaced with the specified value. Unsupported tokens may cause unexpected behavior.
Currently we support the following tokens inside of these strings:
- $mediaUrl - This is the URL of the media play page, member profile, group page, or message board discussion page
- $mediaTitle - This is the title of the media, member profile, group name, or message board discussion title
- $siteName - This is the name of your site, as defined in your Affiliate Center
Examples of all of the above techniques
We have compiled a list of possible configurations which can be found in the Facebook Connect Examples page.
Save and test
You have completed the Facebook Connect configuration. If you are logged into your community, you should start seeing the Facebook Connect feature wherever you have enabled it. Try it out and make sure the strings are being displayed as you intended them to. Make any necessary adjustments and enjoy all the new traffic you get from Facebook!