Facebook Permissions for ASP.NET

Facebook Permission control is used to enable the user to add permissions for Facebook applications or Facebook Connect web sites, like permission to send email, permission to update status, permission to access the stream publish, etc. It is very important to understand the right usage of Permissions ASP.NET control, to ask the user for permissions when he logs in to Facebook Connect website or Facebook iFrame application for the first time. For mandatory permissions, permissions which are crucial for basic functioning of an application, like getting user email that is required for registration, it is not correct to use Permission control. In that case, you should use Facebook Login Button for Facebook Connect websites. List of permissions is placed in Login URL for iFrame application, as you can see in code example on the bottom of this page.

However, there are some optional permissions that are not crucial for correct functioning of an application, but they can enable some additional features, if the user is willing to grant them. Example of optional permission is one to send a SMS. It is not good custom to request from user to grant SMS permission when he is installing the application the first time. There are lots of people who will give up on using the application if the receiving of SMS is requirement for the basic usage of application. If the SMS permission is only a nice addition for the application, many users would rather grant this permission once they test the application for a while. This is where Permissions ASP.NET control takes place - to enable users to grant some optional permissions, once they tested the application. The Facebook Permissions has an event handler which is called if permissions are added, and allows the developer to add some extra code for this case. After permissions are granted by user, it is also possible to get the list of all granted permissions.

Compiled version and source code version of this ASP.NET control are available in C# and VB.NET programming languages, as part of Facebook iFrame ASP.NET library and Facebook Connect ASP.NET control library.

The list of all available permissions can be found inside Facebook official documentation at: Facebook Extended Permissions

Picture of permission dialog in Firefox:

Configuration

Configuration of the Facebook Permissions ASP.NET control is done in ASPX page by setting properties and optional event handler. If dynamic setting of properties is required, they can be also set in the code behind, for example on Page_Load method. If event handler is used, there should be a method in the code behind to execute additional code after a user grants permissions. There is only one event handler, which is executed when user grants permissions. On rendering of the control, there is verification if all permissions from the list are valid. That eliminates typing mistakes of the developer while entering permissions. In case of fault, an exception will be thrown, and the developer will be informed about the error.

Property Name

Type

Description

PermissionList

String

Comma separated list of extended permissions.

CommandType

String

Can be set on 'link', 'button', or 'auto_open'. These mean permissions popup dialog is opened by pressing a link, button, or automatically on page load. Default value is 'link'.

Text

String

Text of permissions button or link. If 'auto_open' command type is used, this parameter is not required.

ConfirmedPermissions

IList

This is read only property to get list of granted permissions after user grants or denies them. The list is consists of PermissionEnum objects. It is usually used in OnAddedPermission event handler.

Event Name

Description

OnAddedPermission

Has to be set to name of protected method that is implemented inside the code behind and which will be called after user grants permission(s).

Usage Examples:

Following example shows usage of Facebook Permissions ASP.NET control, from registration and insertion in ASPX file, to implementation of an event handler in the code behind. Example is given in C# and VB.NET programming languages. The code from event handler reads the list of granted permissions and writes it in the string, as comma separated values.

Example in ASPX file shows only the code required for registration and integration of ASP.NET control in a web page. To see all requirements for registered components, including JavaScript, CSS style and header setting, please look at the manual for page requirements. For following examples, all page requirements are placed in ASP.NET master page. Important parts for registration and integration of Facebook Invite Friends control inside ASP.NET page are highlighted.

 <%@ Page MasterPageFile="~/Master.Master" AutoEventWireup="true" Inherits="FVK_Demo.Permissions" %>
 <%@ Register TagPrefix="fvk" TagName="permissions" Src="~/FVK/Permissions.ascx" %>
 <asp:Content ID="Content1" ContentPlaceHolderID="head" runat="server">
    <title>Facebook Permissions for ASP.NET</title>
    <meta name="description" content="ASP.NET implementation of Facebook Extended Permissions." />
 </asp:Content>
 <asp:Content ID="Content2" ContentPlaceHolderID="ContentPlaceHolder1" runat="server">
    <fvk:permissions id="permissions1" runat="server" 
        CommandType="button" 
        Text="Add Permissions" 
        PermissionList="publish_stream, video_upload" 
        OnAddedPermission="OnAddPermission" 
     />
 </asp:Content>

