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.

.

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

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.

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 na álbum compartilhado.

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.

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 retornar um album; incluem uma propriedade adicional, shareInfo Isso é retornada ao compartilhar, ficha ou recuperando álbuns.

A tabela a seguir lista shareInfo propriedades:

Propriedades
sharedAlbumOptions	Opções que descrevem se alguém pode adicionar mídia itens ou comentários em um álbum compartilhado.
shareableUrl	Um link para o álbum compartilhado do Google Fotos. Qualquer pessoa com o link pode visualizar o conteúdo do álbum, por isso ele deve ser tratado com cuidado. O campo shareableUrl só é retornado se o álbum tem compartilhamento de link ativado. Se um usuário já estiver associado a um álbum não compartilhar o link, essa pessoa poderá usar o productUrl do álbum para acessá-lo. Uma shareableUrl será invalidada se o proprietário desativar o link o compartilhamento no app Google Fotos ou se o compartilhamento do álbum não estiver ativado.
shareToken	Um token usado para participar, sair, ou recuperar os detalhes de um álbum compartilhado em nome de um usuário que não é proprietário. Uma shareToken será invalidada se o proprietário desativar o link o compartilhamento no app Google Fotos ou se o compartilhamento do álbum não estiver ativado.
isJoinable	True se os usuários puderem participar do álbum.
isJoined	True se o usuário estiver associado ao álbum. É sempre true para o proprietário do álbum.
isOwned	True se o usuário for o proprietário do álbum.

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

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

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 tiver sido bem-sucedida, ela retornará uma resposta vazia com uma solicitação código de status de sucesso. Se a solicitação não tiver sido bem-sucedida, ela retornará uma solicitação código de status de erro 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 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

REST

Esta é uma solicitação para ter um álbum do shareToken:

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

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

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
}

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.

.

Atenção: após o app compartilhar um álbum, o proprietário pode desativar o compartilhamento de link ou cancele o compartilhamento do álbum no aplicativo Google Fotos. Se isso acontecer, a propriedade token de compartilhamento será invalidado, o campo isJoinable será falso, e O app não poderá associar os 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 o album compartilhado. seu app é registrado 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 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.

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 tiver sido bem-sucedida, ela retornará uma resposta vazia com uma solicitação código de status de sucesso. Se a solicitação não tiver sido bem-sucedida, ela retornará uma solicitação código de status de erro 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 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"
  }
}

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