Add-on Classroom dimuat dalam iframe untuk memberikan pengguna akhir dengan pengalaman pengguna yang mulus dan nyaman. Ada empat metode jenis iframe; lihat halaman iframe di direktori Perjalanan pengguna ringkasan tujuan dan tampilan masing-masing iframe.
panduan keamanan iframe
Partner diharapkan mengikuti praktik terbaik industri untuk mengamankan iframe mereka. Untuk melindungi iframe, tim keamanan kami menyarankan hal berikut:
HTTPS diperlukan. Kami sangat menyarankan untuk menggunakan TLS 1.2 atau yang lebih baru dan mengaktifkan HTTP Strict Transport Security. Lihat MDN terkait ini tentang Strict Transport Security.
Aktifkan Kebijakan Keamanan Konten Ketat. Lihat OWASP ini dan artikel MDN Kebijakan Keamanan Konten terkait ini.
Aktifkan Atribut cookie aman. Lihat atribut HttpOnly dan ini artikel MDN Cookie terkait.
Konfigurasi URI iFrame
URI Penyiapan Lampiran adalah tempat yang dimuat iframe Penemuan Lampiran, dan adalah tempat pengajar memulai alur pembuatan lampiran add-on pada Postingan Classroom. Atribut ini dapat ditetapkan di konsol project Google Cloud. Tetapkan URI ini di API project Google Cloud Anda & Layanan > SDK Google Workspace Marketplace > Konfigurasi Aplikasi.
Awalan URI Lampiran yang Diizinkan digunakan untuk memvalidasi URI yang ditetapkan dalam
AddOnAttachment menggunakan *.addOnAttachments.create
dan
metode *.addOnAttachments.patch
. Validasi adalah awalan string literal
dan tidak mengizinkan penggunaan
{i>wildcard<i} untuk saat ini.
Parameter kueri
iframe meneruskan informasi penting ke add-on sebagai parameter kueri. Ada dua kategori parameter: terkait lampiran dan terkait login parameter.
Parameter terkait lampiran
Parameter terkait lampiran memberikan informasi tentang lampiran mata pelajaran, tugas, lampiran add-on, tugas yang dikirimkan siswa, dan token otorisasi.
- ID Kursus
Nilai
courseId
adalah ID untuk kursus.Disertakan dengan semua iframe.
- ID Item
Nilai
itemId
adalah ID dariAnnouncement
,CourseWork
, atauCourseWorkMaterial
tempat lampiran ini berada terlampir.Disertakan dengan semua iframe.
- Jenis Item
Nilai
itemType
mengidentifikasi jenis resource tempatlampiran 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
teacherViewUri
,studentViewUri
, dan iframestudentWorkReviewUri
.- ID pengiriman
Nilai
submissionId
adalah ID untuk tugas siswa, tetapi harus digunakan bersamaattachmentId
untuk mengidentifikasi pekerjaan siswa pada tugas tertentu.Disertakan dengan
studentWorkReviewUri
.
- Token add-on
Nilai
addOnToken
adalah token otorisasi yang digunakan untuk membuatPanggilan
addOnAttachments.create
untuk membuat add-on.Disertakan dengan iframe Lampiran Penemuan dan Upgrade Link iframe.
- URL yang akan diupgrade
Adanya nilai
urlToUpgrade
menyiratkan bahwapengajar telah menyertakan Lampiran link di tugas, dan telah menyetujui untuk mengupgradenya ke lampiran add-on. Jika Anda belum fitur dikonfigurasi, lihat panduan tentang mengupgrade link ke add-on lampiran untuk detail selengkapnya.
Disertakan dengan iframe Upgrade Link.
Parameter terkait login
Parameter kueri login_hint
memberikan informasi tentang
Pengguna Classroom yang membuka halaman web add-on. Parameter kueri ini
diberikan di URL src
iframe. Pesan ini dikirim ketika pengguna sebelumnya telah menggunakan
add-on Anda untuk membantu mengurangi hambatan login pengguna akhir. Anda harus menangani
parameter kueri ini dalam penerapan add-on Anda.
- Petunjuk login
login_hint
adalah ID unik untuk ID penggunaAkun. 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 sehingga pengguna tidak perlu memasukkan kredensialnya saat dialog login muncul. Pengguna tidak login secara otomatis. - Setelah pengguna login, gunakan parameter ini untuk membandingkan kepada pengguna mana pun yang mungkin sudah pernah login ke add-on tersebut. Jika Anda menemukan kecocokan, biarkan pengguna tetap masuk dan jangan tampilkan alur login. Jika parameter tidak cocok dengan parameter login pengguna, minta pengguna tersebut untuk login dengan metode login bermerek Google .
Disertakan dengan semua iframe.
- Teruskan nilai
iframe Penemuan Lampiran
Dimensi | Deskripsi |
---|---|
Wajib | Ya |
URI | Disediakan di metadata add-on |
Parameter Kueri | courseId , itemId , itemType ,
addOnToken , dan login_hint . |
Tinggi | Tinggi jendela 80% dikurangi 60 piksel untuk header atas |
Lebar | Maksimum 1.600 piksel Lebar jendela 90% saat jendela <= 600 piksel lebar 80% lebar jendela saat jendela > Lebar 600 px |
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, lalu membuat pengumuman, tugas, atau
materi 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 disetel ke
https://example.com/addon?courseId=123&itemId=234&itemType=courseWork&addOnToken=456
.- Pengajar melakukan tugas dalam iframe untuk membuat pilihan lampiran.
- Pada pemilihan lampiran, add-on akan mengirimkan
postMessage
ke Classroom untuk menutup iframe.
pengajarViewUri dan iframe StudentViewUri
Dimensi | Deskripsi |
---|---|
Wajib | Ya |
URI | teacherViewUri atau studentViewUri |
Parameter Kueri | courseId , itemId , itemType ,
attachmentId , dan login_hint . |
Tinggi | Tinggi jendela 100% dikurangi 140 piksel untuk header atas |
Lebar | Lebar jendela 100% |
iframe StudentWorkReviewUri
Dimensi | Deskripsi |
---|---|
Wajib | Tidak (Menentukan apakah ini lampiran jenis aktivitas) |
URI | studentWorkReviewUri |
Parameter Kueri | courseId , itemId , itemType ,
attachmentId , submissionId , dan login_hint . |
Tinggi | Tinggi jendela 100% dikurangi 168 piksel untuk header atas |
Lebar | Lebar jendela 100% dikurangi lebar sidebar<> bilah sisi adalah 312 px saat diluaskan dan 56 piksel 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 , itemId , itemType ,
addOnToken , urlToUpgrade , dan login_hint . |
Tinggi | Tinggi jendela 80% dikurangi 60 piksel untuk header atas |
Lebar | Maksimum 1.600 piksel Lebar jendela 90% saat jendela <= 600 piksel lebar 80% lebar jendela saat jendela > Lebar 600 px |
Contoh skenario Upgrade Link
- Add-on Classroom didaftarkan dengan URI Link Upgrade dari
https://example.com/upgrade
. Anda telah memberikan host dan jalur berikut pola awalan untuk Lampiran link yang harus diberikan Classroom mencoba mengupgrade ke lampiran add-on:- Host-nya adalah
example.com
dan awalan jalurnya adalah/quiz
.
- Host-nya adalah
- Pengajar membuat pengumuman, tugas, atau materi baru di salah satu
kursusnya. Misalnya,
itemId=234
,itemType=courseWork
, dancourseId=123
. - Pengajar menempelkan link,
https://example.com/quiz/5678
, di Link sesuai dengan pola URL yang Anda berikan. Pengajar adalah kemudian diminta untuk mengupgrade Link ke lampiran add-on. Classroom meluncurkan iframe Upgrade Link dengan URL yang disetel dapat
https://example.com/upgrade?courseId=123&itemId=234&itemType=courseWork&addOnToken=456&urlToUpgrade=https%3A%2F%2Fexample.com%2Fquiz%2F5678
.Anda mengevaluasi parameter kueri yang diteruskan di iframe dan melakukan panggilan ke endpoint
CreateAddOnAttachment
. Perhatikan bahwa kueriurlToUpgrade
adalah URI yang dienkode saat diteruskan di iframe. Anda perlu mendekode untuk mendapatkannya dalam bentuk aslinya. JavaScript, misalnya, menawarkan fungsidecodeURIComponent()
.Setelah berhasil membuat lampiran add-on dari Link, Anda mengirim
postMessage
ke Classroom untuk menutup iframe.
Tutup iframe
iframe dapat ditutup dari alat pembelajaran dengan mengirimkan postMessage
dengan
{type: 'Classroom', action: 'closeIframe'}
payload.
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 seperti pada URI yang digunakan untuk meluncurkan iframe. Jika tidak, pesan
akan diabaikan. Solusinya adalah mengalihkan kembali ke laman di domain asli
yang tidak lebih dari mengirim peristiwa postMessage
.
Menutup iframe dari tab baru
Perlindungan lintas-domain mencegah hal ini berfungsi. Solusinya adalah dengan
komunikasi antara iframe dan tab baru dan membiarkan iframe
pada akhirnya bertanggung jawab untuk menerbitkan peristiwa postMessage
tutup. Sebagai sisi
catatan, hyperlink "Buka di Nama Partner" dihapus agar pengguna tidak
membuat tab dengan cara ini di masa mendatang.
Pembatasan
Semua iframe 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 untuk mempertahankan sesi login di iframe. Buka https://www.cookiestatus.com di status pemblokiran cookie saat ini di berbagai browser. Tentu saja, masalah ini tidak hanya terjadi di add-on Google Classroom dan memengaruhi semua situs yang pihak ketiga iframe. Banyak partner kami yang telah mengalami masalah ini.
Beberapa solusi umum adalah:
- Buka tab baru untuk membuat cookie dalam konteks pihak pertama. Beberapa browser memberikan akses ke cookie yang dibuat dalam konteks pihak pertama saat berada dalam konteks pihak ketiga.
- Minta pengguna untuk mengizinkan cookie pihak ketiga. Hal ini mungkin tidak selalu dapat dilakukan dengan semua pengguna.
- Desain aplikasi web satu halaman yang tidak bergantung pada cookie.
Pembatasan cookie lainnya diperkirakan akan tersedia di versi browser mendatang. Berkreasi permintaan fitur untuk mengirimkan masukan kepada Google tentang cara mengurangi peningkatan yang diperlukan oleh partner.
Aktifkan 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 Anda. Pengajar melampirkan link yang cocok dengan salah satu ekspresi reguler melihat dialog yang dapat ditutup, yang mendorong mereka untuk mencoba add-on Anda. Mereka hanya melihat dialog jika add-on sudah diinstal untuk akun mereka.
Jika Anda ingin memberikan perilaku ini kepada pengajar, berikan siswa Google kontak dengan ekspresi reguler yang sesuai. Jika ekspresi reguler yang Anda sediakan terlalu luas atau bertentangan dengan add-on lain, dimodifikasi menjadi lebih terbatas atau berbeda.
Gambar 1. Pengajar memilih link
lampiran ke tugas baru.
Gambar 2. Pengajar menempelkan link dari pihak ketiga
sumber. Pengajar tersebut telah menginstal paket
add-on Classroom.
Gambar 3. Dialog interaktif yang ditampilkan
kepada pengajar jika link yang ditempel cocok dengan ekspresi reguler yang ditentukan oleh
developer pihak ketiga.
Jika pengajar memilih "Coba sekarang" dalam pop seperti terlihat dalam gambar 3, mereka dialihkan ke iframe Lampiran Discovery add-on Anda.