Konfigurasi project Google Cloud

Halaman ini berisi informasi yang perlu Anda ketahui tentang cara membuat dan mengonfigurasi project Google Cloud untuk add-on Classroom. Project Google Cloud digunakan untuk menerapkan Single Sign-On Google melalui OAuth 2.0 (Google SSO), untuk mengizinkan permintaan yang dibuat oleh add-on Anda, dan untuk mengelola listingan add-on di Google Workspace Marketplace.

Untuk informasi umum selengkapnya tentang cara memublikasikan add-on ke Marketplace, lihat Memublikasikan aplikasi.

Pembuatan project Google Cloud

Ada dua jenis project yang dapat dibuat: project pribadi yang digunakan untuk pengembangan dan project publik yang dapat dijangkau oleh pengguna akhir. Label "publik" dan "pribadi" mengacu pada visibilitas aplikasi Anda di Google Workspace Marketplace; aplikasi Marketplace pribadi hanya dapat diinstal oleh pengguna dalam domain tempat aplikasi tersebut dibuat, sedangkan aplikasi Marketplace publik tersedia untuk semua domain Google Workspace. Keduanya harus berupa dua aplikasi terpisah, karena project tidak dapat bersifat publik dan pribadi. Aplikasi publik harus ditinjau dan disetujui sebelum tersedia di marketplace.

Untuk informasi umum tentang pembuatan project Google Cloud, buka Membuat project Google Cloud.

Membuat project Google Cloud publik

Project ini mewakili aplikasi add-on yang dapat diakses oleh administrator, pengajar, dan siswa. Project publik harus ditinjau dan disetujui oleh tim Google Workspace Marketplace sebelum dapat diluncurkan atau diinstal.

  1. Buat project Google Cloud baru di domain produksi Anda.

    Membuat project Google Cloud

  2. Aktifkan Classroom API di project Cloud Anda.

    Mengaktifkan Classroom API

  3. Aktifkan Google Workspace Marketplace SDK di project Cloud Anda.

    Mengaktifkan Google Workspace Marketplace SDK

  4. Tetapkan Marketplace SDK App Configuration App Visibility ke Public dan centang kotak Unlisted.

  5. Lengkapi kolom yang wajib diisi di halaman Listingan Play Store Marketplace SDK, lalu klik PUBLIKASIKAN.

  6. Aplikasi Anda akan ditinjau oleh tim Google Workspace Marketplace. Mereka akan berkomunikasi dengan Anda menggunakan alamat email developer yang ditentukan di Marketplace SDK. Setelah aplikasi disetujui, hapus kotak Tidak ditampilkan agar pengajar dan administrator dapat menemukannya di Marketplace.

Membuat project Google Cloud pribadi

Project pribadi ini mewakili aplikasi add-on yang digunakan untuk pengembangan. Aplikasi ini tidak dapat diakses oleh pengguna di luar domain tempat aplikasi dibuat, tetapi tidak perlu disetujui sebelum penginstalan. Oleh karena itu, Google merekomendasikan penggunaan project ini untuk mengembangkan dan menguji add-on Anda di lingkungan yang terkontrol.

Anda memerlukan akses ke domain Google Workspace for Education dengan lisensi Teaching & Learning atau Plus untuk membuat project pribadi. Jika Anda belum memiliki akses ke domain tersebut, ikuti langkah-langkah berikut untuk menyiapkan domain demo Google Workspace for Education, mengupgradenya ke lisensi Plus, dan mengizinkannya mengakses API add-on Classroom:

  1. Selesaikan langkah-langkah untuk mendapatkan domain pengujian developer.

  2. Saat login sebagai administrator di domain demo, buat project Google Cloud baru.

    Membuat project Google Cloud

    Jika Anda tidak dapat mengakses konsol Google Cloud atau membuat project Cloud, periksa hal berikut di konsol Admin:

    • Buka halaman Setelan akun > Setelan akses berbasis usia, lalu pilih opsi untuk Semua pengguna dalam grup atau unit organisasi ini berusia 18 tahun atau lebih.
    • Di bagian Aplikasi > Layanan Google tambahan:
    • Google Cloud Platform AKTIF untuk semua orang.
    • Setelan Pembuatan Project adalah Izinkan pengguna membuat project.
    • Setelan Akses Cloud Shell adalah Izinkan akses ke Cloud Shell.

  3. Isi dan kirim formulir permintaan upgrade domain demo. Mengirimkan formulir ini akan meminta Google mengupgrade domain demo Anda ke Google Workspace for Education Plus dengan sepuluh lisensi dan mengizinkan project Cloud Anda mengakses API add-on Classroom.

    Anda akan menerima email saat proses upgrade dan daftar yang diizinkan selesai. Tetapkan lisensi Plus ke akun pengajar uji coba Anda di konsol Admin. Di bagian Direktori > Pengguna, buat atau pilih akun pengajar pengujian Anda. Di setiap Lisensi pengajar, pastikan Google Workspace for Education Plus Ditetapkan.

  4. Aktifkan Classroom API di project Cloud Anda.

    Mengaktifkan Classroom API

  5. Aktifkan Google Workspace Marketplace SDK di project Cloud Anda.

    Mengaktifkan Google Workspace Marketplace SDK

  6. Tetapkan Marketplace SDK App Configuration App Visibility ke private.

  7. Lengkapi kolom yang wajib diisi di halaman Listingan Play Store Marketplace SDK, lalu klik PUBLISH. Setelah listingan aplikasi dipublikasikan, pengguna di domain dapat menemukan dan menginstal aplikasi di Google Workspace Marketplace atau dengan membuka URL Aplikasi yang ditampilkan di halaman Listingan Play Store.

