Compartir contenido multimedia

Los álbumes que crea tu app se pueden compartir entre usuarios, con opciones para permitir que estos comenten o agreguen sus propios elementos multimedia al álbum.

Para compartir un álbum a través de la API de la Biblioteca de Google Fotos, tu app debe hacer lo siguiente:

1. Crea un álbum en nombre de un usuario.
2. Configura ese álbum como compartido.

Nota: Antes de compartir un álbum, obtén el consentimiento explícito del usuario y asegúrate de seguir los lineamientos de UX.

Alcance de la autenticación obligatorio

Para compartir contenido, tu app debe solicitar el alcance de autorización de photoslibrary.sharing.

Compartir un álbum

Antes de compartir un álbum, ten en cuenta las siguientes consideraciones:

• Tu app solo puede compartir los álbumes que creó. La tuya no puede compartir álbumes creados por otras apps, como Google Fotos.
• Cuando tu app comparte un álbum a través de la API de Library, se genera una URL para compartir que cualquier persona puede usar para acceder al álbum.
• En el caso de los álbumes compartidos a través de la API, el propietario del álbum puede desactivar el uso compartido de vínculos o dejar de compartir el álbum en la app de Google Fotos, lo que podría impedir que tu app se una a usuarios nuevos.

Para compartir un álbum, sigue estos pasos:

1. Sigue los lineamientos de UX y obtén el consentimiento explícito del usuario para crear un álbum compartido.
2. Crea el álbum y graba su albumId. Si ya creaste el álbum, puedes recuperar su albumId enumerando los álbumes del usuario.
3. Llama a albums.share con el elemento albumId relevante, junto con las opciones para compartir que desees configurar.
4. Registra el valor shareToken en la respuesta. El token para compartir es un identificador de un álbum compartido que se puede usar con diferentes cuentas de usuario.
5. Ahora otro usuario puede autenticarse con tu app y, luego, join, abandonar o recuperar los detalles del álbum compartido con su shareToken.

Opciones para compartir

Cuando se comparte un álbum, se pueden configurar las siguientes opciones mediante el parámetro sharedAlbumOptions. Si las opciones no se establecen de forma explícita, se usan los valores predeterminados.

Propiedad	Valor predeterminado	Descripción
isCollaborative	false	Establece si otros usuarios de Google Fotos pueden agregar contenido al álbum compartido.
isCommentable	false	Establece si otros usuarios de Google Fotos pueden comentar el álbum compartido.

Ejemplo de solicitud

En la siguiente solicitud, se comparte un álbum llamando a albums.share con opciones. Se muestra una propiedad shareInfo en la respuesta que describe las propiedades de uso compartido del álbum.

REST

Este es un encabezado de la solicitud POST para compartir un álbum:

POST https://photoslibrary.googleapis.com/v1/albums/album-id:share
Content-type: application/json
Authorization: Bearer oauth2-token

En el cuerpo de la solicitud, especifica las opciones para compartir.

{
  "sharedAlbumOptions": {
    "isCollaborative": "true",
    "isCommentable": "true"
  }
}

Esta solicitud muestra la siguiente respuesta:

{
  "shareInfo": {
    "sharedAlbumOptions": {
      "isCollaborative": "true",
      "isCommentable": "true"
    },
    "shareableUrl": "shareable-url",
    "shareToken": "share-token",
    "isJoinable": "true-if-users-can-join-album",
    "isJoined": "true-if-user-is-joined-to-album",
    "isOwned": "true-if-user-owns-album"
  }
}

Java

try {

  SharedAlbumOptions options =
          // Set the options for the album you want to share
          SharedAlbumOptions.newBuilder()
          .setIsCollaborative(true)
          .setIsCommentable(true)
          .build();
  ShareAlbumResponse response = photosLibraryClient.shareAlbum(albumId, options);

  // The response contains the shareInfo object, a url, and a token for sharing
  ShareInfo info = response.getShareInfo();
  // Link to the shared album
  String url = info.getShareableUrl();
  String shareToken = info
  // The share token which other users of your app can use to join the album you shared
      .getShareToken();
  SharedAlbumOptions sharedOptions = info
      // The options set when sharing this album
      .getSharedAlbumOptions();

} catch (ApiException e) {
  // Handle error
}

PHP

// Set the options for the album you want to share
$options = new SharedAlbumOptions();
$options->setIsCollaborative(true);
$options->setIsCommentable(true);
try {
    $response = $photosLibraryClient->shareAlbum($albumId, ['sharedAlbumOptions' => $options]);
    // The response contains the shareInfo object, a url, and a token for sharing
    $shareInfo = $response->getShareInfo();
    // Link to the shared album
    $url = $shareInfo->getShareableUrl();
    // The share token which other users of your app can use to join the album you shared
    $shareToken = $shareInfo->getShareToken();
    // The options set when sharing this album
    $sharedOptions = $shareInfo->getSharedAlbumOptions();
} catch (\Google\ApiCore\ApiException $e) {
    // Handle error
}

