Agrega mejoras

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.

Captura de pantalla de un enriquecimiento de texto que se muestra en Google Fotos

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.

Captura de pantalla de una actualización de ubicación que se muestra en Google Fotos

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.

Captura de pantalla de un enriquecimiento de mapa que se muestra en Google Fotos

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.