Bagikan media

Album yang dibuat oleh aplikasi Anda dapat dibagikan antar-pengguna, dengan opsi yang memungkinkan pengguna tersebut mengomentari, atau mengontribusikan item media mereka sendiri ke album.

Untuk membagikan album melalui Google Photos Library API, aplikasi Anda perlu melakukan hal berikut:

1. Membuat album atas nama pengguna.
2. Setel album tersebut untuk dibagikan.

Catatan: Sebelum membagikan album, dapatkan izin eksplisit dari pengguna, dan pastikan untuk mengikuti panduan UX.

Cakupan autentikasi yang diperlukan

Untuk membagikan konten, aplikasi Anda harus meminta cakupan otorisasi photoslibrary.sharing.

Membagikan album

Sebelum membagikan album, pertimbangkan pertimbangan berikut:

• Aplikasi hanya dapat membagikan album yang telah dibuatnya. Album yang dibuat oleh aplikasi lain, termasuk Google Foto, tidak dapat dibagikan oleh aplikasi Anda.
• Saat aplikasi Anda membagikan album melalui Library API, URL yang dapat dibagikan akan dibuat dan dapat digunakan siapa saja untuk mengakses album tersebut.
• Untuk album yang dibagikan melalui API, pemilik album dapat menonaktifkan berbagi link atau membatalkan berbagi album di aplikasi Google Foto sehingga berpotensi mencegah aplikasi Anda bergabung dengan pengguna baru ke album tersebut.

Untuk membagikan album:

1. Ikuti pedoman UX dan dapatkan izin eksplisit dari pengguna untuk membuat album bersama.
2. Buat album, dan rekam albumId-nya. Jika sudah membuat album, Anda dapat mengambil albumId-nya dengan mencantumkan album pengguna.
3. Panggil albums.share menggunakan albumId yang relevan, bersama dengan opsi berbagi yang ingin Anda tetapkan.
4. Catat nilai shareToken dalam respons. Token berbagi adalah ID untuk album bersama yang dapat digunakan di berbagai akun pengguna.
5. Pengguna lain kini dapat melakukan autentikasi dengan aplikasi Anda, lalu join, keluar, atau mengambil detail album bersama menggunakan shareToken-nya.

Opsi berbagi

Opsi berikut dapat disetel saat berbagi album menggunakan parameter sharedAlbumOptions. Jika opsi tidak ditetapkan secara eksplisit, nilai default akan digunakan.

Properti	Nilai default	Deskripsi
isCollaborative	false	Menetapkan apakah pengguna Google Foto lain dapat menambahkan konten ke album bersama.
isCommentable	false	Menetapkan apakah pengguna Google Foto lain dapat mengomentari album bersama.

Contoh permintaan

Permintaan berikut membagikan album dengan memanggil albums.share yang disertai opsi. Properti shareInfo ditampilkan dalam respons yang mendeskripsikan properti berbagi album.

REST

Berikut adalah header permintaan POST untuk membagikan album:

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

Dalam isi permintaan, tentukan opsi berbagi.

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

Permintaan ini menampilkan respons berikut:

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

Properti album bersama

Untuk album yang telah dibuat dan dibagikan oleh aplikasi Anda, semua respons yang menampilkan album menyertakan properti tambahan, shareInfo. Properti ini ditampilkan saat membagikan, mencantumkan, atau retrieving album.

Tabel berikut mencantumkan properti shareInfo:

Properti
sharedAlbumOptions	Opsi yang menjelaskan apakah seseorang dapat menambahkan item media ke atau mengomentari album bersama.
shareableUrl	Link ke album Google Foto bersama. Siapa pun yang memiliki link dapat melihat konten album sehingga harus diperlakukan dengan hati-hati. Kolom shareableUrl hanya ditampilkan jika album mengaktifkan berbagi link. Jika pengguna sudah bergabung ke album yang tidak dibagikan melalui link, mereka dapat menggunakan productUrl album untuk mengaksesnya. shareableUrl menjadi tidak valid jika pemilik menonaktifkan berbagi link di aplikasi Google Foto, atau jika album dibatalkan berbaginya.
shareToken	Token yang digunakan untuk join, keluar, atau mengambil detail album bersama atas nama pengguna yang bukan pemiliknya. shareToken menjadi tidak valid jika pemilik menonaktifkan berbagi link di aplikasi Google Foto, atau jika album dibatalkan berbaginya.
isJoinable	True jika album dapat digabungkan oleh pengguna.
isJoined	True jika pengguna bergabung ke album. Hal ini selalu berlaku untuk pemilik album.
isOwned	True jika pengguna adalah pemilik album.

Perhatian: Siapa saja yang memiliki shareableUrl album dapat melihat konten album.

Membatalkan berbagi album

