Condividi contenuti multimediali

Gli album creati dalla tua app possono essere condivisi tra utenti, con l'opzione di autorizzarli a inserire commenti o a contribuire all'album con i propri elementi multimediali.

Per condividere un album tramite l'API Raccolta di Google Foto, la tua app deve:

1. Creare un album per conto di un utente.
2. Imposta l'album come condiviso.

Nota: prima di condividere un album, ottieni il consenso esplicito dell'utente e assicurati di rispettare le linee guida per l'esperienza utente.

Ambito dell'autenticazione richiesto

Per condividere contenuti, la tua app deve richiedere l'ambito dell'autorizzazione photoslibrary.sharing.

Condividere un album

Prima di condividere un album, tieni presente quanto segue:

• L'app può condividere soltanto gli album che ha creato. Gli album creati da altre app, incluso Google Foto, non possono essere condivisi dall'app.
• Quando la tua app condivide un album tramite l'API Library, viene generato un URL condivisibile che chiunque può utilizzare per accedere all'album.
• Per gli album condivisi tramite l'API, il proprietario dell'album può disattivare la condivisione tramite link o annullare la condivisione dell'album nell'app Google Foto, impedendo potenzialmente all'app di unirsi a nuovi utenti.

Per condividere un album:

1. Segui le linee guida per l'esperienza utente e ottieni il consenso esplicito dell'utente per creare un album condiviso.
2. Crea l'album e registra il relativo albumId. Se hai già creato l'album, puoi recuperarne albumId inserendo gli album dell'utente.
3. Chiama albums.share utilizzando il albumId pertinente, insieme alle opzioni di condivisione che vuoi impostare.
4. Registra il valore shareToken nella risposta. Il token di condivisione è l'identificatore di un album condiviso, utilizzabile tra diversi account utente.
5. Un altro utente può ora eseguire l'autenticazione con la tua app, quindi join, abbandonare o recuperare i dettagli dell'album condiviso utilizzando il relativo shareToken.

Opzioni di condivisione

Quando condividi un album utilizzando il parametro sharedAlbumOptions, è possibile impostare le seguenti opzioni. Se le opzioni non sono impostate esplicitamente, vengono utilizzati i valori predefiniti.

Proprietà	Valore predefinito	Descrizione
isCollaborative	false	Consente di stabilire se altri utenti di Google Foto possono aggiungere contenuti all'album condiviso.
isCommentable	false	Consente di specificare se altri utenti di Google Foto possono commentare l'album condiviso.

Esempio di richiesta

La seguente richiesta condivide un album chiamando albums.share con le opzioni. Una proprietà shareInfo viene restituita nella risposta che descrive le proprietà di condivisione dell'album.

REST

Ecco l'intestazione di una richiesta POST per condividere un album:

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

Nel corpo della richiesta, specifica le opzioni di condivisione.

{
  "sharedAlbumOptions": {
    "isCollaborative": "true",
    "isCommentable": "true"
  }
}

Questa richiesta restituisce la seguente risposta:

{
  "shareInfo": {
    "sharedAlbumOptions": {
      "isCollaborative": "true",
      "isCommentable": "true"
    },
    "shareableUrl": "shareable-url",
    "shareToken": "share-token",
    "isJoinable": "true-if-users-can-join-album",
    "isJoined": "true-if-user-is-joined-to-album",
    "isOwned": "true-if-user-owns-album"
  }
}

Java

try {

  SharedAlbumOptions options =
          // Set the options for the album you want to share
          SharedAlbumOptions.newBuilder()
          .setIsCollaborative(true)
          .setIsCommentable(true)
          .build();
  ShareAlbumResponse response = photosLibraryClient.shareAlbum(albumId, options);

  // The response contains the shareInfo object, a url, and a token for sharing
  ShareInfo info = response.getShareInfo();
  // Link to the shared album
  String url = info.getShareableUrl();
  String shareToken = info
  // The share token which other users of your app can use to join the album you shared
      .getShareToken();
  SharedAlbumOptions sharedOptions = info
      // The options set when sharing this album
      .getSharedAlbumOptions();

} catch (ApiException e) {
  // Handle error
}

PHP

// Set the options for the album you want to share
$options = new SharedAlbumOptions();
$options->setIsCollaborative(true);
$options->setIsCommentable(true);
try {
    $response = $photosLibraryClient->shareAlbum($albumId, ['sharedAlbumOptions' => $options]);
    // The response contains the shareInfo object, a url, and a token for sharing
    $shareInfo = $response->getShareInfo();
    // Link to the shared album
    $url = $shareInfo->getShareableUrl();
    // The share token which other users of your app can use to join the album you shared
    $shareToken = $shareInfo->getShareToken();
    // The options set when sharing this album
    $sharedOptions = $shareInfo->getSharedAlbumOptions();
} catch (\Google\ApiCore\ApiException $e) {
    // Handle error
}

