Bike, Walk, Run Actions

For developers building fitness apps, Facebook provides common fitness.bikes, fitness.walks and 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 your 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 enable people to create an story that's ongoing. Your app can publish a story about an event that's taking place, update it as progress is made and when the event completes.

If this story appears 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

If a fitness:metrics contains too many ActivityDataPoints, an object's URL may take too long to load. In these circumstances, please use pointers and move all of the ActivityDataPoints to the destination URL.

A source URL example:

<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 -->

  <!-- Pointer to ActivityDataPoint destination URL -->
  <link rel="opengraph" href="DESTINATION_URL_FOR_ACTIVITYDATAPOINTS" />
</head>

A destination URL example:

<!-- Special type for an Open Graph metadata object -->
<meta property="og:type" content="metadata" />

<!-- Pointer to the source URL -->
<link rel="origin" href="SOURCE_URL" />

<!-- 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" />

Units

The unit common object type enables developers to define a fitness unit of measure (e.g. NikeFuel) which can be referenced by Fitness common objects.

For example:

<head>
  <!-- Standard Open Graph object properties -->
  <meta property="fb:app_id"      content="SOME_APP_ID" />
  <meta property="og:type"        content="fitness.unit" />
  <meta property="og:url"         content="SOME_URL" />
  <meta property="og:title"       content="Some unit title" />
  <meta property="og:description" content="Some unit description" />
  <meta property="og:image"       content="SOME_UNIT_IMAGE_URL" />

  <!-- Developer defined fitness unit name -->
  <meta property="fitness:name" content="Fuel"/>
</head>

Submission Criteria

When you submit these actions for review, keep in mind the following:

  • Custom run, walk, or bike actions are no longer accepted. Please use the common actions.
  • Your object should include pace, geo-points, distance, and as many appropriate metrics available to produce the richest possible feed story.
  • Your app must be categorized under the Health & Fitness category. Learn how to edit your app details here.
  • You should set some checks to make sure that your user data remains within a normal range. For example, you do not want users to be able to post a story that they ran 10,000 miles in a single run.
  • Make sure to set or update an end_time or expires_in action property for your actions. More details here.
  • Use Explicit Sharing when a user wants to share their Fitness activity prominently on Facebook.
  • You should not include marketing messages in your object's fitness:live_text, e.g. "Sign up for FunRun America today! Click here!"
Good example
Bad example including marketing messages in the object

Find more information on the submission process here