Sessions

Sessions are a way for users to quickly and easily see a list of all the main activities they've done. They appear in the Google Fit app journal page. For example, a breathing session, a walk, a run, or a night's sleep are each examples of a session.

Sessions group datasets from a specific time period, that was collected during an activity. For example, if a user tracked when they started and finished a 3km run, a session could be created and all the fitness data that's within that time period (like steps, speed, distance) would be associated with that session.

Sessions themselves don't contain details about the activity. This is in the dataset. Sessions have these properties:

• A descriptive, friendly name (for example, "morning run")
• A description
• A unique identifier
• The type of activity it's capturing (for example, a run)

Benefits of using sessions

• Useful for users: Sessions help you organize activity data and workouts in a meaningful way to users. They can see all their activities for the day in Journal page in the Google Fit app.
• Consistent user experience: If your app or companion device allows activity tracking (where users can start and stop an activity), having sessions for these workouts lets users see their activity across both apps.
• More complete data: Google Fit also merges data from multiple sources to supplement and enrich your session information. This gives users a more complete picture of their activity.
• Leverage the Google Fit platform: If your users don't track their activity, or your app doesn't support tracking, you can still read sessions in Google Fit. You can query detailed or aggregate data from the fitness store and find available sessions, without needing to implement your own schema and storage.
• Increased user engagement: You can show your users available sessions and the apps that created them. Interacting with other fitness apps this way could increase your user engagement.

Getting user authorization for sessions

If you want to read or write sessions, then your app must get the user's permission. Access to sessions uses the same authorization scopes as data types, which you should request as follows:

    val fitnessOptions = FitnessOptions.builder()
        .accessActivitySessions(FitnessOptions.ACCESS_READ)
        .addDataType(DataType.TYPE_HEART_RATE_BPM, FitnessOptions.ACCESS_READ)
        .addDataType(DataType.TYPE_SPEED, FitnessOptions.ACCESS_READ)
        .addDataType(DataType.TYPE_LOCATION_SAMPLE, FitnessOptions.ACCESS_READ)
        .build()

Using sessions

How datasets and segments interact with sessions

In Google Fit:

• A dataset represents a set of data points from a particular data source over a specific time period. Datasets can be inserted on their own. But if you're creating a session, it might be easier to create the session and its datasets together.
• A segment groups the datasets in a session by the exact activity the user was doing in the session. For example, if the user tracks a 30 minute run (the session) but walked for a little while during this, this could be broken up into segments. There would be a segment for the run, then the walking break, then the run again.

Figure 1 shows a time interval in the fitness store during which apps A, B, and C have inserted some datasets and sessions:

• App A inserted datasets A1 and A2 together with Session 1, and A3 independently of any sessions.
• App B inserted datasets B1 and B2 together with Session 2.
• App C inserted dataset C1 independently of any sessions.

When reading session data from the fitness store, all fitness data that falls within the time interval of a session is automatically associated with that session, even if you insert the data after creating the session, or create a session after data has been passively tracked. For example, a query for fitness data from Session 1 would return:

• Dataset A1
• Dataset A2
• The portion of dataset A3 between t1 and t2
• The portion of dataset C1 between t1 and t2

You can tell which app inserted each session and dataset.

Creating sessions

Sessions can be created in a few different ways:

• Your app can actively create a session in either
  • in real time when a user actively tracks an activity on a device (Android only), or
  • by manually inserting it.
• When a user manually adds a workout or activity in the Google Fit app.

When to create a session

Are you adding sleep data?

• Yes - Create a session and manually insert this into the fitness store. For example, inserting a sleep session. This is because users with sleep-tracking apps or devices won't interact with devices to start and stop their sleep activity (this is tracked passively).
• No - Does your app let users start and stop activities?
  • No - Don’t create a session. Only add datasets from your app.
  • Yes - With the Android API, create a session in real-time if users track their activity, or manually. With the REST API, create a session and manually insert this into the fitness store.
  • Can your app detect when a user is doing different activities on a more detailed level (for example, walking vs running)?
    • Yes - Add segments.
    • No - Only add datasets. Ignore segments for now, and let Google Fit passively create these.

Reading sessions

Your app can read sessions in a few ways:

• Look for a specific session it created/inserted by
  • Name or
  • ID
• Look for all the sessions it created/inserted, by time period
• Look for all available sessions created by all apps (including Google Fit) by time period

Learn which sources created a session

You can show your users which app or device created each of their sessions. Each session has an associated data source, which has information about the app or device that collected or transformed the data.