An extensible Pyramid application that provides default routes and views for Facebook canvas application.


Install using pip, e.g. (within a virtualenv):

$ pip install pyramid_facebook


  1. Once pyramid_facebook is installed, you can use the config.include mechanism to include it into your Pyramid project’s configuration. In your Pyramid project’s

    config = Configurator(.....)

    Alternately, instead of using the Configurator’s include() method, you can activate Pyramid by changing your application’s .ini file, use the following line:

    pyramid.includes = pyramid_facebook
  2. Create a Facebook application on

  3. pyramid_facebook obtains facebook application information from the **settings dictionary passed to the Configurator. It assumes that you’ve placed some of your facebook application configuration parameters prefixed with facebook. in your Pyramid application’s .ini file:

    facebook.app_id = 123456789
    facebook.secret_key = 5fbf6252b38eec5d7f8a6962c8a00556
    facebook.namespace = myfacebookapp
    facebook.scope = user_events
  4. In the app settings on, set callbak url to point to your server. when developing, it is handy to point your localhost:{facebook application namespace}/
  5. Define your facebook canvas view:

    from pyramid_facebook.canvas import facebook_canvas
    def canvas(context, request):
       # 1 canvas is available only to users who grant application all
       #   permissions defined in setting['facebook.scope'].
       # 2 context.facebook_data dict contains signed_request content.
       #   i.e.:
       #   user_id = context.facebook["user_id"]
       return Response('Hello Facebok World')
  6. Register event handlers on Oauth accept or deny by subscribing to OauthAccept and OauthDeny:

    from import subscriber
    from import OauthAccept, OauthDeny
    def user_accept(context, request):
    def user_deny(context, request):
  7. Visit your app on[facebook app namespace]

  8. To get facebook credits running, set credits callback in your facebook application settings to point to[facebook app namespace]/credits

  9. Define your get item method using facebook_payments_get_items decorator.

  10. Subscribe to payments update events:

    1. DisputedOrder
    2. RefundedOrder
    3. PlacedItemOrder
    4. EarnedCurrencyOrder

Under The Hood


class pyramid_facebook.canvas.facebook_canvas(**kwargs)

Decorator that registers a view for the facebook_canvas route with the view_canvas permission.

Accepts same arguments as view_config:

def canvas(context, request):
    return {
        'title': 'A great Facebook Game'
class pyramid_facebook.credits.facebook_payments_get_items

Decorator to register the function to process facebook credits payments_get_items.

Decorated function receives 2 positional parameters:

  • context: The FacebookCreditsContext the request is associated with. context.facebook_data["user"] gives information about user’s locale which would permit to return different languages.
  • request: The request itself.

It is possible to access order_info via context.order_info:

Decorated function must return a dictionary structured as:

    # Required:
    "title":       "100 diamonds",
    "description": "100 shiny diamonds!",
    "price":       1000,
    "image_url":   "",

    # Optional (according to facebook doc):
    "item_id": "123",
    "data":    "whatever"


def get_item(context, request):
    return {
        "title": a_title,
        "description": a_description,
        "price": a_price_in_facebook_credits,
        "image_url": an_image_url



Security context for facebook signed request routes.


Contains facebook data provided in signed_request parameter decrypted with SignedRequest.parse


Context for facebook credits callback requests.


Modified field received in facebook credits callback for payment status update for earned app currency.


The item info as passed when FB.ui method is invoked.


Order details received in facebook credits callback for payment status updates.


Order info being the order information passed when the FB.ui method is invoked.



For oauth and payments callback, pyramid_facebook uses custom events propagated throught Pyramid registry. Read pyramid documentation to learn how to configure an event listener.

class, request)

Event sent when a user accepts app authentication.

class, request)

Event sent when a user denies app authentication.

class, request)

Event sent when a user disputes an order.

class, request)

Event sent when a user got refunded for an order.

class, request)

Event sent when a user placed an item order.

class, request)

Event sent when a user placed an currency order.


class pyramid_facebook.lib.Base(context, request)

Base class for views and events


Route context which can be of 2 types:


Request object for this route.

pyramid_facebook.lib.encrypt_signed_request(secret_key, data)

Encrypts data the way facebook does for permit testing. Adds algorithm key to dict.

  • secret_key – Facebook application’ secret key.
  • data – a dictionary of data to sign.

Signed request as defined by Facebook documentation

pyramid_facebook.lib.headers_predicate(*header_names, **headers)

Custom predicate which check that header_names and headers name/value pairs are in request.headers.


Custom predicate which checks if a parameter is present with possible values being one in list values.

Parameters:params – A dictionary structured as dict(param_name=(value1, value2))
pyramid_facebook.lib.request_params_predicate(*required_param_keys, **required_params)

Custom predicates to check if required parameter are in request parameters. Read custom route predicates for more info:

# /example?param1&param2=321
    custom_predicates=[request_params_predicate('param1', param2=321)]