Compartilhar mídia

Os álbuns criados pelo app podem ser compartilhados entre os usuários, com opções para permitir que esses usuários comentem ou contribuam com seus próprios itens de mídia para o álbum.

Para compartilhar um álbum pela API Google Photos Library, seu app precisa fazer o seguinte:

1. Crie um álbum em nome de um usuário.
2. Defina esse álbum como compartilhado.

Escopo de autenticação obrigatório

Para compartilhar conteúdo, o app precisa solicitar a photoslibrary.sharing escopo da autorização.

Compartilhar um álbum

Antes de compartilhar um álbum, considere o seguinte:

• Seu app só pode compartilhar álbuns que ele mesmo criou. Álbuns criados por outros apps incluindo o Google Fotos, não podem ser compartilhados pelo seu aplicativo.
• Quando seu app compartilha um álbum pela API Library, uma URL compartilhável é gerado e qualquer um pode usar para acessar o álbum.
• Nos álbuns compartilhados por meio da API, o proprietário do álbum pode: desativar o compartilhamento de link ou cancele o compartilhamento do álbum no aplicativo Google Fotos, possivelmente impedindo sua o aplicativo da associação de novos usuários a ele.

Para compartilhar um álbum:

1. Siga o Diretrizes de UX e pedir o consentimento explícito do usuário para criar um álbum compartilhado;
2. Crie o álbum, e registrar o albumId. Se você já tiver criado o álbum, poderá recuperar albumId listando os álbuns do usuário.
3. Chame albums.share usando o albumId relevante, junto com o opções de compartilhamento que você deseja definido.
4. Grave o shareToken na resposta. O token de compartilhamento é um identificador para um álbum compartilhado que podem ser usadas em diferentes contas de usuário.
5. Outro usuário agora pode autenticar com seu aplicativo e participar, sair, ou recupere os detalhes do álbum compartilhado usando shareToken.

Opções de compartilhamento

As opções a seguir podem ser definidas ao compartilhar um álbum usando o sharedAlbumOptions . Se as opções não forem definidas explicitamente, os valores padrão serão usados.

Exemplo de solicitação

A solicitação a seguir compartilha um álbum chamando albums.share com opções. Um Propriedade shareInfo é retornado na resposta que descreve as de compartilhamento de propriedades.

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

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

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

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
}

// 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
}

Propriedades do álbum compartilhado

Para álbuns que foram criados e compartilhados pelo seu app, todas as respostas que retornar um album; incluem uma propriedade adicional, shareInfo Isso é retornada ao compartilhar, ficha ou recuperando álbuns.

A tabela a seguir lista shareInfo propriedades:

Como cancelar o compartilhamento de um álbum

Para cancelar o compartilhamento de um álbum compartilhado por seu app, chame albums.unshare usando o albumId do álbum.

Além de o álbum não ser mais compartilhado, os itens a seguir serão acontecer:

• Todos os usuários que não forem proprietários perderão o acesso ao álbum. Isso inclui pessoas que tinha o álbum compartilhado especificamente pelo app Google Fotos.
• Todo o conteúdo adicionado por não proprietários será removido do álbum.
• Se um usuário já tiver adicionado o conteúdo do álbum à biblioteca, o conteúdos serão mantidos na biblioteca deles.
• O token de compartilhamento e o URL compartilhável do álbum serão invalidados.

Exemplo de solicitação

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

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

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
}

Como recuperar álbuns compartilhados e tokens de compartilhamento

Os detalhes de um álbum compartilhado incluindo o token de compartilhamento, são retornadas quando o aplicativo compartilha um álbum. Você pode também recupere esses detalhes posteriormente das seguintes maneiras.

Se o usuário conectado ao aplicativo for o proprietário ou estiver vinculado ao álbum:

• Com o albums.get usando o albumId relevantes.
• Com albums.list, se houver são itens de mídia do álbum.
• Com sharedAlbums.list, que retorna todos os álbuns compartilhados dos quais o usuário está associado ou é proprietário. Para recuperar somente os álbuns que seu aplicativo criou, use o excludeNonAppCreatedData .
• Com sharedAlbums.get usando um token de compartilhamento.

Se o usuário conectado ao aplicativo não estiver associado ao álbum, você pode recuperar detalhes de um álbum compartilhado com sharedAlbums.get usando um token de compartilhamento válido.

Exemplo de solicitação

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

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
}

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
}

Participando de um álbum compartilhado

Seu app pode participar de um álbum compartilhado em nome de um usuário com a opção de compartilhamento do álbum com base no token correto anterior. Para isso, as seguintes condições precisam ser verdadeiras:

• Seu app tem criou e compartilhou o álbum.
• O usuário que você quer associar ao álbum não é o proprietário dele. Ou seja, isOwned da coluna shareInfo é falso.
• O token de compartilhamento é válido.
• O campo isJoinable no shareInfo do álbum é verdadeiro.

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

{
  "shareToken": "share-token"
}

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
}

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
}

Saindo de um álbum compartilhado

Seu app pode sair de um álbum compartilhado em nome de um usuário usando o recurso de compartilhamento do álbum. com base no token correto anterior. Para isso, as seguintes condições precisam ser verdadeiras:

• Seu app criou e compartilhou o álbum.
• O usuário está associado ao álbum no momento. Ou seja, o campo isJoined no shareInfo do álbum é verdadeira.
• O usuário conectado ao aplicativo não é o proprietário do álbum. Ou seja, O campo isOwned no shareInfo do álbum é falso.

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

{
  "shareToken": "share-token"
}

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
}

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
}

Propriedades do item de mídia compartilhado

Itens de mídia que pertencem a os álbuns compartilhados pelo app contêm uma propriedade adicional, contributorInfo. Esta propriedade só é incluída ao listar os conteúdo de um álbum compartilhado.

A propriedade contributorInfo inclui o nome do usuário que adicionou a mídia. item ao álbum, e um URL de base ao perfil da pessoa imagem.

Veja um exemplo:

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