Proprietà album condiviso

Per gli album che sono stati creati e condivisi dalla tua app, tutte le risposte che restituiscono un elemento album includono un'ulteriore proprietà, shareInfo. Questa proprietà viene restituita in caso di condivisione, elenco o retrieving album.

Nella tabella seguente sono elencate le proprietà shareInfo:

Proprietà
sharedAlbumOptions	Opzioni che indicano se un utente può aggiungere elementi multimediali a un album condiviso o aggiungere commenti.
shareableUrl	Un link all'album Google Foto condiviso. Chiunque abbia il link può visualizzare i contenuti dell'album, quindi occorre prestare la massima attenzione. Il campo shareableUrl viene restituito solo se nell'album è stata attivata la condivisione tramite link. Se un utente fa già parte di un album che non è condiviso tramite link, può utilizzare l'oggetto productUrl dell'album per accedervi. Un shareableUrl viene invalidato se il proprietario disattiva la condivisione tramite link nell'app Google Foto o se la condivisione dell'album viene annullata.
shareToken	Un token che viene utilizzato per join, uscire o recuperare i dettagli di un album condiviso per conto di un utente che non è il proprietario. Un shareToken viene invalidato se il proprietario disattiva la condivisione tramite link nell'app Google Foto o se la condivisione dell'album viene annullata.
isJoinable	True se gli utenti possono partecipare all'album.
isJoined	True se l'utente partecipa all'album. Questo vale sempre per il proprietario dell'album.
isOwned	True se l'utente è il proprietario dell'album.

Attenzione: chiunque abbia il codice shareableUrl di un album può visualizzarne i contenuti.

Annullare la condivisione di un album

Per annullare la condivisione di un album condiviso in precedenza dall'app, chiama albums.unshare utilizzando albumId dell'album.

Inoltre, l'album non viene più condiviso, quando si verifica quanto segue:

• Tutti gli utenti che non sono proprietari perderanno l'accesso all'album. Sono incluse le persone che hanno l'album condiviso appositamente con loro tramite l'app Google Foto.
• Tutti i contenuti aggiunti dagli utenti che non sono proprietari saranno rimossi dall'album.
• Se un utente ha precedentemente aggiunto i contenuti dell'album alla propria raccolta, i contenuti verranno conservati nella sua raccolta.
• Il token di condivisione e l'URL condivisibile dell'album verranno invalidati.

Esempio di richiesta

REST

Ecco l'intestazione di una richiesta POST per annullare la condivisione di un album:

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

Il corpo della richiesta deve essere vuoto.

Se la richiesta ha esito positivo, restituisce una risposta vuota con un codice di stato HTTP di esito positivo. Se la richiesta non ha esito positivo, viene restituito un codice di stato di errore HTTP con un messaggio di errore.

Java

try {
  // If this call is not successful, an exception is raised
  photosLibraryClient.unshareAlbum(albumId);
} catch (ApiException e) {
  // Handle error
}

PHP

try {
    // Mark the album as private and no longer shared
    // If this call is not successful, an exception is raised
    $photosLibraryClient->unshareAlbum($albumId);
} catch (\Google\ApiCore\ApiException $e) {
    // Handle error
}

Recupero degli album condivisi e dei token di condivisione

Quando l'app condivide un album, vengono restituiti i dettagli di un album condiviso, incluso il relativo token di condivisione. Puoi anche recuperare questi dettagli in seguito nei seguenti modi.

Se l'utente attualmente connesso alla tua app è il proprietario o fa parte dell'album:

• Con albums.get utilizzando i albumId pertinenti.
• Con albums.list, se l'album contiene elementi multimediali.
• Con sharedAlbums.list, che restituisce tutti gli album condivisi a cui l'utente è membro o di sua proprietà. Per recuperare solo gli album creati dalla tua app, utilizza il parametro excludeNonAppCreatedData.
• Con sharedAlbums.get l'utilizzo di un token di condivisione.

Se l'utente attualmente connesso alla tua app non partecipa all'album, puoi recuperare i dettagli di un album condiviso con sharedAlbums.get utilizzando un token di condivisione valido.

Esempio di richiesta

REST

Ecco una richiesta per ottenere un album entro il giorno shareToken:

GET https://photoslibrary.googleapis.com/v1/sharedAlbums/share-token

Se la richiesta riesce, vengono restituiti i dettagli condivisi album .

Java

