Fitbit

Owned by Former user (Deleted)
Last updated: Nov 28, 2023 by Sadie Friday

 

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.

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

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

Data fields (API version 1.2) 

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