Adicionar enriquecimentos

Os aprimoramentos permitem que seu aplicativo controle a estrutura e a apresentação de fotos em um álbum no Google Fotos. Eles permitem apresentar ao usuário mais contexto por meio de anotações de texto ou local e de imagens de ordem/agrupamento que contam uma história juntas.

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.

Enriquecimentos de texto

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

Aprimoramentos de local

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

Aprimoramentos do mapa

Um enriquecimento de mapa é um mapa com uma origem e um destino especificados que podem ser inseridos no álbum.

Posições

Para inserir itens de mídia e enriquecimentos de álbuns, 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.

Relativo ao item de enriquecimento

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

Como adicionar enriquecimentos a um álbum

Os aprimoramentos são adicionados um de cada 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 outros enriquecimentos.

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

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

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

Melhorias com suporte

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:

{
  "text": "Text to be shown"
}

// Use the NewEnrichmentItemFactory helper to create a text enrichment item
NewEnrichmentItem newEnrichmentItem =
    NewEnrichmentItemFactory.createTextEnrichment("text to be shown");

$newEnrichmentItem = PhotosLibraryResourceFactory::newEnrichmentItemWithText("text to be shown");

Aprimoramentos de local

Os aprimoramentos de local consistem em um nome arbitrário de local e na posição de latitude e longitude. O locationName é limitado a 500 caracteres.

{
  "location": {
    "locationName": "Australia",
    "latlng": {
      "latitude": "-21.197",
      "longitude": "95.821"
    }
  }
}

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

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

Aprimoramentos do mapa

Os enriquecimentos do mapa mostram dois locais, cada um consistindo em um nome e a latitude e longitude. Assim como no enriquecimento de local, o locationName na origem e o destination são limitados a 500 caracteres.

{
  "origin": {
    "locationName": "Australia",
    "latlng": {
      "latitude": "-21.197",
      "longitude": "95.821"
    }
  },
  "destination": {
    "locationName": "San Francisco",
    "latlng": {
      "latitude": "37.757",
      "longitude": "122.507"
    }
  }
}

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

// 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 ao usuário primeiro:

{
  "position": "FIRST_IN_ALBUM",
}

AlbumPosition albumPosition = AlbumPositionFactory.createFirstInAlbum();

$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.

{
  "position": "LAST_IN_ALBUM",
}

AlbumPosition albumPosition = AlbumPositionFactory.createLastInAlbum();

$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.

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

AlbumPosition albumPosition = AlbumPositionFactory.createAfterMediaItem(mediaItemId);

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

Em relação ao item de enriquecimento

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.

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

AlbumPosition albumPosition = AlbumPositionFactory.createAfterEnrichmentItem(enrichmentItemId);

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

Como modificar enriquecimentos

No momento, não é possível modificar os enriquecimentos. No entanto, depois que uma melhoria for criada e adicionada a um álbum, o usuário poderá modificá-la pelo app Google Fotos.