OAuth 2.0

Akses ke Classroom API memerlukan izin akses data pengguna. Token ini diperoleh dengan meminta akses Google ke cakupan OAuth untuk pengguna yang login dan menerima token yang dapat digunakan untuk kemudian melakukan panggilan API ke Google Classroom. Cakupan harus dikonfigurasi di daftar Play Store Google Workspace Marketplace agar administrator domain dapat memberikan izin atas nama pengguna domain mereka jika mereka menginstal add-on.

Karena cakupan Classroom bersifat Sensitif, Anda harus meminta verifikasi OAuth sebelum meluncurkan add-on. Jika tidak, pengguna akan melihat pesan peringatan bahwa aplikasi tidak terverifikasi, dan hanya sejumlah kecil pengguna yang dapat mengakses produk Anda. Lihat ringkasan urutan peninjauan untuk mengetahui informasi selengkapnya tentang verifikasi.

Lihat halaman Cakupan OAuth untuk Google API untuk mengetahui daftar mendetail tentang semua cakupan yang tersedia dan penggunaannya. Lihat halaman Konfigurasi OAuth dalam dokumentasi Workspace untuk informasi konfigurasi OAuth umum.

Izin pengguna

Aplikasi web Anda harus meminta setidaknya satu cakupan berikut:

  • https://www.googleapis.com/auth/userinfo.email, yang memungkinkan aplikasi melihat alamat email pengguna.
  • https://www.googleapis.com/auth/userinfo.profile, yang memungkinkan aplikasi melihat informasi pribadi seperti potret, nama depan dan belakang, serta informasi pribadi lainnya yang telah disediakan secara publik oleh pengguna.

Setelah pengguna memberikan otorisasi ke salah satu cakupan ini di add-on Anda, mereka akan diidentifikasi oleh parameter kueri login_hint. Parameter ini diteruskan ke URL aplikasi web Anda saat iframe dibuka. Jika pengguna belum memberikan otorisasi ke salah satu cakupan ini, login_hint tidak akan dikirim.

login_hint adalah parameter OpenID Connect standar yang dapat Anda teruskan ke Google secara opsional saat menggunakan Login dengan Google atau meminta token OAuth. Hal ini dimaksudkan untuk membuat pengalaman otorisasi lebih lancar bagi pengguna akhir.

Cakupan add-on Classroom

Cakupan berikut khusus untuk add-on Classroom:

  • https://www.googleapis.com/auth/classroom.addons.teacher, yang memungkinkan akses ke semua metode API.
  • https://www.googleapis.com/auth/classroom.addons.student, yang memungkinkan akses untuk meluncurkan validasi dan operasi baca lampiran.

