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:
- Crea un álbum en nombre de un usuario.
- Configura ese álbum como compartido.
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:
- Sigue los lineamientos de UX y obtén el consentimiento explícito del usuario para crear un álbum compartido.
- Crea el álbum y graba su
albumId
. Si ya creaste el álbum, puedes recuperar sualbumId
enumerando los álbumes del usuario. - Llama a
albums.share
con el elementoalbumId
relevante, junto con las opciones para compartir que desees configurar. - 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. - 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 Una |
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 |
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 |
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 elalbumId
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ámetroexcludeNonAppCreatedData
. - 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 losshareInfo
del álbum es falso. - El token para compartir es válido.
- El campo
isJoinable
del archivoshareInfo
del álbum es verdadero.
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 elshareInfo
del álbum es verdadero. - El usuario conectado a tu aplicación no es el propietario del álbum. Es decir, el campo
isOwned
en elshareInfo
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" } }