Sessions

Sessions represent a time interval during which users perform an activity. These can be traditional 'activities' like going for a run, or a bike ride, but also include things like a night of sleep or meditation session. Sessions help organize data and perform detailed or aggregate queries for a fitness activity.

Sessions, datasets, and apps

Sessions in Google Fit consist of a start time, an end time, a user-friendly name, a description, an activity type, and a unique identifier. Sessions don't contain data themselves. You can think of sessions as metadata objects with information that helps you query data from the fitness store later.

A dataset in Google Fit represents a set of data points from a particular data source. A dataset represents data at fixed time boundaries, as shown in Figure 1. More often, you will create sessions and datasets together, with the same time boundaries. But your app can insert datasets without session information when inserting nutrition data, continuous measurements (like continuous heart rate monitoring) or vitals/body measurements with a timestamp (like weight).

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 implicitly associated with that session, even if you insert the data after creating the session. 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 determine which app inserted each session and dataset.

Benefits of using sessions

Sessions help you organize workouts by easily adding time interval metadata to fitness data in the fitness store. Here are some reasons why your app should use sessions with Google Fit:

  • Users can see the sessions your app created in the Google Fit app journal.
  • You can also show other available sessions, along with the apps that created each of them, in the journal.
  • You don't need to implement your own metadata schema and storage.

Sessions help your app users see their activity in a clear format in the Google Fit journal. They can also increase user engagement with your app by interacting with other fitness apps. For example, another app can find sessions your app has created in the fitness store for a particular user. In their app, they can show your session details to that same user with your app name and icon. You can also find sessions created by other apps, including Google Fit, to display in your own app.

Creating and reading sessions

Android

The Sessions API lets you:

  • 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
  • Start another app to show session data
  • Receive an intent when any app starts a session

REST

The REST API lets you create sessions and retrieve sessions within a specific time interval. You can also read data from datasets that overlap with the time interval of a session. For more information, see Working with Sessions and Working with Datasets.

Data attribution in sessions

Android

Sessions let you obtain the package name of the app that created them using the getAppPackageName method. You can use this information in your app to show users which other apps inserted fitness sessions that are relevant to the context. You can show the icon for each of these apps to help users identify them, and you can fire an intent to launch these apps. Other apps can also fire an intent to launch your app to view details of sessions it created.

Apps may show generic icons for other fitness apps not installed on the device.

For more information, see Data Attribution.

REST

Sessions let you obtain the package name of the Android app that created them using the session.application property. For sessions that were created using the REST API, you can use the session.name property. You can use this information in your app to show users which other apps inserted fitness sessions that are relevant to the context. For more information, see Data Attribution.