Meskipun dengan token akses OAuth yang valid yang menunjukkan kredensial pengguna, panggilan API dibatasi oleh persyaratan tambahan:

  • Semua metode mengharuskan pengguna menjadi pengajar atau siswa dalam kursus yang ditentukan oleh courseId dalam permintaan.
  • Pembuatan, pembaruan, penghapusan, dan penerusan nilai lampiran mengharuskan pengguna menjadi pengajar.
  • Panggilan ke postingan Google Classroom tertentu dibatasi oleh pemeriksaan berikut.
    • Jika sudah memiliki minimal satu lampiran di postingan, add-on dapat membuat permintaan untuk:
      • validasi peluncuran iframe
      • Operasi baca, perbarui, dan hapus lampiran
      • Pembaruan nilai pada postingan tersebut
    • Saat iframe Penemuan Lampiran pertama kali dibuka, add-on mungkin belum memiliki lampiran di postingan. Parameter kueri addOnToken disediakan yang dapat digunakan untuk membuat permintaan untuk hal berikut:
      • Membuat lampiran di bawah postingan (addOnToken diperlukan)
      • Validasi peluncuran (addOnToken divalidasi jika diberikan dan diperlukan jika add-on tidak memiliki lampiran yang ada di postingan)

Verifikasi OAuth

Add-on Classroom menggunakan Google API untuk mengakses data pengguna Google.

Lihat FAQ verifikasi OAuth API untuk mengetahui informasi selengkapnya tentang proses verifikasi.

Listingan Google Workspace Marketplace

Untuk informasi konfigurasi Google Workspace Marketplace SDK umum, buka Mengaktifkan dan mengonfigurasi Google Workspace Marketplace SDK dan Membuat listingan Play Store Google Workspace Marketplace.

Pertimbangan listingan

Listingan Marketplace SDK Store project Google Cloud publik Anda menentukan nama dan deskripsi aplikasi yang ditujukan untuk pengguna akhir. Anda dapat memberikan detail ini dalam beberapa bahasa di bagian Detail Aplikasi.

Ikuti pedoman berikut di listingan Anda:

  • Di bagian App Details:

    • Hindari tanda baca dalam Nama Aplikasi. Misalnya, gunakan "Add-on Saya dari Perusahaan Saya", bukan "Perusahaan Saya: Add-on Saya" atau "Add-on Saya, dari Perusahaan Saya".

    • Deskripsi Singkat dan Deskripsi Mendetail tidak boleh berisi teks yang sama persis.

    + Pastikan Anda telah memilih nilai untuk kolom Pricing. Kolom ini mencakup opsi untuk harga Gratis, Berbayar dengan uji coba gratis, Berbayar dengan fitur gratis, dan Berbayar. Anda tidak perlu menentukan jumlah biaya di listingan Marketplace.

    • Pastikan Anda telah memilih nilai untuk kolom Kategori. Referensi Akademis atau Alat Pengajar dan Admin mungkin merupakan pilihan yang tepat untuk add-on Classroom.

    • Lihat item yang tercantum di Deskripsi detail aplikasi Marketplace untuk informasi lebih lanjut.

  • Di bagian Graphics Assets:

  • Di bagian Support Links:

    • Pastikan Anda telah memberikan link ke Persyaratan Layanan aplikasi Anda.

  • Pastikan Anda memenuhi Panduan branding Google API, yang mencakup nama dan deskripsi yang diizinkan.

  • Jika Anda merujuk ke produk Google apa pun dalam listingan, gunakan namanya dalam format yang disediakan di Daftar Merek Dagang. Pastikan Anda menyertakan simbol merek dagang (™) jika ditentukan; gunakan "Google Dokumen™", bukan "Google Dokumen".

Berintegrasi dengan layanan penagihan dan pemberian lisensi Google

Jika Anda tertarik untuk mengintegrasikan aplikasi Google Workspace Marketplace dengan layanan penagihan dan pemberian lisensi Google, buka Marketplace API.

Setelan penginstalan

Add-on dapat mengizinkan penginstalan perorangan selain penginstalan administrator. Halaman ini menyoroti beberapa perbedaan antara kedua jenis penginstalan. Halaman ini tidak dimaksudkan untuk mempromosikan salah satu jenis penginstalan. Anda dapat memilih apakah akan mengizinkan penginstalan individual di halaman Konfigurasi Aplikasi Google Workspace Marketplace SDK.

Penginstalan administrator

Penginstalan oleh admin memungkinkan admin menambahkan add-on ke semua akun di domain atau ke grup akses atau unit organisasi tertentu. Hanya administrator domain yang dapat melakukan penginstalan administrator. Administrator dapat memberikan izin secara opsional ke semua cakupan akses atas nama semua pengguna di domain; pengguna tidak akan diminta untuk memberikan izin ke cakupan akses apa pun jika administrator memilih untuk melakukannya.

