Purchasing & General Information
Fitbits are watches/wristbands that have the capability of tracking steps, heart rate, mvpa or intraday data, and sleep. For each, you can choose to setup collect time series data for each of these activities. For pricing and other helpful information visit: https://www.fitbit.com/home
Those purchasing Fitbit for research can receive a 20% discount! To move forward with an order, please complete the Fitbit Research Application and Research Order Form. The Fitbit Order Management Team will contact you within 2 business days of these submissions. If you have any additional questions, please reach out to Tim Schmidt, Business Development- Fitbit Health Solutions, at tschmidt@fitbit.com.
Authorization
To authorize Fitbit devices with Way to Health, you must include a Device Authorization step in your Enrollment steps. Once configured, the device authorization occurs when participants will enroll (first image). They will need to enter their Fitbit credentials into Way to Health when the modal pops up (second image). Then participants will need to allow Way to Health to receive data from Fitbit and can check-off what data we receive (third image).
Incoming Data
First, you should ensure there is proper configuration on the event schedule. A daily event should be created to track step, heart, or sleep data (if you are collecting more than one, you will need a daily event for each type of data). This is done by create a "Collect Data" event that runs from 12am - 11:59am the same day. The event should repeat for the duration of the intervention (e.g. 180 times for a 6 month intervention).
With this configuration, the data will come in as follows:
- Way to Health runs a daily process everyday just after midnight to collect all synced Fitbit data, regardless of whether a participant syncs. If there is no data, a value of 0 is retrieved. . We first check each participant's device's last-sync-time and query Fitbit's API for all new data up to that point. If a participant has not synced their device we will not store any data for that day (until they have synced at which point we will backfill).
- Way to Health runs any logic configured on the Collect Data event approximately 4 hours later. This is 4 AM EST. An example of logic is the evaluation of incoming data against a participant's target or goal (See screenshot below). Immediately following evaluation of the target is a message that is triggered that includes the step count for the day and whether or not the participant met their goal.*
- W2H also queries Fitbit's servers every hour. If a participant syncs their app during the day, WTH will receive it within the hour.
*If the message is sent via text message, the message will go out at 4 AM EST. In most cases, the study team should configure participant messaging windows to only be sent between certain hours of the day. For example, the participant only can receive messages from 8am-10pm. WTH will queue and hold the message to be sent later in the morning in those cases. If you want to include the data and participant goal variables in messaging, your only option is to build this messaging on the Collect Data event itself. Those variables are not currently available on "Add Logic" events. This is a current limitation of the platform, which we hope to address soon.
...
We recommend participants sync their device at least once a day at the end of the day. That way we can collect the highest step count from participants for that day. Most Fitbit devices record minute-by-minute data for seven days (Fitbit Alta records minute-by-minute data for five days. Fitbit devices can store daily totals for up to 30 days so if participants wait a few days to sync, W2H will still be able to capture the missing data.
Step Data (Updated 2/20)
goal_steps (migration to rename fitbit_goal to goal_steps)
goal_calories_out
goal_floors
goal_distance
calories_out
calories_bmr
marginal_calories
activity_calories
elevation
floors
...
- activity_name
- log_type
- source_type
- source_name
- distance (?miles)
- speed (?mph)
- distance_unit (probably applies to above two fields, confirm its mile even though API example uses kilometers)
- duration (seconds)
- active_duration
- calories
- steps
- start_time (store this as the as_of for the form submission)
- last_modified
- manual_step_value (boolean)
- manual_distance_value (boolean)
- manual_calorie_value (boolean)
- average_heart_rate
- heart_rate_minutes_out_of_range
- heart_rate_minutes_fat_burn
- heart_rate_minutes_cardio
- heart_rate_minutes_cardio
- Confirm if below are consistent across activities
- minutes_sedentary
- minutes_lightly_active
- minutes_fairly_active
- minutes_very_active
- activity_id
- activity_parent_id
- calories
- description
- distance
- duration
- has_start_time
- is_favorite
- log_id (could potentially be used in combination with option a)
- name
- start_time
- steps
Sleep data
We will soon be upgrading our Fitbit Sleep API integration to use version 1.2 since version 1 has been deprecated (https://dev.fitbit.com/build/reference/web-api/sleep/#version-1)
Data fields (API version 1)
start_time: The time the sleep period started
end_time: The time the sleep period ended
minutes_to_fall_asleep: Minutes in bed spent awake prior to first sleep cycle
minutes_asleep: Total minutes spent in a sleep stage during the sleep period
minutes_awake: Total minutes spent awake during the sleep period
minutes_after_wakeup: Minutes in bed spent awake after last sleep cycle
minutes_in_bed: Total Minutes spent in bed, this is equal to the duration of the sleep period
awake_count: How many sleep cycles were spent 'awake' during the sleep period
awake_duration: Total time spent in the 'awake' stage during the sleep period
restless_count: How many sleep cycles were spent in the 'restless' stage during the sleep period
restless_duration: Total time spent in the 'restless' stage during the sleep period
efficiency: An arbitrary number fitbit calculates using the following formula: time asleep / (total time in bed - time to fall asleep).
Will probably be removed at some point since fitbit deprecated this fieldmain_sleep: A true/false value: true if fitbit considers this sleep period the main sleep for that person (one main sleep per day)
...
start_time: The time the sleep period started
end_time: The time the sleep period ended
minutes_to_fall_asleep: Minutes in bed spent awake prior to first sleep cycle
minutes_asleep: Total minutes spent in a sleep stage during the sleep period
minutes_awake: Total minutes spent awake during the sleep period
minutes_after_wakeup: Minutes in bed spent awake after last sleep cycle
minutes_in_bed: Total Minutes spent in bed, this is equal to the duration of the sleep period
efficiency: An arbitrary number fitbit calculates using the following formula: time asleep / (total time in bed - time to fall asleep)
main_sleep: A true/false value: true if fitbit considers this sleep period the main sleep for that person (one main sleep per day)
- type: value of either classic or stages (see Fitbit Sleep API docs for more detail)
- classic fields
awake_count: How many sleep cycles were spent in the 'awake' level during the sleep period
awake_duration: Total time (minutes) spent in the 'awake' level during the sleep period
restless_count: How many sleep cycles were spent in the 'restless' level during the sleep period
restless_duration: Total time (minutes) spent in the 'restless' level during the sleep period
- asleep_count: How many sleep cycles were spent n the 'asleep' level during the sleep period
- asleep_duration: Total time (minutes) spent in the 'asleep' level during the sleep period
- stages fields
wake_count: How many sleep cycles were spent in the 'wake' level during the sleep period
wake_duration: Total time (minutes) spent in the 'wake' level during the sleep period
light_count: How many sleep cycles were spent in the 'light' level during the sleep period
light_duration: Total time (minutes) spent in the 'light' level during the sleep period
- deep_count: How many sleep cycles were spent in the 'deep' level during the sleep period
- deep_duration: Total time (minutes) spent in the 'deep' level during the sleep period
- rem_count: How many sleep cycles were spent in the 'rem' level during the sleep period
- rem_duration: Total time (minutes) spent in the 'rem' level during the sleep period
- classic fields
...