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:

Android

Specify what type of session your app needs to access, using the appropriate methods from FitnessOptions. For example, to read sessions relating to running you might choose:

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

This example specifies that your app wants to access activity session metadata, and it also specifies the data types it wants to read within those sessions; the heart rate, speed and location data types are used in this example.

REST

Request scopes as follows:

  • Sessions with sleep activity types:
    • https://www.googleapis.com/auth/fitness.sleep.read
    • https://www.googleapis.com/auth/fitness.sleep.write
  • All other sessions:
    • https://www.googleapis.com/auth/fitness.activity.read
    • https://www.googleapis.com/auth/fitness.activity.write

Using sessions

Android

You can use the Sessions API to:

  • Create sessions in real time
  • Insert sessions in the fitness store
  • Insert activity segments to support pauses during workouts
  • Read sessions and datasets associated with them
  • Launch another app to show information about a session it created
  • Receive an intent when another app starts a session

REST

You can use the Sessions API to:

  • Create sessions in real time
  • Insert sessions in the fitness store
  • Insert activity segments to support pauses during workouts
  • Read sessions and datasets associated with them

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: Different apps add sessions and datasets to the [fitness store].

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.

Android

You can currently only get the package name of a session written by an Android client. To get the package name of the app that created a session, use the getAppPackageName method. You can use this information in your app to show users which other apps inserted fitness sessions. You can show the icon for each of these apps to help users identify them.

You can also fire an intent to launch other apps to show details of the sessions they created. Other apps can also fire an intent to launch your app.

Learn more about finding the source that created a session.

REST

To get the package name of the Android app that created sessions, use the session.application property. For sessions that were created using the REST API, use the session.name property instead. You can use this information in your app to show users which other apps inserted fitness sessions. You can show the icon for each of these apps to help users identify them.

Learn more about finding the source that created a session.