Untuk membatalkan berbagi album yang sebelumnya telah dibagikan aplikasi Anda, panggil albums.unshare menggunakan albumId album.

Selain album yang tidak lagi dibagikan, hal-hal berikut akan terjadi:

• Semua orang yang bukan pemilik akan kehilangan akses ke album tersebut. Ini mencakup orang-orang yang telah secara khusus membagikan album kepada mereka melalui aplikasi Google Foto.
• Semua konten yang ditambahkan oleh bukan pemilik akan dihapus dari album.
• Jika pengguna sebelumnya telah menambahkan konten album ke koleksinya, konten tersebut akan dipertahankan di koleksi pengguna.
• Token berbagi album dan URL yang dapat dibagikan menjadi tidak valid.

Contoh permintaan

REST

Berikut adalah header permintaan POST untuk membatalkan berbagi album:

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

Isi permintaan harus kosong.

Jika berhasil, permintaan akan menampilkan respons kosong dengan kode status sukses HTTP. Jika permintaan tidak berhasil, kode status error HTTP akan ditampilkan dengan pesan error.

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
}

Mengambil album bersama dan token berbagi

Detail album bersama, termasuk token berbaginya, ditampilkan saat aplikasi Anda membagikan album. Anda juga dapat mengambil detail tersebut setelahnya dengan cara berikut.

Jika pengguna yang saat ini terhubung ke aplikasi Anda adalah pemilik, atau bergabung dengan album:

• Dengan albums.get menggunakan albumId yang relevan.
• Dengan albums.list, jika ada item media dalam album.
• Dengan sharedAlbums.list, yang menampilkan semua album bersama yang bergabung atau dimiliki pengguna. Untuk mengambil hanya album yang telah dibuat aplikasi Anda, gunakan parameter excludeNonAppCreatedData.
• Dengan sharedAlbums.get menggunakan token berbagi.

Jika pengguna yang saat ini terhubung ke aplikasi Anda tidak digabungkan ke album, Anda dapat mengambil detail album bersama dengan sharedAlbums.get menggunakan token berbagi yang valid.

Contoh permintaan

REST

Berikut adalah permintaan untuk mendapatkan album dari shareToken:

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

Jika permintaan berhasil, detail album yang dibagikan akan ditampilkan.

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
}

Bergabung dengan album bersama

Aplikasi Anda dapat bergabung dengan album bersama atas nama pengguna dengan token berbagi album. Untuk melakukannya, kondisi berikut harus terpenuhi:

• Aplikasi Anda telah membuat dan membagikan album.
• Pengguna yang ingin Anda gabungkan ke album bukan pemiliknya. Artinya, kolom isOwned di shareInfo album adalah salah.
• Token berbagi valid.
• Kolom isJoinable di shareInfo album adalah benar (true).

Perhatian: Setelah aplikasi Anda membagikan album, pemiliknya dapat menonaktifkan berbagi link atau membatalkan berbagi album di aplikasi Google Foto. Jika hal ini terjadi, token berbagi album akan menjadi tidak valid, kolom isJoinable-nya akan salah, dan aplikasi Anda tidak akan dapat menggabungkan pengguna ke album tersebut.

REST

Berikut adalah header permintaan POST untuk bergabung dengan album bersama:

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

Dalam isi permintaan, tentukan shareToken.

{
  "shareToken": "share-token"
}

Permintaan POST menampilkan album bersama yang digabungkan dengan aplikasi Anda atas nama pengguna.

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
}

Keluar dari album bersama

Aplikasi Anda dapat keluar dari album bersama atas nama pengguna, menggunakan token berbagi album. Untuk melakukannya, kondisi berikut harus terpenuhi:

• Aplikasi Anda telah membuat dan membagikan album.
• Saat ini pengguna bergabung dengan album. Artinya, kolom isJoined di shareInfo album adalah benar (true).
• Pengguna yang terhubung ke aplikasi Anda bukanlah pemilik album. Artinya, kolom isOwned di shareInfo album adalah salah (false).

REST

Berikut adalah header permintaan POST untuk keluar dari album bersama:

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

Dalam isi permintaan, tentukan shareToken.

{
  "shareToken": "share-token"
}

Jika berhasil, permintaan akan menampilkan respons kosong dengan kode status sukses HTTP. Jika permintaan tidak berhasil, kode status error HTTP akan ditampilkan dengan pesan error.

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
}

Properti item media bersama

Item media yang termasuk dalam album yang dibagikan oleh aplikasi Anda berisi properti tambahan, yaitu contributorInfo. Properti ini hanya disertakan saat mencantumkan konten album bersama.

Properti contributorInfo mencakup nama pengguna yang menambahkan item media ke album, dan URL dasar ke foto profilnya.

Berikut contohnya:

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

Catatan: Properti contributorInfo hanya ditampilkan jika pengguna telah memberikan akses ke cakupan photoslibrary.sharing.