Adicionar enriquecimentos

Os enriquecimentos permitem que seu aplicativo controle a estrutura e a apresentação de fotos em um álbum no Google Fotos. Elas permitem que você apresente ao usuário mais contexto com anotações de texto ou local e imagens de ordem/grupo que contam uma história.

Escopo de autorização obrigatório

A adição de enriquecimentos a álbuns criados pelo app requer o escopo photoslibrary.appendonly. Para mais informações sobre escopos, consulte Escpos de autorização.

Tipos de enriquecimento

O Google Fotos oferece suporte a três tipos de enriquecimento em álbuns: texto, locais e mapas.

Aprimoramentos de texto

Um enriquecimento de texto é uma string de texto simples que pode ser inserida para anotar o álbum.

Aprimoramentos de local

Um enriquecimento de local é um marcador e o nome do lugar que pode ser inserido para anotar um local.

Aprimoramentos do mapa

Um aprimoramento do mapa é um mapa com origem e destino especificados que podem ser inseridos no álbum.

Posições

Para inserir itens de mídia e enriquecimentos de álbum, especifique a posição do álbum. Uma posição é opcional para itens de mídia, mas precisa ser especificada para o enriquecimento do álbum.

Uma posição só pode ser especificada ao criar um item de mídia ou adicionar enriquecimentos. Os itens de mídia de um álbum não podem ser reorganizados. Por isso, é importante definir a posição de um item quando ele é adicionado.

Início do álbum

Um item de mídia/enriquecimento pode ser adicionado ao início do álbum como posicionamento absoluto.

Fim do álbum

Um item de mídia/enriquecimento pode ser adicionado ao final do álbum como posicionamento absoluto.

Em relação ao item de mídia

Um item de mídia/enriquecimento pode ser adicionado em relação a um item de mídia que começa após a posição dele no álbum.

Em relação ao item de enriquecimento

Um item de mídia/enriquecimento pode ser adicionado em relação a um item de aprimoramento começando após a posição dele no álbum.

Como adicionar enriquecimentos a um álbum

Os enriquecimentos são adicionados um por vez e precisam ser adicionados a uma posição em um álbum. Para adicionar enriquecimentos a um álbum, chame albums.addEnrichment.

Se a solicitação for bem-sucedida, ela vai retornar o id do item de enriquecimento, que pode ser usado para posicionar itens de mídia ou outras melhorias.

REST

Confira um exemplo de solicitação POST:

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

O corpo da solicitação consiste no item de enriquecimento e na posição dele:

{
  "newEnrichmentItem": {
    enrichment-to-be-added
  },
  "albumPosition": {
    position-of-enrichment
}

Veja um exemplo de resposta:

{
  "enrichmentItem": {
    "id": "enrichment-item-id",
  }
}

Enriquecimentos aceitos

Enriquecimentos de texto

Os enriquecimentos de texto contêm uma única string de texto (não mais de 1.000 caracteres), conforme mostrado no exemplo abaixo:

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");

Enriquecimentos de local

Os enriquecimentos de local consistem em um nome de local arbitrário e a posição de latitude e longitude. O locationName é limitado a 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);

Enriquecimentos de mapa

Os enriquecimentos de mapa mostram dois locais, cada um com um nome e a latitude e a longitude. Assim como no enriquecimento de local, o locationName dentro da origem e destination é limitado 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);

Posicionamento compatível

Início do álbum

A posição FIRST_IN_ALBUM refere-se ao início do álbum. Os itens localizados aqui são mostrados primeiro ao usuário:

REST

{
  "position": "FIRST_IN_ALBUM",
}

Java

AlbumPosition albumPosition = AlbumPositionFactory.createFirstInAlbum();

PHP

$albumPosition = new AlbumPosition();
$albumPosition->setPosition(PositionType::FIRST_IN_ALBUM);

Fim do álbum

A posição LAST_IN_ALBUM se refere ao fim do álbum. Os itens localizados aqui são mostrados ao usuário por último.

REST

{
  "position": "LAST_IN_ALBUM",
}

Java

AlbumPosition albumPosition = AlbumPositionFactory.createLastInAlbum();

PHP

$albumPosition = new AlbumPosition();
$albumPosition->setPosition(PositionType::LAST_IN_ALBUM);

Em relação ao item de mídia

Especificar a posição relativeMediaItem se refere a uma posição relativa a um item de mídia. Os itens são adicionados após o item de mídia especificado.

REST

{
  "position": "after-media-item",
  "relativeMediaItemId": "media-item-id"
}

Java

AlbumPosition albumPosition = AlbumPositionFactory.createAfterMediaItem(mediaItemId);

PHP

$albumPosition = PhotosLibraryResourceFactory::albumPositionAfterMediaItem($mediaItemId);

Relativo ao item de aprimoramento

A especificação de um relativeEnrichmentItemId se refere a uma posição relativa a um item de enriquecimento. Os itens são adicionados após o item de enriquecimento especificado.

REST

{
  "position": "after-enrichment-item",
  "relativeEnrichmentItemId": "enrichment-item-id"
}

Java

AlbumPosition albumPosition = AlbumPositionFactory.createAfterEnrichmentItem(enrichmentItemId);

PHP

$albumPosition = PhotosLibraryResourceFactory::albumPositionAfterEnrichmentItem($enrichmentItemId);

Como modificar melhorias

No momento, não é possível modificar os enriquecimentos. No entanto, depois que um enriquecimento é criado e adicionado a um álbum, o usuário pode modificar os enriquecimentos no app Google Fotos.