Aggiungi arricchimenti

Gli arricchimenti consentono all'applicazione di controllare la struttura e la presentazione foto di un album in Google Foto. Ti consentono di presentare all'utente con contesto aggiuntivo tramite annotazioni di testo o posizioni e ordine/gruppo immagini che raccontano insieme una storia.

Ambito dell'autorizzazione richiesto

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

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

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

Quando si utilizza l'ambito .sharing, enrichAlbum è limitato alle circostanze Se lo sviluppatore agisce per conto del proprietario dell'album condiviso.

Tipi di arricchimento

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

Arricchimenti del testo

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

Screenshot di un arricchimento del testo mostrato in Google Foto

Arricchimenti posizione

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

Screenshot di un potenziamento della posizione mostrato in Google Foto

Arricchimenti mappa

Per arricchimento della mappa si intende una mappa con un'origine e una destinazione specificate che possono essere inserito nell'album.

Screenshot di un arricchimento mappa mostrato in Google Foto

Posizioni

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

Una posizione può essere specificata solo quando 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 quando viene aggiunto.

Inizio dell'album

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

Fine dell'album

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

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

Un elemento multimediale/di arricchimento può essere aggiunto rispetto all'inizio di un elemento di arricchimento in base alla sua posizione nell'album.

Aggiunta di miglioramenti all'album

Gli arricchimenti vengono aggiunti uno alla volta e devono essere inseriti in una posizione all'interno dell'album. Per aggiungere arricchimento a un album, chiama albums.addEnrichment

Se la richiesta ha esito positivo, restituisce il valore id dell'elemento di arricchimento, possono essere usate 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 testuali contengono una singola stringa di testo (non più di 1000 caratteri), ad esempio: 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 posizione

Gli arricchimenti relativi alla località consistono in un nome di posizione arbitrario, nonché in latitudine e e longitudine. Il campo locationName può contenere un massimo di 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 mappa

Gli aggiornamenti della mappa mostrano due luoghi, ognuno composto da un nome e dalla latitudine e longitudine. Analogamente all'arricchimento della posizione, locationName all'interno e 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 fa riferimento all'inizio dell'album. Elementi individuati che vengono mostrati prima 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. Elementi che si trovano qui vengono mostrati all'utente per ultimo.

REST

{
  "position": "LAST_IN_ALBUM",
}

Java

AlbumPosition albumPosition = AlbumPositionFactory.createLastInAlbum();

PHP

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

Rispetto all'elemento multimediale

La specifica della posizione relativeMediaItem fa riferimento a una posizione relativa a 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 potenziamento

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

REST

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

Java

AlbumPosition albumPosition = AlbumPositionFactory.createAfterEnrichmentItem(enrichmentItemId);

PHP

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

Modifica degli arricchimenti

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