Create and manage sessions

Sessions are at the heart of the Picker API, providing a secure and controlled way for users to select photos and videos from their Google Photos library. This guide outlines how to create, manage, and effectively poll sessions to enable seamless photo selection in your app.

Before you start

  • Configure your app: Enable the API and set up authentication. See Configure your app for detailed steps.
  • Understand the flow: Review get started with the Picker API for an overview of the entire photo selection process.
  • Review required authorization scopes: Working with sessions requires the photospicker.mediaitems.readonly scope. For more information on scopes, see Authorization scopes.

Session lifecycle

The Picker API provides methods to create, retrieve information about, and delete sessions. After authenticating your users, you can use sessions to manage the photo picking lifecycle.

  1. Create a session to enable a user to select media items.
  2. Poll the session to check when the user has finished selecting media items.
  3. List and retrieve the media items.
  4. Clean up the session by deleting it.

Create sessions

Create a session so your users can securely pick photos directly from their Google Photos app, and share them back to your application.

sessions.create generates a new session, returning a unique pickerUri that you can present to your users. The session remains active until either the user has successfully selected media items, or the session times out.

Session limits

Be aware of session limits. The Picker API enforces limits on the number of sessions you can create to ensure responsible usage and prevent abuse. Under normal circumstances, you're unlikely to reach these limits. However, you should track and clean up sessions proactively to avoid any issues.

Poll and monitor sessions

Once a session is created, periodically poll the sessions.get endpoint to get the status of a session. The mediaItemsSet property in the response returns true when the user has completed their selection.

Make sure to use efficient polling. The sessions.get response includes the pollingConfig object. Use the following fields to help you avoid unnecessary calls and create a smooth user experience:

  • pollInterval: optimal polling intervals
  • timeoutIn: timeout duration

See the Example polling flow for more details.

Delete and clean up sessions

sessions.delete removes a session, typically used for cleanup after the user has finished selecting media or if the session times out.

It's a best practice to delete sessions once the user has selected media items and your app has retrieved the media item bytes.

Example polling flow

This is an example of creating and polling a session. After first authenticating your user, create a new session.

  1. Create a session: Call sessions.create to initiate a new session and obtain the pickerUri.
  2. Present the pickerUri to the user: Display the URL or generate a QR code for the user to scan. Read an overview of the user's picking experience.
  3. Poll the session:
    1. Use the recommended pollInterval from pollingConfig.
    2. Check if mediaItemsSet is true.
      1. If true, proceed to list the selected media items.
      2. If false, continue polling until timeoutIn is reached.
    3. Handle timeouts and cancellations gracefully.
GET https://photoslibrary.googleapis.com/v1/sessions/{sessionId}

Here's an example response:

{
  "id": string,
  "pickerUri": string,
  "pollingConfig": {
    object (PollingConfig)
  },
  "mediaItemsSet": boolean
}

Present the pickerUri to the user, and then begin to poll the session.

Check the response for the following:

  • mediaItemsSet: true if the user has finished selecting media items
  • pollingConfig.pollInterval: recommended time to wait before the next poll
  • pollingConfig.timeoutIn: total time to wait before timing out

If mediaItemsSet is false and timeoutIn has not been reached, wait for pollInterval and then poll again.

If mediaItemsSet is true, proceed to list the selected media items.

If timeoutIn is reached, handle the timeout gracefully.