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).
Note: participants should only have one tracker device associated with the Fitbit account that they authorize to share data with W2H. Relatedly, they should not enable MobileTrack, which tracks steps from their phone, in addition to their Fitbit device, as it can cause issues with step counts being recorded correctly in the W2H system.
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 https://waytohealth.atlassian.net/wiki/spaces/WTHST/pages/21496294/%27Collect+Data%27+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. 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.
MVPA (Moderate to Vigorous Physical Activity)
For Fitbit, W2H can calculate a daily MVPA value. MVPA uses a validated algorithm that any minute with a rate of 100 steps or more is counted as moderate to vigorous physical activity. Those minutes are added for the 24-hour period to give you a single data point of MVPA minutes for that day.
Here are some references we used to determine that 100 steps per minutes is MVPA:
Data Syncing
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.
Pausing Data Collection
We added a “Paused” status to devices in September of 2023. When looking at the configuration of a Fitbit device in the participant profile/devices tab, there will be a blue button that says Pause Data Collection. When this is clicked, W2H will not try to pull down data for that device. When it is unpaused (by clicking Resume Data Collection) the data for the period during which it was paused will backfill. That’s all this feature does - stops data from flowing into W2H until such a time as we turn the tap back on.
(Updated 2/20)
Activity Data (Updated 2/20)
Biking and Running
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
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 field
main_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
Notes:
The timestamp we use for sleep data is equivalent to the end_time data field. This matches with the method fitbit uses to attach sleep data to a date. The date of a sleep period is the date the user woke up on.
Fitbit requires users to be at least 13 years of age to have a fitbit account.
W2H stops pulling in Fitbit data when participants are marked as ‘finished’, ‘unenrolled’, ‘declined’, etc.