Berikut adalah beberapa pertimbangan terkait penginstalan administrator.

  • Kontrol yang lebih ketat. Administrator dapat membatasi pengguna yang dapat mengakses add-on.
  • Kompatibilitas dengan pemberian lisensi. Jika aplikasi Anda memerlukan lisensi, mengarahkan penginstalan melalui administrator dapat membantu memastikan bahwa lisensi didistribusikan dan digunakan dengan tepat dengan institusi yang sesuai.
  • Beban yang lebih rendah bagi pengguna akhir. Penginstalan administrator mengurangi beban penyiapan untuk pengajar dan siswa. Hal ini dapat menghasilkan pengalaman pengguna yang lebih lancar dengan lebih sedikit klik dan lebih sedikit peluang untuk kebingungan.

Lihat Menginstal aplikasi Marketplace di domain Anda untuk mengetahui informasi selengkapnya tentang cara melakukan penginstalan administrator dan Cara kerja struktur organisasi untuk mempelajari unit organisasi dan grup akses lebih lanjut.

Penginstalan individual

Penginstalan individual menambahkan add-on ke akun pengguna sendiri. Pengguna akan diminta untuk memberikan izin ke cakupan akses add-on selama penginstalan.

Berikut adalah beberapa pertimbangan terkait penginstalan individual.

  • Memfasilitasi adopsi. Lebih banyak pengguna dapat melihat dan menginstal add-on Anda dari Google Workspace Marketplace. Mengizinkan penginstalan individual dapat mendorong lebih banyak pengajar untuk menggunakan atau mendukung produk Anda.
  • Pengujian administrator. Administrator dapat menginstal add-on secara terpisah untuk menguji atau mengevaluasinya sebelum menyetujui atau menginstalnya untuk grup yang lebih luas.

Selain menginstal add-on atas nama pengguna, administrator juga dapat mengelola daftar yang diizinkan untuk mengizinkan pengguna menginstal add-on yang mengizinkan penginstalan secara terpisah. Jika add-on tidak ada dalam daftar yang diizinkan, pengguna masih dapat melihat daftar add-on di Google Workspace Marketplace, tetapi tidak dapat menginstal add-on; mereka akan melihat pesan yang menjelaskan bahwa add-on belum diizinkan untuk diinstal oleh administrator domain. Lihat Mengelola aplikasi Google Workspace Marketplace di daftar yang diizinkan untuk mempelajari perilaku ini lebih lanjut.

Lihat dokumentasi setelan penginstalan Google Workspace Marketplace untuk mengetahui informasi selengkapnya.

Integrasi Apl

Anda harus memberikan URL iframe peluncuran di kolom Attachment Setup URI. URL ini digunakan sebagai nilai src iframe untuk iframe Penemuan Lampiran. Iframe Penemuan Lampiran digunakan oleh pengajar untuk menemukan konten atau aktivitas yang akan disertakan ke tugas mereka.

Anda juga harus menentukan semua awalan URI tempat lampiran diizinkan dari add-on Anda. Fitur ini meningkatkan keamanan dengan mencegah lampiran dari sumber yang tidak sah.

Lihat halaman panduan iframe untuk mengetahui detail selengkapnya tentang kolom ini.

Akun pengujian

Buat akun pengujian di domain demo untuk memverifikasi perilaku add-on pribadi Anda yang benar. Dua akun siswa diperlukan untuk menguji pengalihan antar-siswa di iframe Ulasan Tugas Siswa.

Akun pengujian yang disarankan:

  • Tamara Pengajar, tammy.pengajar@<domain demo Anda>
  • Sam Siswa, sam.siswa@<domain demo Anda>
  • Sally Student, sally.student@<your demo domain>

Ikuti prosedur ini untuk membuat akun pengujian baru:

  1. Login ke konsol Admin.
  2. Buka Pengguna.
  3. Klik Tambahkan pengguna baru (lihat Gambar 1).
  4. Masukkan informasi pengguna dan tetapkan peran yang sesuai.

Klik Tambahkan pengguna baru Gambar 1. Lokasi link Tambahkan pengguna baru dalam konsol Admin.

Ikuti prosedur ini untuk membuat grup pengujian baru:

  1. Login ke konsol Admin.
  2. Buka Grup.
  3. Klik Buat grup (lihat Gambar 2).
  4. Masukkan anggota dan pemilik grup.

Klik Buat grup Gambar 2. Lokasi link Buat grup dalam konsol Admin.