try {
  // Get a shared album from its share token
  Album sharedAlbum = photosLibraryClient.getSharedAlbum(shareToken);

  String id = sharedAlbum.getId();
  String title = sharedAlbum.getTitle();
  // ...

} catch (ApiException e) {
  // Handle error
}

PHP

try {
    // Get the album from a share token
    $album = $photosLibraryClient->getSharedAlbum($shareToken);

    // Get some properties of an album
    $productUrl = $album->getProductUrl();
    $title = $album->getTitle();

} catch (\Google\ApiCore\ApiException $e) {
    // Handle error
}

Partecipazione a un album condiviso

La tua app può partecipare a un album condiviso per conto di un utente con il token di condivisione dell'album. Per farlo, le seguenti condizioni devono essere vere:

• L'app ha creato e condiviso l'album.
• L'utente a cui vuoi partecipare non è il proprietario dell'album. In altre parole, il campo isOwned nel shareInfo dell'album è false.
• Il token di condivisione sia valido.
• Il campo isJoinable nel campo shareInfo dell'album è true.

Attenzione: dopo che l'app ha condiviso un album, il proprietario può disattivare la condivisione tramite link o annullare la condivisione dell'album nell'app Google Foto. In questo caso, il token di condivisione dell'album verrà invalidato, il campo isJoinable sarà falso e l'app non potrà unirsi all'album.

REST

Ecco l'intestazione di una richiesta POST per partecipare a un album condiviso:

POST https://photoslibrary.googleapis.com/v1/sharedAlbums:join
Content-type: application/json
Authorization: Bearer oauth2-token

Nel corpo della richiesta, specifica shareToken.

{
  "shareToken": "share-token"
}

La richiesta POST restituisce il album condiviso a cui è stata aggiunta l'app per conto dell'utente.

Java

try {
  // Join the shared album using the share token obtained when sharing the album
  // If this call is not successful, an exception is raised
  JoinSharedAlbumResponse response = photosLibraryClient.joinSharedAlbum(shareToken);
  Album joinedAlbum = response.getAlbum();
} catch (ApiException e) {
  // Handle error
}

PHP

try {
    $response = $photosLibraryClient->joinSharedAlbum($shareToken);
    // Join the shared album using the share token obtained when sharing the album
    // If this call is not successful, an exception is raised
    $joinedAlbum = $response->getAlbum();
} catch (\Google\ApiCore\ApiException $e) {
    // Handle error
}

Uscita da un album condiviso

L'app può abbandonare un album condiviso per conto di un utente utilizzando il token di condivisione dell'album. Per farlo, le seguenti condizioni devono essere vere:

• L'app ha creato e condiviso l'album.
• L'utente è attualmente unito all'album. In altre parole, il campo isJoined nel campo shareInfo dell'album è true.
• L'utente connesso alla tua app non è il proprietario dell'album. In altre parole, il campo isOwned nella sezione shareInfo dell'album è false.

REST

Ecco l'intestazione di una richiesta POST per abbandonare un album condiviso:

POST https://photoslibrary.googleapis.com/v1/sharedAlbums:leave
Content-type: application/json
Authorization: Bearer oauth2-token

Nel corpo della richiesta, specifica shareToken.

{
  "shareToken": "share-token"
}

Se la richiesta ha esito positivo, restituisce una risposta vuota con un codice di stato HTTP di esito positivo. Se la richiesta non ha esito positivo, viene restituito un codice di stato di errore HTTP con un messaggio di errore.

Java

try {
  // Leave a shared album using its share token
  // If this call is not successful, an exception is raised
  photosLibraryClient.leaveSharedAlbum(shareToken);
} catch (ApiException e) {
  // Handle error
}

PHP

try {
    // Leave the shared album using the share token obtained when sharing the album
    // If this call is not successful, an exception is raised
    $photosLibraryClient->leaveSharedAlbum($shareToken);
} catch (\Google\ApiCore\ApiException $e) {
    // Handle error
}

Proprietà degli elementi multimediali condivisi

Gli elementi multimediali appartenenti agli album condivisi dalla tua app contengono una proprietà aggiuntiva, contributorInfo. Questa proprietà è inclusa solo quando elenchi i contenuti di un album condiviso.

La proprietà contributorInfo include il nome dell'utente che ha aggiunto l'elemento multimediale all'album e un URL di base all'immagine del suo profilo.

Esempio:

{
  "id: "media-item-id",
  ...,
  "mediaMetadata": {
    ...
  }
  "contributorInfo": {
    "profilePictureBaseUrl": "profile-picture-base-url_use-only-with-parameters",
    "displayName": "name-of-user"
  }
}

Nota: la proprietà contributorInfo viene restituita solo se l'utente ha concesso l'accesso all'ambito photoslibrary.sharing.