Compartilhar mídia

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

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

1. Criar um álbum em nome de um usuário.
2. Defina o álbum como compartilhado.

Observação: antes de compartilhar um álbum, peça o consentimento explícito do usuário e siga as diretrizes de UX.

Escopo de autenticação obrigatório

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

Como compartilhar um álbum

Antes de compartilhar um álbum, considere o seguinte:

• O app só pode compartilhar álbuns criados por ele. Álbuns criados por outros apps, incluindo o Google Fotos, não podem ser compartilhados pelo seu app.
• Quando o app compartilha um álbum pela API Library, um URL compartilhável é gerado para que qualquer pessoa possa acessar o álbum.
• Nos álbuns compartilhados usando a API, o proprietário pode desativar o compartilhamento de link ou cancelar o compartilhamento do álbum no Google Fotos, o que pode impedir que o app adicione novos usuários.

Para compartilhar um álbum:

1. Siga as diretrizes de UX e peça o consentimento explícito do usuário para criar um álbum compartilhado.
2. Crie o álbum e grave a albumId dele. Se você já criou o álbum, é possível recuperar o albumId dele listando os álbuns do usuário.
3. Chame albums.share usando o albumId relevante e as opções de compartilhamento que você quer definir.
4. Registre o valor shareToken na resposta. O token de compartilhamento é um identificador de um álbum compartilhado que pode ser usado em diferentes contas de usuário.
5. Agora, outro usuário pode se autenticar com seu app e depois join, sair ou recuperar os detalhes do álbum compartilhado usando o shareToken.

Opções de compartilhamento

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

Propriedade	Valor padrão	Descrição
isCollaborative	false	Define se outros usuários do Google Fotos podem adicionar conteúdo ao álbum compartilhado.
isCommentable	false	Define se outros usuários do Google Fotos podem comentar no álbum compartilhado.

Exemplo de solicitação

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

REST

Este é um cabeçalho de solicitação POST para compartilhar um álbum:

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

No corpo da solicitação, especifique as opções de compartilhamento.

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

Essa solicitação retorna a seguinte resposta:

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

Propriedades do álbum compartilhado

Para álbuns que foram criados e compartilhados pelo seu app, todas as respostas que retornam um album incluem uma propriedade extra, shareInfo. Essa propriedade é retornada ao compartilhar, listar ou retrieving álbuns.

A tabela a seguir lista as propriedades shareInfo:

Propriedades
sharedAlbumOptions	Opções que descrevem se alguém pode adicionar itens de mídia ou comentar em um álbum compartilhado.
shareableUrl	Um link para o álbum compartilhado do Google Fotos. Qualquer pessoa com o link pode ver o conteúdo do álbum, por isso ele precisa ser tratado com cuidado. O campo shareableUrl só vai ser retornado se o álbum estiver com o compartilhamento de link ativado. Se um usuário já participa de um álbum que não é compartilhado por link, ele pode usar o productUrl do álbum para acessá-lo. Uma shareableUrl será invalidada se o proprietário desativar o compartilhamento de link no app Google Fotos ou se o compartilhamento do álbum for cancelado.
shareToken	Um token usado para join, sair ou recuperar os detalhes de um álbum compartilhado em nome de um usuário que não é o proprietário. Uma shareToken será invalidada se o proprietário desativar o compartilhamento de link no app Google Fotos ou se o compartilhamento do álbum for cancelado.
isJoinable	True se os usuários puderem participar do álbum.
isJoined	True se o usuário estiver participando do álbum. Isso sempre acontece com o proprietário do álbum.
isOwned	True se o usuário for o proprietário do álbum.

Atenção :qualquer pessoa com o shareableUrl de um álbum pode ver o conteúdo dele.

Cancelar o compartilhamento de um álbum

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

Além do álbum não ser mais compartilhado, acontecerá o seguinte:

• Todos os não proprietários perderão o acesso ao álbum. Isso inclui as pessoas que compartilharam especificamente o álbum com elas 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, esse conteúdo será mantido.
• O token e o URL compartilhável do álbum serão invalidados.

Exemplo de solicitação

REST

Este é um cabeçalho de solicitação POST para cancelar o compartilhamento de um álbum:

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

O corpo da solicitação precisa estar vazio.

Se a solicitação for bem-sucedida, ela retornará uma resposta vazia com um código de status de sucesso HTTP. Se a solicitação não for bem-sucedida, ela retornará um código de status de erro HTTP com uma mensagem de erro.

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
}

Como recuperar álbuns compartilhados e compartilhar tokens

Os detalhes de um álbum compartilhado, incluindo o token de compartilhamento, são retornados quando o app compartilha um álbum. Também é possível recuperar esses detalhes posteriormente das maneiras a seguir.

Se o usuário conectado ao seu app for o proprietário ou fizer parte do álbum:

• Com albums.get usando o albumId relevante.
• Com albums.list, se houver itens de mídia no álbum.
• Com sharedAlbums.list, que retorna todos os álbuns compartilhados de que o usuário está participando ou é proprietário. Para recuperar somente os álbuns criados pelo seu app, use o parâmetro excludeNonAppCreatedData.
• Com sharedAlbums.get usando um token de compartilhamento.

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

Exemplo de solicitação

REST

Esta é uma solicitação para obter um álbum pela shareToken:

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

Se a solicitação for bem-sucedida, ela retornará os detalhes de album compartilhados.

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
}

Participar de um álbum compartilhado

Seu app pode participar de um álbum compartilhado em nome de um usuário com o token de compartilhamento do álbum. Para isso, as seguintes condições precisam ser atendidas:

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

Atenção :depois que o app compartilhar um álbum, o proprietário poderá desativar o compartilhamento de link ou cancelar o compartilhamento do álbum no app Google Fotos. Se isso acontecer, o token de compartilhamento do álbum será invalidado, o campo isJoinable será falso e o app não poderá associar usuários a ele.

REST

Este é um cabeçalho de solicitação POST para participar de um álbum compartilhado:

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

No corpo da solicitação, especifique o shareToken.

{
  "shareToken": "share-token"
}

A solicitação POST retorna as album compartilhadas em que seu app entrou em nome do usuário.

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
}

Saindo de um álbum compartilhado

Seu app pode sair de um álbum compartilhado em nome de um usuário usando o token de compartilhamento do álbum. Para isso, as seguintes condições precisam ser atendidas:

• O app criou e compartilhou o álbum.
• O usuário está participando do álbum. Ou seja, o campo isJoined no shareInfo do álbum é verdadeiro.
• O usuário conectado ao seu app não é o proprietário do álbum. Ou seja, o campo isOwned no shareInfo do álbum é falso.

REST

Este é um cabeçalho de solicitação POST para sair de um álbum compartilhado:

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

No corpo da solicitação, especifique o shareToken.

{
  "shareToken": "share-token"
}

Se a solicitação for bem-sucedida, ela retornará uma resposta vazia com um código de status de sucesso HTTP. Se a solicitação não for bem-sucedida, ela retornará um código de status de erro HTTP com uma mensagem de erro.

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
}

Propriedades do item de mídia compartilhada

Os itens de mídia que pertencem aos álbuns compartilhados pelo seu app contêm uma propriedade adicional, contributorInfo. Essa propriedade só é incluída ao listar o conteúdo de um álbum compartilhado.

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

Veja um exemplo:

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

Observação :a propriedade contributorInfo só vai ser retornada se o usuário conceder acesso ao escopo photoslibrary.sharing.