Aggiungi arricchimenti

Gli arricchimenti consentono alla tua applicazione di controllare la struttura e la presentazione delle foto all'interno di un album in Google Foto. Ti consentono di presentare all'utente un contesto aggiuntivo tramite annotazioni di testo o posizione e ordinare/raggruppare le immagini che raccontano una storia insieme.

Ambito dell'autorizzazione richiesto

L'aggiunta di arricchimenti agli album creati dall'app richiede l'ambito photoslibrary.appendonly. Per ulteriori informazioni sugli ambiti, consulta Ambiti di autorizzazione.

Tipi di arricchimento

Google Foto supporta tre tipi di arricchimento negli album: testo, località e mappe.

Arricchimenti di testo

Un arricchimento del testo è una stringa di testo normale che può essere inserita per annotare l'album.

Arricchimenti dei dati sulla posizione

Un arricchimento della posizione è un indicatore e il nome del luogo che può essere inserito per annotare una posizione.

Arricchimenti delle mappe

Un arricchimento della mappa è una mappa con una partenza e una destinazione specificate che può essere inserita nell'album.

Posizioni

Per inserire elementi multimediali e arricchimenti dell'album, specifica la posizione dell'album. Una posizione è facoltativa per gli elementi multimediali, ma deve essere specificata per l'arricchimento degli album.

Una posizione può essere specificata solo durante la creazione di un elemento multimediale o l'aggiunta di arricchimenti. Gli elementi multimediali esistenti in un album non possono essere riorganizzati, quindi è importante impostare la posizione di un elemento al momento dell'aggiunta.

Inizio dell'album

Un elemento multimediale/di arricchimento può essere aggiunto all'inizio dell'album come posizionamento assoluto.

Fine dell'album

Un elemento multimediale/di arricchimento può essere aggiunto alla fine dell'album come posizionamento assoluto.

Rispetto all'elemento multimediale

Un elemento multimediale/arricchimento può essere aggiunto rispetto a un elemento multimediale che inizia dopo la sua posizione nell'album.

Rispetto all'elemento di potenziamento

È possibile aggiungere un elemento multimediale/di arricchimento rispetto a un elemento di arricchimento che inizia dopo la sua posizione nell'album.

Aggiunta di arricchimenti all'album

Gli arricchimenti vengono aggiunti uno alla volta e devono essere aggiunti a una posizione in un album. Per aggiungere arricchimenti a un album, chiama albums.addEnrichment.

Se la richiesta ha esito positivo, restituisce il valore id dell'elemento di potenziamento, che può essere utilizzato per posizionare elementi multimediali o altri arricchimenti.

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",
  }
}

Arricchimenti supportati

Arricchimenti di testo

Gli arricchimenti di testo contengono una singola stringa di testo (non più di 1000 caratteri), come mostrato nell'esempio seguente:

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

Arricchimenti dei dati sulla posizione

Gli arricchimenti della località consistono in un nome di località arbitrario e nella posizione di latitudine e longitudine. locationName è limitato a 500 caratteri.

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

Arricchimenti delle mappe

Gli arricchimenti della mappa mostrano due località, ciascuna composta da un nome, la latitudine e la longitudine. Come per l'arricchimento dei dati sulla posizione, locationName all'interno di destination e di destination è limitato a 500 caratteri.

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

Posizionamento supportato

Inizio dell'album

La posizione FIRST_IN_ALBUM fa riferimento all'inizio dell'album. Gli elementi che si trovano qui vengono mostrati prima all'utente:

{
  "position": "FIRST_IN_ALBUM",
}

AlbumPosition albumPosition = AlbumPositionFactory.createFirstInAlbum();

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

Fine dell'album

La posizione LAST_IN_ALBUM si riferisce alla fine dell'album. Gli elementi che si trovano qui vengono mostrati all'utente per ultimi.

{
  "position": "LAST_IN_ALBUM",
}

AlbumPosition albumPosition = AlbumPositionFactory.createLastInAlbum();

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

Rispetto all'elemento multimediale

La specifica della posizione relativeMediaItem si riferisce a una posizione relativa a un elemento multimediale. Gli elementi vengono aggiunti dopo l'elemento multimediale specificato.

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

AlbumPosition albumPosition = AlbumPositionFactory.createAfterMediaItem(mediaItemId);

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

Rispetto all'elemento di arricchimento

La specifica di un relativeEnrichmentItemId fa riferimento a una posizione relativa a un elemento di arricchimento. Gli elementi vengono aggiunti dopo l'elemento di arricchimento specificato.

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

AlbumPosition albumPosition = AlbumPositionFactory.createAfterEnrichmentItem(enrichmentItemId);

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

Modificare gli arricchimenti

Al momento non è possibile modificare gli arricchimenti. Tuttavia, una volta creato un arricchimento e aggiunto a un album, l'utente può modificarlo tramite l'app Google Foto.