Add-on Classroom dimuat dalam iframe untuk memberikan pengalaman pengguna yang lancar dan nyaman kepada pengguna akhir. Ada empat jenis iframe yang berbeda; lihat halaman iframe di direktori Perjalanan pengguna untuk melihat ringkasan tujuan dan tampilan dari setiap iframe.
pedoman keamanan iframe
Partner diharapkan mengikuti praktik terbaik industri untuk mengamankan iframe mereka. Untuk melindungi iframe, tim keamanan kami merekomendasikan hal berikut:
HTTPS diperlukan. Sebaiknya gunakan TLS 1.2 atau yang lebih baru dan aktifkan HTTP Strict Transport Security. Lihat artikel MDN terkait ini tentang Strict Transport Security.
Aktifkan Kebijakan Keamanan Konten Ketat. Lihat artikel OWASP ini dan artikel MDN Kebijakan Keamanan Konten terkait ini.
Aktifkan Atribut cookie aman. Lihat Atribut HttpOnly dan artikel MDN Cookie yang terkait.
Konfigurasi URI iFrame
URI Penyiapan Lampiran adalah yang dimuat oleh iframe Lampiran Discovery, dan merupakan tempat pengajar memulai alur pembuatan lampiran add-on di postingan Classroom. Kunci ini dapat disetel di konsol project Google Cloud. Tetapkan URI ini di halaman API & Layanan project Google Cloud > Google Workspace Marketplace SDK > halaman App Configuration.
Awalan URI Lampiran yang Diizinkan digunakan untuk memvalidasi URI yang ditetapkan di
AddOnAttachment menggunakan metode *.addOnAttachments.create
dan
*.addOnAttachments.patch
. Validasi adalah pencocokan awalan string literal
dan tidak mengizinkan penggunaan karakter pengganti untuk saat ini.
Parameter kueri
iframe meneruskan informasi penting ke add-on sebagai parameter kueri. Ada dua kategori parameter: parameter terkait lampiran dan login.
Parameter terkait lampiran
Parameter terkait lampiran memberikan add-on informasi tentang kursus, tugas, lampiran add-on, kiriman siswa, dan token otorisasi.
- ID Kursus
Nilai
courseId
merupakan ID untuk kursus.Disertakan dengan semua iframe.
- ID Postingan (tidak digunakan lagi)
Nilai
postId
adalah ID postingan (pengumuman, tugas kursus, atau materi tugas kursus) tempat lampiran ini dilampirkan.Disertakan dengan semua iframe.
- ID Item
Nilai
itemId
adalah IDAnnouncement
,CourseWork
, atauCourseWorkMaterial
tempat lampiran ini dilampirkan.Disertakan dengan semua iframe.
- Jenis Item
Nilai
itemType
mengidentifikasi jenis resource tempat lampiran ini dilampirkan. Nilai string yang diteruskan adalah salah satu dari"announcements"
,"courseWork"
, atau"courseWorkMaterials"
.Disertakan dengan semua iframe.
- ID Lampiran
Nilai
attachmentId
adalah ID untuk lampiran.Disertakan dengan iframe
teacherViewUri
,studentViewUri
, danstudentWorkReviewUri
.- ID pengiriman
Nilai
submissionId
merupakan ID untuk tugas siswa, tetapi harus digunakan bersamaattachmentId
untuk mengidentifikasi tugas siswa pada tugas tertentu.Disertakan dengan
studentWorkReviewUri
.
- Token add-on
Nilai
addOnToken
adalah token otorisasi yang digunakan untuk melakukan panggilanaddOnAttachments.create
untuk membuat add-on.Disertakan dengan iframe Discovery Lampiran dan iframe Upgrade Link.
- URL yang akan diupgrade
Kehadiran nilai
urlToUpgrade
menyiratkan bahwa pengajar telah menyertakan Lampiran link dalam tugas, dan telah setuju untuk mengupgradenya ke lampiran add-on. Jika Anda belum mengonfigurasi fitur ini, lihat panduan tentang mengupgrade link ke lampiran add-on untuk mengetahui detail selengkapnya.Disertakan dengan iframe Upgrade Link.
Parameter terkait login
Parameter kueri login_hint
memberikan informasi tentang
pengguna Classroom yang mengunjungi halaman web add-on. Parameter kueri ini
diberikan pada URL src
iframe. Notifikasi ini dikirim saat pengguna sebelumnya menggunakan add-on Anda untuk membantu mengurangi hambatan login pengguna akhir. Anda harus menangani
parameter kueri ini dalam implementasi add-on.
- Petunjuk login
login_hint
adalah ID unik untuk akun GoogleAkun. Setelah pengguna login ke add-on Anda untuk pertama kalinya, parameter
login_hint
diteruskan pada setiap kunjungan berikutnya ke add-on Anda oleh pengguna yang sama.Ada dua kemungkinan penggunaan parameter
login_hint
:- Teruskan nilai
login_hint
selama alur autentikasi agar pengguna tidak perlu memasukkan kredensialnya saat dialog login muncul. Pengguna tidak login secara otomatis. - Setelah pengguna login, gunakan parameter ini untuk membandingkan nilai dengan pengguna yang mungkin sudah Anda loginkan ke add-on. Jika menemukan kecocokan, Anda dapat membiarkan pengguna login dan menghindari alur login. Jika parameter tidak cocok dengan semua pengguna yang login, minta pengguna untuk login dengan tombol login bermerek Google.
Disertakan dengan semua iframe.
- Teruskan nilai
Iframe Discovery Lampiran
Dimensi | Deskripsi |
---|---|
Wajib | Ya |
URI | Disediakan di metadata add-on |
Parameter Kueri | courseId , postId (tidak digunakan lagi), itemId , itemType ,
addOnToken , dan login_hint . |
Tinggi badan | Tinggi jendela 80% dikurangi 60px untuk header atas |
Lebar | Maksimum 1.600 piksel Lebar jendela 90% saat jendela <= 600 piksel lebar 80% lebar jendela jika jendela > lebar > 600 piksel |
Contoh skenario Penemuan Lampiran
- Add-on Classroom didaftarkan di Google Workspace
Marketplace dengan URI Penemuan Lampiran
https://example.com/addon
. - Pengajar menginstal add-on ini dan membuat pengumuman, tugas, atau
materi baru dalam salah satu kursusnya. Misalnya,
itemId=234
,itemType=courseWork
, dancourseId=123
. - Saat mengonfigurasi item tersebut, pengajar memilih add-on yang baru diinstal sebagai lampiran.
- Classroom membuat iframe dengan URL src yang ditetapkan ke
https://example.com/addon?courseId=123&itemId=234&itemType=courseWork&addOnToken=456
.- Pengajar melakukan tugas dalam iframe untuk membuat pilihan lampiran.
- Saat pemilihan lampiran, add-on akan mengirimkan
postMessage
ke Classroom untuk menutup iframe.
iframe teacherViewUri dan studentViewUri
Dimensi | Deskripsi |
---|---|
Wajib | Ya |
URI | teacherViewUri atau studentViewUri |
Parameter Kueri | courseId , postId (tidak digunakan lagi), itemId , itemType ,
attachmentId , dan login_hint . |
Tinggi badan | 100% tinggi jendela dikurangi 140 px untuk header atas |
Lebar | 100% lebar jendela |
iframe StudentWorkReviewUri
Dimensi | Deskripsi |
---|---|
Wajib | Tidak (Menentukan apakah ini lampiran jenis aktivitas) |
URI | studentWorkReviewUri |
Parameter Kueri | courseId , postId (tidak digunakan lagi), itemId , itemType ,
attachmentId , submissionId , dan login_hint . |
Tinggi badan | 100% tinggi jendela dikurangi 168 px untuk header atas |
Lebar | 100% lebar jendela dikurangi lebar sidebar<> adalah 312 piksel saat diluaskan dan 56px saat diciutkan |
iframe Upgrade Link
Dimensi | Deskripsi |
---|---|
Wajib | Ya, jika mengupgrade link ke lampiran add-on didukung oleh add-on Anda. |
URI | Disediakan di metadata add-on |
Parameter Kueri | courseId , postId (tidak digunakan lagi), itemId , itemType ,
addOnToken , urlToUpgrade , dan login_hint . |
Tinggi badan | Tinggi jendela 80% dikurangi 60px untuk header atas |
Lebar | Maksimum 1.600 piksel Lebar jendela 90% saat jendela <= 600 piksel lebar 80% lebar jendela jika jendela > lebar > 600 piksel |
Contoh skenario Upgrade Link
- Add-on Classroom didaftarkan dengan URI Upgrade Link
https://example.com/upgrade
. Anda telah memberikan pola awalan host dan jalur berikut untuk Lampiran link yang harus diupgrade oleh Classroom ke lampiran add-on:- Host-nya adalah
example.com
dan awalan jalurnya adalah/quiz
.
- Host-nya adalah
- Pengajar membuat pengumuman, tugas, atau materi baru dalam salah satu
kursusnya. Misalnya,
itemId=234
,itemType=courseWork
, dancourseId=123
. - Pengajar menempelkan link,
https://example.com/quiz/5678
, dalam dialog lampiran Link yang cocok dengan pola URL yang Anda berikan. Pengajar kemudian diminta untuk mengupgrade Link ke lampiran add-on. Classroom akan meluncurkan iframe Link Upgrade dengan URL yang ditetapkan ke
https://example.com/upgrade?courseId=123&postId=234&addOnToken=456&urlToUpgrade=https%3A%2F%2Fexample.com%2Fquiz%2F5678
.Anda mengevaluasi parameter kueri yang diteruskan di iframe dan melakukan panggilan ke endpoint
CreateAddOnAttachment
. Perlu diketahui bahwa parameter kueriurlToUpgrade
dienkode URI saat diteruskan ke iframe. Anda perlu mendekode parameter untuk mendapatkannya dalam bentuk aslinya. JavaScript, misalnya, menawarkan fungsidecodeURIComponent()
.Setelah berhasil membuat lampiran add-on dari Link, kirim
postMessage
ke Classroom untuk menutup iframe.
Tutup iframe
iframe dapat ditutup dari alat pembelajaran dengan mengirimkan postMessage
dengan
payload {type: 'Classroom', action: 'closeIframe'}
.
Classroom hanya menerima postMessage
ini dari host_name+port
yang sesuai dengan URI asli yang dibuka.
<button id="close">Send message to close iframe</button>
<script>
document.querySelector('#close')
.addEventListener('click', () => {
window.parent.postMessage({
type: 'Classroom',
action: 'closeIframe',
}, '*');
});
</script>
Menutup iframe dari iframe
Domain+port halaman yang mengirimkan peristiwa postMessage
harus memiliki domain+port yang sama dengan URI yang digunakan untuk meluncurkan iframe. Jika tidak, pesan akan diabaikan. Solusinya adalah mengalihkan kembali ke halaman di domain asli yang tidak melakukan apa pun selain mengirim peristiwa postMessage
.
Menutup iframe dari tab baru
Perlindungan lintas-domain mencegah fitur ini berfungsi. Solusinya adalah menangani sendiri komunikasi antara iframe dan tab baru, dan biarkan iframe bertanggung jawab dalam menerbitkan peristiwa postMessage
penutup. Sebagai catatan, hyperlink "Buka di Nama Partner" dihapus agar pengguna tidak membuat tab dengan cara ini dalam waktu dekat.
Batasan
Semua iframe akan dibuka dengan atribut sandbox berikut:
allow-popups
allow-popups-to-escape-sandbox
allow-forms
allow-scripts
allow-storage-access-by-user-activation
allow-same-origin
dan kebijakan fitur berikut
allow="microphone *"
Pemblokiran cookie pihak ketiga
Perlu diketahui bahwa pemblokiran cookie pihak ketiga mempersulit pengelolaan sesi login di iframe. Lihat https://www.cookiestatus.com untuk mengetahui status pemblokiran cookie saat ini di berbagai browser. Tentu saja, masalah ini tidak khusus untuk add-on Google Classroom dan memengaruhi semua situs yang pihak ketiga iframe. Banyak partner kami telah mengalami masalah ini.
Beberapa solusi umumnya adalah:
- Buka tab baru untuk membuat cookie dalam konteks pihak pertama. Beberapa browser memberikan akses ke cookie yang dibuat dalam konteks pihak pertama saat dalam konteks pihak ketiga.
- Minta pengguna untuk mengizinkan cookie pihak ketiga. Hal ini mungkin tidak selalu dapat dilakukan oleh semua pengguna.
- Desain aplikasi web satu halaman yang tidak mengandalkan cookie.
Pembatasan cookie yang lebih banyak diperkirakan akan diterapkan pada versi browser mendatang. Buat permintaan fitur untuk mengirimkan masukan ke Google tentang cara mengurangi peningkatan yang diperlukan oleh partner.
Mengaktifkan visibilitas add-on menggunakan ekspresi reguler URL
Pengajar sering membuat tugas dengan lampiran link. Untuk mempromosikan penggunaan add-on, Anda dapat menentukan ekspresi reguler yang cocok dengan URL resource yang dapat diakses di add-on. Pengajar yang melampirkan link yang cocok dengan salah satu ekspresi reguler Anda akan melihat dialog yang dapat ditutup yang mendorong mereka untuk mencoba add-on Anda. Pengguna hanya akan melihat dialog jika add-on sudah diinstal untuk akunnya.
Jika Anda ingin memberikan perilaku ini kepada pengajar, berikan ekspresi reguler yang sesuai kepada kontak Google Anda. Jika ekspresi reguler yang Anda berikan terlalu luas atau bertentangan dengan add-on lain, ekspresi tersebut dapat dimodifikasi agar lebih dibatasi atau berbeda.
Gambar 1. Pengajar memilih link lampiran ke tugas baru.
Gambar 2. Pengajar menempelkan link dari sumber pihak ketiga. Pengajar telah menginstal add-on Classroom pihak ketiga.
Gambar 3. Dialog interaktif yang ditampilkan kepada pengajar jika link yang ditempelkan cocok dengan ekspresi reguler yang ditentukan oleh developer pihak ketiga.
Jika pengajar memilih "Coba sekarang" di jendela pop-up seperti yang terlihat pada gambar 3, pengajar akan dialihkan ke iframe Discovery Lampiran add-on Anda.