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](https://developers.google.com/fit/overview#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](https://developers.google.com/fit/datatypes#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`](https://developers.google.com/android/reference/com/google/android/gms/fitness/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.

> [!NOTE]
> **Note:** To access sleep sessions, use `.accessSleepSessions()`.

### 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](https://developers.google.com/fit/android/using-sessions) to:

- Create sessions in real time
- Insert sessions in the [fitness store](https://developers.google.com/fit/overview#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](https://developers.google.com/fit/rest/v1/using-sessions) to:

- Create sessions in real time
- Insert sessions in the [fitness store](https://developers.google.com/fit/overview#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.

![](https://developers.google.com/static/fit/images/timeline.png) **Figure 1**: Different apps add sessions and datasets to the \[fitness store\].

<br />

Figure 1 shows a time interval in the [fitness store](https://developers.google.com/fit/overview#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](https://developers.google.com/fit/overview#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

> [!NOTE]
> **Note:** To create a session, your app needs the https://www.googleapis.com/auth/fitness.activity.write [OAuth scope
> permission](https://developers.google.com/identity/protocols/oauth2/scopes).

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](https://developers.google.com/fit/scenarios/write-sleep-data). 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](https://developers.google.com/fit/android/using-sessions#create_sessions_in_real_time) if users track their activity, or [manually](https://developers.google.com/fit/android/using-sessions#insert_sessions_in_the_fitness_store). With the REST API, [create a session and manually insert this into the fitness store](https://developers.google.com/fit/rest/v1/using-sessions).
  - 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](https://developers.google.com/fit/sessions#how_datasets_and_segments_interact_with_sessions). Ignore segments for now, and let Google Fit passively create these.

## Reading sessions

> [!NOTE]
> **Note:** To read sessions with the REST API, your app needs the https://www.googleapis.com/auth/fitness.activity.read [OAuth scope
> permission](https://developers.google.com/identity/protocols/oauth2/scopes). To read sessions with the Sessions API for Android, [specify the read constant in
> the FitnessOptions
> class](https://developers.google.com/android/reference/com/google/android/gms/fitness/FitnessOptions).

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`](https://developers.google.com/android/reference/com/google/android/gms/fitness/data/DataSource#public-string-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](https://developer.android.com/reference/android/content/pm/PackageItemIn%0Afo) to help users identify them.

> [!NOTE]
> **Note:** You can [show generic
> icons](https://developer.android.com/studio/write/image-asset-studio) for other fitness apps that aren't installed on the user's device.

You can also fire an
[intent](https://developer.android.com/guide/components/intents-filters) to
[launch other apps](https://developer.android.com/training/app-links/deep-%0Alinking) 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](https://developers.google.com/fit/android/data-attribution).

### REST

To get the package name of the Android app that created sessions, use the
[`session.application`](https://developers.google.com/static/fit/rest/v1/reference/users/sessions/list#session.application) property. For sessions that were created using the
REST API, use the [`session.name`](https://developers.google.com/fit/rest/v1/reference/users/sessions/list#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](https://developers.google.com/fit/rest/v1/attribution).