Subscribing to Fitbit Events

Intro

Fitbit's API provides a callback mechanism via HTTP(s) to alert your web-based application that there is new data available you should grab. Fitbit.NET contains helper methods to:

1. Establish a subscription for each user on Fitbit's servers
2. Parse the responses from Fitbit's servers to yours
3. List / Remove subscriptions for users on Fitbit's servers.

You should familiarize yourself with the general flow of this part of the API. Like most of the API, it requires auth token access for the user you are trying to set up with subscriptions. https://wiki.fitbit.com/display/API/Fitbit+Subscriptions+API

Getting Started

Head over to dev.fitbit.com, sign in, and go to "Manage my Apps" to open the configuration for your Fitbit "App", select it, and then navigate to "Edit Application Settings".

• Now's a good time to double check this app is set up as a "Browser" type app.

At the bottom, there's a field for adding subscriber endpoints. You just need one. Make sure it is a url that will resolve to your web server, and is publicly available so that Fitbit's servers don't get a 404. This is hard to debug locally unless you can open your local computer to the www and through all firewalls.

Set it as: default:true, url: www.yourserver.com/Your/DataEndpoint, type:xml, version: 1, subscriber (none, or "1").

Implementing the Receiver Endpoint

The following is an ASP.NET MVC endpoint implementation listening for updates:

[AcceptVerbs(HttpVerbs.Post)]
public ActionResult SubscriptionData()
{
	SubscriptionManager subscriptionManager = new SubscriptionManager();
	List<UpdatedResource> updatedResources; //all the updated users and which resources

	using (var sr = new StreamReader(Request.InputStream))
	{
		string responseText = sr.ReadToEnd();
		//note, you can store the raw response from fitbit here if you like

		responseText = subscriptionManager.StripSignatureString(responseText);
		updatedResources = subscriptionManager.ProcessUpdateReponseBody(responseText);
	}

	foreach (UpdatedResource updatedResource in updatedResources)
	{
		//do something here with the updated resources fitbit is reporting
	
		//likely, you'll grab stored AuthToken/AuthSecret 
		// for a user and use FitbitClient class to get the latest resource type
	}
}

Alternatively, the following is a Web API endpoint signature. In the Fitbit application settings the "subscriber" will have the type "JSON body", everything else is the same.

public class FitbitSubscriptionController : ApiController
{
    // POST api/fitbitsubscription
    public HttpResponseMessage Post([FromBody] JArray updates)
    {
        // Your code here...
        return msg;
    }
}

Establishing a Subscription for a User

Now that there's a place for the subscription to go, you set up the user subscription much like any other Fitbit API request, using the FitbitClient class. You can set up either a specific type of data you'd like to get notified about, like activities:

FitbitClient fitbitClient = new FitbitClient(YOUR_CONSUMER_KEY, YOUR_CONSUMER_SECRET, userCredential.AuthToken, userCredential.AuthTokenSecret);

//the library will register a subscription called "123456789"-activities
fitbitClient.AddSubscription(APICollectionType.activities, "123456789");  //type and your user identifier

or, you can ask for all types of updates, including things manually entered in the fitbit portal by using the "user" level APICollectionType enum, like so:

FitbitClient fitbitClient = new FitbitClient(YOUR_CONSUMER_KEY, YOUR_CONSUMER_SECRET, userCredential.AuthToken, userCredential.AuthTokenSecret);

//the library will register a subscription called "123456789"-user
fitbitClient.AddSubscription(APICollectionType.user, "123456789");  //type and your user identifier

*note, if you request both the "user" and any other collection type, you will get duplicate requests. See the documentation for specifics on how responses are sent: https://wiki.fitbit.com/display/API/Fitbit+Subscriptions+API#FitbitSubscriptionsAPI-Addasubscription

Listing all Subscriptions

This will return all the active subscriptions for a particular user:

FitbitClient fitbitClient = new FitbitClient(YOUR_CONSUMER_KEY, YOUR_CONSUMER_SECRET, userCredential.AuthToken, userCredential.AuthTokenSecret);
List<ApiSubscription> apiSubscriptions = fitbitClient.GetSubscriptions();

Removing a Subscription

The following removes a subscription for a user:

FitbitClient fitbitClient = new FitbitClient(YOUR_CONSUMER_KEY, YOUR_CONSUMER_SECRET, userCredential.AuthToken, userCredential.AuthTokenSecret);
var apiSubscription = fitbitClient.RemoveSubscription(APICollectionType.activities, "123456789-activities");

*Note, as hinted above in the insert method, by default subscriptions are appended with the type at the end, so make sure to include it when you remove. If you first list what active subscriptions a user has, then you'll have it (like "123456789-activities") and just pass that value directly to remove.