pyramid_facebook¶

Overview¶

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

Installation¶

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

$ pip install pyramid_facebook

Setup¶

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 __init__.py:
```
config = Configurator(.....)
config.include('pyramid_facebook')
```
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
```
Create a Facebook application on https://developers.facebook.com/apps
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:
```
[app:myapp]

facebook.app_id = 123456789
facebook.secret_key = 5fbf6252b38eec5d7f8a6962c8a00556
facebook.namespace = myfacebookapp
facebook.scope = user_events
```
In the app settings on https://developers.facebook.com/apps, set callbak url to point to your server. when developing, it is handy to point your localhost:
```
http://127.0.0.1:6543/{facebook application namespace}/
```

Define your facebook canvas view:

from pyramid_facebook.canvas import facebook_canvas

@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')

Register event handlers on Oauth accept or deny by subscribing to OauthAccept and OauthDeny:

from pyramid.events import subscriber

from pyramid_facebook.events import OauthAccept, OauthDeny

@subscriber(OauthAccept)
def user_accept(context, request):
   ...
   pass

@subscriber(OauthDeny)
def user_deny(context, request):
   ...
   pass

Visit your app on http://apps.facebook.com/[facebook app namespace]
To get facebook credits running, set credits callback in your facebook application settings to point to http://yourserver.com/[facebook app namespace]/credits
Define your get item method using facebook_payments_get_items decorator.
Subscribe to payments update events:

Under The Hood¶

Decorators¶

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:

@facebook_canvas(renderer='canvas.mako')
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":   "http://hadriendavid.com/images/100dimonds.png",

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

Example:

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

Contexts¶

class pyramid_facebook.security.SignedRequestContext(request)¶

Security context for facebook signed request routes.

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

class pyramid_facebook.security.FacebookCreditsContext(request)¶

Context for facebook credits callback requests.

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

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

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

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

Events¶

Note

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 pyramid_facebook.events.OauthAccept(context, request)¶: Event sent when a user accepts app authentication.

class pyramid_facebook.events.OauthDeny(context, request)¶: Event sent when a user denies app authentication.

class pyramid_facebook.events.DisputedOrder(context, request)¶: Event sent when a user disputes an order.

class pyramid_facebook.events.RefundedOrder(context, request)¶: Event sent when a user got refunded for an order.

class pyramid_facebook.events.PlacedItemOrder(context, request)¶: Event sent when a user placed an item order.

class pyramid_facebook.events.EarnedCurrencyOrder(context, request)¶: Event sent when a user placed an currency order.

Lib¶

class pyramid_facebook.lib.Base(context, request)¶

Base class for views and events

context¶

Route context which can be of 2 types:

SignedRequestContext
FacebookCreditsContext

request¶: 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.

Parameters:	secret_key – Facebook application’ secret key. data – a dictionary of data to sign.
Returns:	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.

pyramid_facebook.lib.nor_predicate(**params)¶

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
config.add_route(
    'example',
    '/example',
    custom_predicates=[request_params_predicate('param1', param2=321)]
    )