Aggiungi arricchimenti

Gli arricchimenti consentono all'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 di località e immagini di ordine/gruppo che raccontano una storia insieme.

Ambito dell'autorizzazione obbligatorio

Per aggiungere arricchimenti, è richiesto almeno uno dei seguenti ambiti:

  • photoslibrary.appendonly
  • photoslibrary.library
  • photoslibrary.sharing

Per ogni ambito, la chiamata enrichAlbum è limitata solo agli album creati dall'app.

Quando utilizzi l'ambito .sharing, enrichAlbum è limitato ai casi in cui lo sviluppatore agisce per conto del proprietario dell'album condiviso.

Tipi di arricchimento

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

Arricchimenti del testo

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

Screenshot di un arricchimento di testo mostrato in Google Foto

Arricchimenti della località

Un arricchimento di località è un indicatore e il nome del luogo che possono essere inseriti per annotare una località.

Screenshot dell'arricchimento della località mostrato in Google Foto

Arricchimenti della mappa

Un arricchimento mappa è una mappa con un'origine e una destinazione specificate che possono essere inserite nell'album.

Screenshot dell'arricchimento della mappa mostrato in Google Foto

Posizioni

Per inserire elementi multimediali e arricchimenti dell'album, specifica la posizione dell'album. La posizione è facoltativa per gli elementi multimediali, ma deve essere specificata per l'arricchimento dell'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, pertanto è importante impostare la posizione di un elemento quando viene aggiunto.

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

Puoi aggiungere un elemento multimediale/di arricchimento relativo a un elemento multimediale che inizia dopo la sua posizione nell'album.

Rispetto all'elemento di arricchimento

Un elemento multimediale/di arricchimento può essere aggiunto in base 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 di un album. Per aggiungere arricchimenti a un album, chiama albums.addEnrichment.

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

REST

Ecco una richiesta POST:

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

Il corpo della richiesta è composto dall'elemento di arricchimento e dalla sua posizione:

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

Ecco un esempio di risposta:

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

Arricchimenti supportati

Arricchimenti del testo

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

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

Arricchimenti della località

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

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

Arricchimenti della mappa

Gli arricchimenti della mappa mostrano due località, ciascuna costituita da un nome e da latitudine e longitudine. Analogamente all'arricchimento della località, il valore locationName all'interno dell'origine e di destination è limitato a 500 caratteri.

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

Posizionamento supportato

Inizio dell'album

La posizione FIRST_IN_ALBUM si riferisce all'inizio dell'album. Gli elementi situati qui vengono mostrati per primi all'utente:

REST

{
  "position": "FIRST_IN_ALBUM",
}

Java

AlbumPosition albumPosition = AlbumPositionFactory.createFirstInAlbum();

PHP

$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 situati qui vengono mostrati all'utente per ultimi.

REST

{
  "position": "LAST_IN_ALBUM",
}

Java

AlbumPosition albumPosition = AlbumPositionFactory.createLastInAlbum();

PHP

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

Rispetto all'elemento multimediale

Se specifichi la posizione relativeMediaItem, fai riferimento a una posizione relativa a un elemento multimediale. Gli elementi vengono aggiunti dopo l'elemento multimediale specificato.

REST

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

Java

AlbumPosition albumPosition = AlbumPositionFactory.createAfterMediaItem(mediaItemId);

PHP

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

Rispetto all'elemento di arricchimento

Se specifichi un valore relativeEnrichmentItemId, fai riferimento a una posizione relativa a un elemento di arricchimento. Gli elementi vengono aggiunti dopo l'elemento di arricchimento specificato.

REST

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

Java

AlbumPosition albumPosition = AlbumPositionFactory.createAfterEnrichmentItem(enrichmentItemId);

PHP

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

Modificare gli arricchimenti

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