Following code shows the code behind to demonstrate the implementation of an event handler in C# programming language. When user grants permissions, OnAddPermission method is executed. The code inside the method is using ConfirmedPermissions property to get the list of granted permissions, and create string as comma separated values.

 using System;
 using System.Collections.Generic;
 using System.Linq;
 using System.Web;
 using System.Web.UI;
 using System.Web.UI.WebControls;
 using Facebook;
 using FVK;

 namespace FVK_Demo
 {
    public partial class Permissions : System.Web.UI.Page
    {
       protected void Page_Load(object sender, EventArgs e)
       {
            
       }

       protected void OnAddPermission(object sender, EventArgs e)
       {
          string permissions = "";
          foreach (PermissionEnum perm in permissions1.ConfirmedPermissions)
          {
             permissions += perm.ToString() + ", ";
          }
       }
    }
 }

Following code shows the code behind, which is the same as the one above, but in VB.NET programming language. When user grants permissions, OnAddPermission method is executed. The code inside the method is using ConfirmedPermissions property to get the list of granted permissions, and create string as comma separated values.

 Imports System.Collections.Generic
 Imports System.Linq
 Imports System.Web
 Imports System.Web.UI
 Imports System.Web.UI.WebControls
 Imports Facebook
 Imports FVK

 Namespace FVK_Demo
    Public Partial Class Permissions
       Inherits System.Web.UI.Page
       Protected Sub Page_Load(sender As Object, e As EventArgs) Handles Me.Load

       End Sub

       Protected Sub OnAddPermission(sender As Object, e As EventArgs)
          Dim permissions As String = ""
          For Each perm As PermissionEnum In permissions1.ConfirmedPermissions
             permissions += perm.ToString() & ", "
          Next
       End Sub
    End Class
 End Namespace

Mandatory permissions for iFrame applications:

As it is stated in the beginning of this page, Facebook Permissions ASP.NET control is used for optional permissions. While for Facebook Connect websites it is enough to use Login button control instead Permission control, for iFrame applications it is little more complicated. Following example code shows how to set mandatory Facebook permissions to be requested when user starts an iFrame application for the first time. Note that the code is using object from Graph API Facebook C# SDK to get login URL from provided parameters, including permission list. Important parts of the code are highlighted.

 using System;
 using System.Collections.Generic;
 using System.Linq;
 using System.Web;
 using System.Web.UI;
 using System.Web.UI.WebControls;
 using Facebook;
 using Facebook.Web;
 using FVK;

 namespace FacebookStart
 {
    public partial class Default : Page
    {
        protected void Page_Load(object sender, EventArgs e)
        {
            if (!Page.IsPostBack)
            {
                var auth = new CanvasAuthorizer { Permissions = new[] { "perm1", "perm2" ... } };
                 
                if (auth.Authorize())
                {
                    var facebook = new FacebookWebClient();

                    // check if facebook session is valid
                    try
                    {
                        JsonObject basicData = (JsonObject)facebook.Get("me?fields=id,name");
                    }
                    catch (Exception)
                    {
                        Session.Clear();
                        auth.HandleUnauthorizedRequest();
                        return;
                    }
                }
            }
        }
}

 Imports System.Collections.Generic
 Imports System.Linq
 Imports System.Web
 Imports System.Web.UI
 Imports System.Web.UI.WebControls
 Imports Facebook
 Imports Facebook.Web
 Imports FVK

 Namespace FacebookStart
    Public Partial Class [Default]
       Inherits Page
       Protected Sub Page_Load(ByVal sender As Object, ByVal e As EventArgs) Handles Me.Load
            If Not Page.IsPostBack Then
                Dim auth = New CanvasAuthorizer() With {.Permissions = New String() {"perm1", "perm2" ...}}

                If auth.Authorize() Then
                    Dim facebook = New FacebookWebClient()

                    ' check if facebook session is valid
                    Try
                        Dim basicData As JsonObject = DirectCast(facebook.[Get]("me?fields=id,name"), JsonObject)
                    Catch generatedExceptionName As Exception
                        Session.Clear()
                        auth.HandleUnauthorizedRequest()
                        Return
                    End Try
                End If
            End If
        End Sub
    End Class
 End Namespace