Propiedades de álbumes compartidos

En el caso de los álbumes que la app creó y compartió, todas las respuestas que muestran un objeto album incluyen una propiedad adicional, shareInfo. Esta propiedad se muestra cuando se comparte, enumera o retrieving álbumes.

En la siguiente tabla, se enumeran las propiedades de shareInfo:

Propiedades
sharedAlbumOptions	Opciones que describen si alguien puede agregar elementos multimedia o comentar un álbum compartido.
shareableUrl	Un vínculo al álbum compartido de Google Fotos. Cualquier persona que tenga el vínculo puede ver el contenido del álbum, por lo que se debe tratar con cuidado. El campo shareableUrl solo se muestra si el álbum tiene activado el uso compartido de vínculos. Si un usuario ya se unió a un álbum que no se compartió mediante un vínculo, puede usar el productUrl del álbum para acceder a él. Una shareableUrl se invalida si el propietario desactiva el uso compartido de vínculos en la app de Google Fotos o si el álbum se deja de compartir.
shareToken	Un token que se usa para join, abandonar o recuperar los detalles de un álbum compartido en nombre de un usuario que no es el propietario. Una shareToken se invalida si el propietario desactiva el uso compartido de vínculos en la app de Google Fotos o si el álbum se deja de compartir.
isJoinable	True si algún usuario puede unirse al álbum.
isJoined	True si el usuario se unió al álbum. Esto siempre es así para el propietario del álbum.
isOwned	True si el usuario es propietario del álbum

Precaución: Cualquier persona que tenga el shareableUrl de un álbum podrá ver su contenido.

Cómo dejar de compartir un álbum

Para dejar de compartir un álbum que tu app compartió anteriormente, llama a albums.unshare con el albumId del álbum.

Además de que el álbum ya no se comparta, ocurrirá lo siguiente:

• Todos los usuarios que no sean propietarios perderán el acceso al álbum. Esto incluye a las personas que compartieron el álbum de forma específica con ellos mediante la app de Google Fotos.
• Se quitará del álbum todo el contenido que hayan agregado los usuarios que no sean propietarios.
• Si un usuario agregó previamente el contenido del álbum a su biblioteca, ese contenido se conservará en su biblioteca.
• Se invalidarán el token y la URL para compartir del álbum.

Ejemplo de solicitud

REST

Este es un encabezado de la solicitud POST para dejar de compartir un álbum:

POST https://photoslibrary.googleapis.com/v1/albums/album-id:unshare
Content-type: application/json
Authorization: Bearer oauth2-token

El cuerpo de la solicitud debe estar vacío.

Si la solicitud tuvo éxito, muestra una respuesta vacía con un código de estado de éxito HTTP. Si la solicitud no tuvo éxito, muestra un código de estado de error de HTTP con un mensaje de error.

Java

try {
  // If this call is not successful, an exception is raised
  photosLibraryClient.unshareAlbum(albumId);
} catch (ApiException e) {
  // Handle error
}

PHP

try {
    // Mark the album as private and no longer shared
    // If this call is not successful, an exception is raised
    $photosLibraryClient->unshareAlbum($albumId);
} catch (\Google\ApiCore\ApiException $e) {
    // Handle error
}

Cómo recuperar álbumes compartidos y tokens para compartir

Cuando la app comparte un álbum, se muestran los detalles de un álbum compartido, incluido el token para compartir. También puedes recuperar esos detalles después de las siguientes maneras.

Si el usuario que está conectado a tu app es el propietario o está unido al álbum, haz lo siguiente:

• Con albums.get usando el albumId relevante.
• Con albums.list, si hay elementos multimedia en el álbum
• Con sharedAlbums.list, que muestra todos los álbumes compartidos a los que el usuario se unió o es de su propiedad. Para recuperar solo los álbumes que creó tu app, usa el parámetro excludeNonAppCreatedData.
• Con sharedAlbums.get mediante un token para compartir

Si el usuario que está conectado actualmente a tu app no se unió al álbum, puedes recuperar los detalles de un álbum compartido con sharedAlbums.get usando un token para compartir válido.

Ejemplo de solicitud

REST

A continuación, se incluye una solicitud para obtener un álbum a partir de su shareToken:

GET https://photoslibrary.googleapis.com/v1/sharedAlbums/share-token

Si la solicitud se realiza correctamente, se mostrarán los detalles compartidos de album .

Java

