Foursquare Apps Builder

A framework for building foursquare apps on AppEngine.

Registering with foursquare

Register your app at http://foursquare.com/oauth. Your application web site is

http://APPENGINE_APPLICATION_NAME.appspot.com

And your callback url is

https://APPENGINE_APPLICATION_NAME.appspot.com/oauth

Once you've registered, you'll get a client_id. You'll want to edit your app's settings to set up your app for push notifications and as a connected app.

Your push url is

http://APPENGINE_APPLICATION_NAME.appspot.com/checkin

System Config

First update /app.yaml and /config.py with the details for your appengine instance.

• app.yaml: You should only need to update the application name

• config.py: Read through the documentation and update fields as appropriate.

• foursquare_secrets_template.py: First, copy this file over to foursquare_secrets.py. That filename has been .gitignore'd so that you don't accidentally leak your secrets! Then, fill out the template with your actual client and push secrets.

Implementing an app

Create a new folder for your app's files. You can check out /menulette as an example. Your main class should extend the AbstractApp class found in in abstract_app.py. There are 4 primary actions the app can support.

checkinTaskQueue(self, authenticated_client, checkin_json)

• A user who has authorized your app has checked in. This runs inside AppEngine's task queue, and contains the check-in payload for you to process.

contentGet(self, client, content_info)

• A user is requesting to view content generated by the app. The content info is passed along to the app so it can render the appropriate page. The default implementation returns a 400 to the user.

appPost(self, client)

• This is for your app to handle any arbitrary POST request not already handled by the framework (i.e., all POSTs other than the ones from the foursquare Push API). The default implementation returns a 404.

appGet(self, client)

• This is for your app to handle any arbitrary GET request not already handled by the framework (i.e., all GETs other than those handled by contentGet). The default implementation returns a 404.

The client object passed for these calls is a Foursquare object from Mike Lewis's library: https://github.com/mLewisLogic/foursquare. For checkinTaskQueue, the client includes the user's access token. For all other calls you'll need to retrieve the access token you want to use via utils.fetchAccessToken(user_id) and set it via client.set_access_token(access_token).

There are a bunch of utility methods in both utils.py and abstract_app.py which should make common actions much easier.

Once you've extended AbstractApp and filled out the configuration files, you're good to go. Deploy your instance, and you should be all set!

Local development

It's easy to develop your app locally. Go to config.py and specify "local_dev": True and give the localhost url under 'local_server'. Then use the AppEngineLauncher to run your app locally and hit it with a fake check-in -- there's a sample payload in the testing directory. It's url-encoded, so you'll need to decode and re-encode to make edits. I use http://meyerweb.com/eric/tools/dencoder/ to do this.

You'll need to change the user ID field to your ID in order for the app to find your auth token in the datastore.

Once you've done that, you can push the data into your app via:

curl http://localhost:8090/checkin --data-urlencode checkin@test_checkin.txt

You probably don't want to make actual write requests from the app when in local dev mode -- makeContentInfo skips and logs for your convenience.