Bike, Walk, Run

For developers building fitness apps, Facebook provides common fitness.bikes, fitness.walksand fitness.runs actions.
These actions support the following fitness common objects:
  • The course object. You run, bike or walk a course.
  • The unit object. Fitness common objects can reference a developer defined fitness unit of measure (e.g. NikeFuel).
This action and associated object types are automatically added to the App Dashboard when you use the action for the first time.
This document covers the following topics:

Code Samples

You can find platform-specific code samples on how to create, read, update, or delete these actions in the following API Reference Guides:

Fitness Action Lifetime

Fitness actions allow you to create an story that's ongoing. That is, you can publish a story about an event that's taking place, updating it as progress is made and when the event completes. If this story is seen on a person's news feed or timeline the text is different than for past events. When that event is complete, the text will change to reflect that it's a completed event.
In order to create an ongoing event, you should:
  1. Create a unique course object for this action.
  2. Publish a single action with start_time property set, but without the end_time property set. Save the ID that's returned, since you will need it later to update the action.
  3. If there's a change in the progress of the event, update the object and then update the action ID.
  4. In order to end an event, set the end_time property on the action.
Fitness actions can also be set to expire. You can use the expires_in property to specify how long after the start_time that the event will automatically end.

Live Text

live_text is a unique feature to Common Fitness Actions that will render additional developer-specified text in the story while a fitness action is in progress. A common usage for live_text is a call to action to friends to encourage the person while his/her activity is in-progress. Developers configure the content of the live_text in the course object. See Submission Criteria for information on what's allowed and not allowed in live_text.

Handling Courses

This common object type enables developers to provide information specific to a course ran, biked, walked by a user.
A unique course URL is required for each run, bike, walk published for a user.
Custom Open Graph actions may publish common Course objects, but the custom Open Graph actions do not qualify for Fitness specific News Feed and Timeline stories and aggregations.
When specifying the fitness:distance metrics and properties on the fitness.course object, specify the quantity unit in the metric that the user would expect to see in the resulting story. For example, specify km if you want the story to include kilometers in the text, or alternatively, specify mi if the user would expect to see miles.
An example course object:
<head>
  <!-- Standard Open Graph object properties -->
  <meta property="fb:app_id"      content="YOUR_APP_ID" />
  <meta property="og:type"        content="some.type" />
  <meta property="og:url"         content="SOME_URL" />
  <meta property="og:title"       content="Some title" />
  <meta property="og:description" content="Some description" />
  <meta property="og:image"       content="SOME_IMAGE_URL" />

  <!-- Other Open Graph properties -->

  <!-- First ActivityDataPoint -->
  <meta property="fitness:metrics:location:latitude"  content="37.416382" />
  <meta property="fitness:metrics:location:longitude" content="-122.152659" />
  <meta property="fitness:metrics:location:altitude"  content="42" />
  <meta property="fitness:metrics:timestamp" content="2011-01-26T00:00" />
  <meta property="fitness:metrics:distance:value" content="0" />
  <meta property="fitness:metrics:distance:units" content="mi" />
  <meta property="fitness:metrics:pace:value" content="0" />
  <meta property="fitness:metrics:pace:units" content="s/m" />
  <meta property="fitness:metrics:calories" content="0" />
  <meta property="fitness:metrics:custom_quantity:value" content="0" />
  <meta property="fitness:metrics:custom_quantity:units" content="SOME_UNIT_URL" />

  <!-- Second ActivityDataPoint -->
  <meta property="fitness:metrics:location:latitude"  content="37.442564" />
  <meta property="fitness:metrics:location:longitude" content="-122.164879" />
  <meta property="fitness:metrics:location:altitude"  content="50" />
  <meta property="fitness:metrics:timestamp" content="2011-01-26T01:00" />
  <meta property="fitness:metrics:distance:value" content="2.3" />
  <meta property="fitness:metrics:distance:units" content="mi" />
  <meta property="fitness:metrics:pace:value" content="0.5" />
  <meta property="fitness:metrics:pace:units" content="s/m" />
  <meta property="fitness:metrics:calories" content="326" />
  <meta property="fitness:metrics:custom_quantity:value" content="486" />
  <meta property="fitness:metrics:custom_quantity:units" content="SOME_UNIT_URL" />
</head>
Notice the use of the ActivityDataPoint above. The ActivityDataPoint complex type is for Fitness common objects that contain a time-series data of location, distance, pace, steps, calories, and a developer defined unit of measure. Course objects will generally be made up of a large number of these types.
You should only include an ActivityDataPoint for every 30 seconds of activity.

Handling Large Course Objects