try {
  // Get a shared album from its share token
  Album sharedAlbum = photosLibraryClient.getSharedAlbum(shareToken);

  String id = sharedAlbum.getId();
  String title = sharedAlbum.getTitle();
  // ...

} catch (ApiException e) {
  // Handle error
}

PHP

try {
    // Get the album from a share token
    $album = $photosLibraryClient->getSharedAlbum($shareToken);

    // Get some properties of an album
    $productUrl = $album->getProductUrl();
    $title = $album->getTitle();

} catch (\Google\ApiCore\ApiException $e) {
    // Handle error
}

Cómo unirse a un álbum compartido

Tu app puede unirse a un álbum compartido en nombre de un usuario con el token para compartir del álbum. Para ello, se deben cumplir las siguientes condiciones:

• Tu app creó y compartió el álbum.
• El usuario al que deseas unirte al álbum no es su propietario. Es decir, el campo isOwned en los shareInfo del álbum es falso.
• El token para compartir es válido.
• El campo isJoinable del archivo shareInfo del álbum es verdadero.

Precaución: Después de que tu app comparte un álbum, el propietario puede desactivar el uso compartido de vínculos o dejar de compartirlo en la app de Google Fotos. Si esto sucede, se invalidará el token para compartir del álbum, su campo isJoinable será falso, y tu app no podrá unirse a él con usuarios.

REST

Este es un encabezado de solicitud POST para unirse a un álbum compartido:

POST https://photoslibrary.googleapis.com/v1/sharedAlbums:join
Content-type: application/json
Authorization: Bearer oauth2-token

En el cuerpo de la solicitud, especifica el shareToken.

{
  "shareToken": "share-token"
}

La solicitud POST muestra el album compartido al que se unió tu app en nombre del usuario.

Java

try {
  // Join the shared album using the share token obtained when sharing the album
  // If this call is not successful, an exception is raised
  JoinSharedAlbumResponse response = photosLibraryClient.joinSharedAlbum(shareToken);
  Album joinedAlbum = response.getAlbum();
} catch (ApiException e) {
  // Handle error
}

PHP

try {
    $response = $photosLibraryClient->joinSharedAlbum($shareToken);
    // Join the shared album using the share token obtained when sharing the album
    // If this call is not successful, an exception is raised
    $joinedAlbum = $response->getAlbum();
} catch (\Google\ApiCore\ApiException $e) {
    // Handle error
}

Cómo salir de un álbum compartido

Tu app puede abandonar un álbum compartido en nombre de un usuario mediante el token para compartir del álbum. Para ello, se deben cumplir las siguientes condiciones:

• Tu app creó y compartió el álbum.
• El usuario se unió al álbum en este momento. Es decir, el campo isJoined en el shareInfo del álbum es verdadero.
• El usuario conectado a tu aplicación no es el propietario del álbum. Es decir, el campo isOwned en el shareInfo del álbum es falso.

REST

Este es un encabezado de solicitud POST para salir de un álbum compartido:

POST https://photoslibrary.googleapis.com/v1/sharedAlbums:leave
Content-type: application/json
Authorization: Bearer oauth2-token

En el cuerpo de la solicitud, especifica el shareToken.

{
  "shareToken": "share-token"
}

Si la solicitud tuvo éxito, muestra una respuesta vacía con un código de estado de éxito HTTP. Si la solicitud no tuvo éxito, muestra un código de estado de error de HTTP con un mensaje de error.

Java

try {
  // Leave a shared album using its share token
  // If this call is not successful, an exception is raised
  photosLibraryClient.leaveSharedAlbum(shareToken);
} catch (ApiException e) {
  // Handle error
}

PHP

try {
    // Leave the shared album using the share token obtained when sharing the album
    // If this call is not successful, an exception is raised
    $photosLibraryClient->leaveSharedAlbum($shareToken);
} catch (\Google\ApiCore\ApiException $e) {
    // Handle error
}

Propiedades de los elementos multimedia compartidos

Los elementos multimedia que pertenecen a álbumes compartidos por tu app contienen una propiedad adicional, contributorInfo. Esta propiedad solo se incluye cuando se enumera el contenido de un álbum compartido.

La propiedad contributorInfo incluye el nombre del usuario que agregó el elemento multimedia al álbum y una URL base a su imagen de perfil.

Por ejemplo:

{
  "id: "media-item-id",
  ...,
  "mediaMetadata": {
    ...
  }
  "contributorInfo": {
    "profilePictureBaseUrl": "profile-picture-base-url_use-only-with-parameters",
    "displayName": "name-of-user"
  }
}

Nota: Solo se muestra la propiedad contributorInfo si el usuario otorgó acceso al alcance photoslibrary.sharing.