Los enriquecimientos permiten que tu aplicación controle la estructura y la presentación de las fotos dentro de un álbum en Google Fotos. Te permiten presentarle al usuario contexto adicional a través de anotaciones de texto o ubicación, y ordenar o agrupar imágenes que cuentan una historia en conjunto.
Alcance de la autorización requerido
Para agregar mejoras, se requiere al menos uno de los siguientes alcances:
photoslibrary.appendonly
photoslibrary.library
photoslibrary.sharing
Para cada alcance, la llamada a enrichAlbum
está restringida solo a los álbumes creados por la app.
Cuando se usa el alcance .sharing
, enrichAlbum
está restringido a circunstancias en las que el desarrollador actúa en nombre del propietario del álbum compartido.
Tipos de enriquecimiento
Google Fotos admite tres tipos de mejoras en los álbumes: texto, ubicaciones y mapas.
Enriquecimientos de texto
Un enriquecimiento de texto es una cadena de texto sin formato que se puede insertar para anotar el álbum.
Mejoras de ubicación
Un enriquecimiento de ubicación es un marcador y el nombre del lugar que se puede insertar para anotar una ubicación.
Mejoras de mapas
Un enriquecimiento de mapa es un mapa con un origen y un destino específicos que se pueden insertar en el álbum.
Posiciones
Para insertar elementos multimedia y mejoras del álbum, especifica la posición del álbum. Una posición es opcional para los elementos multimedia, pero se debe especificar para el enriquecimiento del álbum.
Solo se puede especificar una posición cuando creas un elemento multimedia o agregas mejoras. Los elementos multimedia existentes de un álbum no se pueden reorganizar, por lo que es importante establecer la posición de un elemento cuando lo agregues.
Inicio del álbum
Se puede agregar un elemento multimedia o de enriquecimiento al comienzo del álbum como posicionamiento absoluto.
Fin del álbum
Se puede agregar un elemento multimedia o de enriquecimiento al final del álbum como posicionamiento absoluto.
Relativo al elemento multimedia
Se puede agregar un elemento multimedia o de enriquecimiento en relación con un elemento multimedia a partir de su posición en el álbum.
Relativo al elemento de actualización
Se puede agregar un elemento multimedia o de enriquecimiento en relación con un elemento de enriquecimiento a partir de su posición en el álbum.
Agregando mejoras al álbum
Los enriquecimientos se agregan de a uno a la vez y deben agregarse a una posición en el álbum.
Para agregar mejoras a un álbum, llama a albums.addEnrichment
.
Si la solicitud se realiza correctamente, muestra el id
del elemento de actualización, que se puede usar para posicionar elementos multimedia o cualquier otro enriquecimiento.
REST
A continuación, se muestra una solicitud POST:
POST https://photoslibrary.googleapis.com/v1/albums/album-id:addEnrichment Content-type: application/json Authorization: Bearer oauth2-token request-body
El cuerpo de la solicitud consta del elemento de enriquecimiento y su posición:
{ "newEnrichmentItem": { enrichment-to-be-added }, "albumPosition": { position-of-enrichment }
A continuación, se muestra una respuesta de ejemplo:
{ "enrichmentItem": { "id": "enrichment-item-id", } }
Java
try { // Create the enrichment using the NewEnrichmentItemFactory helper NewEnrichmentItem newEnrichmentItem = NewEnrichmentItemFactory.createTextEnrichment(""); // Set the position of the enrichment within the album AlbumPosition albumPosition = AlbumPositionFactory.createFirstInAlbum(); // To add an enrichment, specify the album, the enrichment item, // and the position in the album where the enrichment is to be added AddEnrichmentToAlbumResponse response = photosLibraryClient .addEnrichmentToAlbum(albumId, newEnrichmentItem, albumPosition); // The response contains an EnrichmentItem // whose ID can be used to position media items or other enrichments EnrichmentItem enrichmentItem = response.getEnrichmentItem(); String itemId = enrichmentItem.getId(); } catch (ApiException e) { // Handle error }
PHP
// Create the enrichment item using the PhotosLibraryResourceFactory helper $newEnrichmentItem = PhotosLibraryResourceFactory::newEnrichmentItemWithText(""); // ... // Set the position of the enrichment within the album $position = new AlbumPosition(); // ... try { // To add an enrichment, specify the album, the enrichment item, // and the position in the album where the enrichment is to be added $response = $photosLibraryClient->addEnrichmentToAlbum($albumId, $newEnrichmentItem, $position); // The response contains an EnrichmentItem // whose ID can be used to position media items or other enrichments $enrichmentItem = $response->getEnrichmentItem(); $itemId = $enrichmentItem->getId(); } catch (\Google\ApiCore\ApiException $e) { // Handle error }
Enriquecimientos admitidos
Enriquecimientos de texto
Los enriquecimientos de texto contienen una sola cadena de texto (no más de 1,000 caracteres), como se muestra en el siguiente ejemplo:
REST
{ "text": "Text to be shown" }
Java
// Use the NewEnrichmentItemFactory helper to create a text enrichment item NewEnrichmentItem newEnrichmentItem = NewEnrichmentItemFactory.createTextEnrichment("text to be shown");
PHP
$newEnrichmentItem = PhotosLibraryResourceFactory::newEnrichmentItemWithText("text to be shown");
Mejoras de ubicación
Los enriquecimientos de ubicación consisten en un nombre de ubicación arbitrario y la posición de latitud y longitud. El locationName
tiene un límite de 500 caracteres.
REST
{ "location": { "locationName": "Australia", "latlng": { "latitude": "-21.197", "longitude": "95.821" } } }
Java
// Use the NewEnrichmentItemFactory helper to create a location enrichment // with the name, latitude, and longitude of the location NewEnrichmentItem newEnrichmentItem = NewEnrichmentItemFactory.createLocationEnrichment("Australia", -21.197, 95.821);
PHP
// Create a new location object and set the name, latitude, and longitude of the location $newLocation = new Location(); $newLocation->setLocationName("Australia"); $newLocation->setLatlng((new LatLng())->setLatitude(-21.197)->setLongitude(95.821)); $newEnrichmentItem = PhotosLibraryResourceFactory::newEnrichmentItemWithLocation($newLocation);
Mejoras de mapas
Los enriquecimientos de mapa muestran dos ubicaciones, cada una compuesta por un nombre y la latitud y longitud. Al igual que el enriquecimiento de ubicación, el locationName
dentro del origen y destination
se limita a 500 caracteres.
REST
{ "origin": { "locationName": "Australia", "latlng": { "latitude": "-21.197", "longitude": "95.821" } }, "destination": { "locationName": "San Francisco", "latlng": { "latitude": "37.757", "longitude": "122.507" } } }
Java
// Use the NewEnrichmentItemFactory helper to create a map enrichment item for // an origin and a destination location NewEnrichmentItem newEnrichmentItem = NewEnrichmentItemFactory.createMapEnrichment( "Australia", -21.197, 95.821, // origin "San Francisco", 37.757, 122.507 // destination );
PHP
// Create two new location objects to create a map enrichment item // for an origin and a destination location $locationAustralia = new Location(); $locationAustralia->setLocationName("Australia"); $locationAustralia->setLatlng((new LatLng())->setLatitude(-21.197)->setLongitude(95.821)); $locationSanFrancisco = new Location(); $locationSanFrancisco->setLocationName("San Francisco"); $locationSanFrancisco->setLatlng((new LatLng())->setLatitude(37.757)->setLongitude(122.507)); $newEnrichmentItem = PhotosLibraryResourceFactory::newEnrichmentItemWithMap($locationAustralia, $locationSanFrancisco);
Posicionamiento compatible
Inicio del álbum
La posición FIRST_IN_ALBUM
hace referencia al inicio del álbum. Los elementos que se encuentran aquí se muestran al usuario primero:
REST
{ "position": "FIRST_IN_ALBUM", }
Java
AlbumPosition albumPosition = AlbumPositionFactory.createFirstInAlbum();
PHP
$albumPosition = new AlbumPosition(); $albumPosition->setPosition(PositionType::FIRST_IN_ALBUM);
Fin del álbum
La posición LAST_IN_ALBUM
hace referencia al final del álbum. Los elementos que se encuentran aquí
se muestran al usuario por última vez.
REST
{ "position": "LAST_IN_ALBUM", }
Java
AlbumPosition albumPosition = AlbumPositionFactory.createLastInAlbum();
PHP
$albumPosition = new AlbumPosition(); $albumPosition->setPosition(PositionType::LAST_IN_ALBUM);
Relativo al elemento multimedia
Especificar la posición relativeMediaItem
hace referencia a una posición relativa a un elemento multimedia. Los elementos se agregarán después del elemento multimedia especificado.
REST
{ "position": "after-media-item", "relativeMediaItemId": "media-item-id" }
Java
AlbumPosition albumPosition = AlbumPositionFactory.createAfterMediaItem(mediaItemId);
PHP
$albumPosition = PhotosLibraryResourceFactory::albumPositionAfterMediaItem($mediaItemId);
Relativo al elemento de actualización
Especificar un relativeEnrichmentItemId
hace referencia a una posición relativa a un elemento de enriquecimiento. Los elementos se agregan después del elemento de actualización especificado.
REST
{ "position": "after-enrichment-item", "relativeEnrichmentItemId": "enrichment-item-id" }
Java
AlbumPosition albumPosition = AlbumPositionFactory.createAfterEnrichmentItem(enrichmentItemId);
PHP
$albumPosition = PhotosLibraryResourceFactory::albumPositionAfterEnrichmentItem($enrichmentItemId);
Modifica enriquecimientos
Por el momento, no hay forma de modificar los enriquecimientos. Sin embargo, una vez que se crea un enriquecimiento y se lo agrega a un álbum, el usuario puede modificarlo desde la app de Google Fotos.