detail iframe dan parameter kueri

Add-on Classroom dimuat dalam iframe untuk memberikan pengalaman pengguna yang lancar dan praktis kepada pengguna akhir. Ada lima jenis iframe yang berbeda ; lihat halaman iframe di direktori Perjalanan pengguna untuk mengetahui ringkasan tujuan dan tampilan setiap iframe.

Poin Penting: Anda menerima berbagai informasi saat pengguna membuka salah satu tampilan add-on Anda. Gunakan informasi ini untuk mengidentifikasi lampiran, memvalidasi kredensial dan peran pengguna, serta melakukan permintaan API tertentu.

Panduan keamanan iframe

Developer diharapkan mengikuti praktik terbaik industri untuk mengamankan iframe mereka. Namun, Anda juga harus menyertakan interaksi API tertentu dalam alur pengguna untuk mengonfirmasi bahwa Anda memiliki kredensial yang valid dan dapat mengidentifikasi peran pengguna dalam kursus dengan benar.

Konfigurasi aplikasi server

Untuk melindungi iframe, sebaiknya gunakan konfigurasi server berikut:

• Diperlukan HTTPS. Sebaiknya gunakan TLS 1.2 atau yang lebih baru dan aktifkan HTTP Strict Transport Security (HSTS). Lihat artikel MDN terkait tentang Strict Transport Security.
• Aktifkan Kebijakan Keamanan Konten Ketat (Strict CSP). Lihat artikel OWASP ini dan artikel MDN Kebijakan Keamanan Konten terkait.
• Aktifkan atribut cookie Aman. Lihat atribut HttpOnly dan artikel MDN Cookie terkait ini.

Parameter kueri

Iframe meneruskan informasi penting ke add-on sebagai parameter kueri. Ada dua kategori parameter: parameter terkait lampiran dan parameter terkait login.

Parameter terkait lampiran

Parameter terkait lampiran memberikan informasi kepada add-on tentang kursus, tugas, lampiran add-on, pengiriman siswa, dan token otorisasi.

ID Kursus

Nilai courseId adalah ID untuk kursus.

Disertakan dengan semua iframe.

ID Item

Nilai itemId adalah ID Announcement, CourseWork, atau CourseWorkMaterial yang dilampirkan ke lampiran ini.

Disertakan dengan semua iframe.

Jenis Item

Nilai itemType mengidentifikasi jenis resource yang dilampirkan ke lampiran ini. 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 dan studentWorkReviewUri.

ID Pengiriman

Nilai submissionId adalah ID untuk pekerjaan siswa, tetapi harus digunakan bersama dengan attachmentId untuk mengidentifikasi pekerjaan siswa dari tugas tertentu.

Disertakan dengan studentWorkReviewUri.

Catatan: Anda dapat menggunakan kunci komposit submissionId dan attachmentId untuk mengidentifikasi pekerjaan siswa jika lampiran yang sama ditetapkan ke siswa yang sama di berbagai kursus. Untuk mengetahui informasi selengkapnya, lihat konten yang disalin.

Token add-on

Nilai addOnToken adalah token otorisasi yang digunakan untuk melakukan panggilan addOnAttachments.create guna membuat add-on.

Disertakan dengan iframe Penemuan Lampiran dan iframe Upgrade Link.

URL untuk diupgrade

Keberadaan nilai urlToUpgrade menunjukkan 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 lampiran 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 disediakan di URL src iframe. Parameter ini dikirim saat pengguna sebelumnya telah menggunakan add-on Anda untuk membantu mengurangi kesulitan login pengguna akhir. Anda wajib menangani parameter kueri ini dalam penerapan add-on Anda.

Petunjuk login

login_hint adalah ID unik untuk Akun Google pengguna. Setelah pengguna login ke add-on Anda untuk pertama kalinya, parameter login_hint akan diteruskan pada setiap kunjungan berikutnya ke add-on Anda oleh pengguna yang sama.

Ada dua potensi penggunaan untuk parameter login_hint:

1. Teruskan nilai login_hint selama alur autentikasi sehingga pengguna tidak perlu memasukkan kredensialnya saat dialog login muncul. Pengguna tidak otomatis login.
2. Setelah pengguna login, gunakan parameter ini untuk membandingkan nilai dengan pengguna yang mungkin sudah login ke add-on. Jika menemukan kecocokan, Anda dapat membiarkan pengguna tetap login dan menghindari menampilkan alur login. Jika parameter tidak cocok dengan pengguna yang login, minta pengguna untuk login dengan tombol login bermerek Google.

Disertakan dengan semua iframe.

Catatan: Informasi tambahan dapat ditemukan tentang penerapan parameter login_hint dan alur login di halaman panduan SSO, Login tanpa hambatan, dan Menangani login berulang.

iframe Penemuan Lampiran

Dimensi	Deskripsi
Wajib	Ya
URI	Disediakan dalam 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% jika lebar jendela <= 600 piksel lebar Lebar jendela 80% jika lebar jendela > 600 piksel

Contoh skenario Penemuan Lampiran

1. Add-on Classroom terdaftar di Google Workspace Marketplace dengan URI Penemuan Lampiran https://example.com/addon.
2. Pengajar menginstal add-on ini dan membuat pengumuman, tugas, atau materi baru dalam salah satu kursusnya. Misalnya, itemId=234, itemType=courseWork, dan courseId=123.
3. Saat mengonfigurasi item tersebut, pengajar memilih add-on yang baru diinstal sebagai lampiran.
4. Classroom membuat iframe dengan URL src yang ditetapkan ke https://example.com/addon?courseId=123&itemId=234&itemType=courseWork&addOnToken=456.
   1. Pengajar melakukan pekerjaan dalam iframe untuk membuat pilihan lampiran.
5. Saat memilih lampiran, add-on mengirim postMessage ke Classroom untuk menutup iframe.

iframe teacherViewUri dan 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<> sidebar adalah 312 piksel saat diperluas dan 56 piksel saat diciutkan

Catatan: Pengajar dapat membuka iframe Tinjauan Pekerjaan Siswa untuk siswa yang belum pernah melihat lampiran add-on. Dalam hal ini, add-on mungkin belum mengetahui siswa ini dan harus menampilkan pesan yang sesuai.

iframe Upgrade Link

Dimensi	Deskripsi
Wajib	Ya, jika mengupgrade link ke lampiran add-on didukung oleh add-on Anda.
URI	Disediakan dalam 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% jika lebar jendela <= 600 piksel lebar Lebar jendela 80% jika lebar jendela > 600 piksel

Contoh skenario Upgrade Link

1. Add-on Classroom terdaftar dengan URI Upgrade Link https://example.com/upgrade. Anda telah memberikan pola awalan host dan jalur berikut untuk lampiran Link yang akan diupgrade Classroom ke lampiran add-on:
   • Host-nya adalah example.com dan awalan jalurnya adalah /quiz.
2. Pengajar membuat pengumuman, tugas, atau materi baru dalam salah satu kursusnya. Misalnya, itemId=234, itemType=courseWork, dan courseId=123.
3. Pengajar menempelkan link, https://example.com/quiz/5678, di dialog lampiran Link yang cocok dengan pola URL yang Anda berikan. Pengajar kemudian diminta untuk mengupgrade Link ke lampiran add-on.

4. Classroom meluncurkan iframe Upgrade Link dengan URL yang ditetapkan ke https://example.com/upgrade?courseId=123&itemId=234&itemType=courseWork&addOnToken=456&urlToUpgrade=https%3A%2F%2Fexample.com%2Fquiz%2F5678.

5. Anda mengevaluasi parameter kueri yang diteruskan di iframe dan melakukan panggilan ke endpoint CreateAddOnAttachment. Perhatikan bahwa parameter kueri urlToUpgrade dienkode URI saat diteruskan di iframe. Anda perlu mendekode parameter untuk mendapatkannya dalam bentuk aslinya. JavaScript, misalnya, menawarkan fungsi decodeURIComponent().

6. Setelah berhasil membuat lampiran add-on dari Link, Anda mengirim postMessage ke Classroom untuk menutup iframe.

Menutup iframe

Iframe dapat ditutup dari alat pembelajaran dengan mengirim 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 mengirim 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 hal ini berfungsi. Solusinya adalah menangani komunikasi antara iframe dan tab baru sendiri dan membiarkan iframe pada akhirnya bertanggung jawab untuk mengeluarkan peristiwa postMessage penutup. Sebagai catatan tambahan, hyperlink "Buka di Nama Partner" akan dihapus sehingga pengguna tidak membuat tab dengan cara ini dalam waktu dekat.

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

Perhatikan bahwa pemblokiran cookie pihak ketiga mempersulit pemeliharaan sesi login di iframe. Lihat https://www.cookiestatus.com untuk mengetahui status pemblokiran cookie saat ini di berbagai browser. Tentu saja, masalah ini tidak hanya terjadi pada add-on Google Classroom dan memengaruhi semua situs yang menggunakan iframe pihak ketiga. Banyak partner kami 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 oleh semua pengguna.
• Desain aplikasi web satu halaman yang tidak mengandalkan cookie.

Pembatasan cookie lainnya diharapkan akan diterapkan di versi browser mendatang. Buat permintaan fitur untuk mengirim masukan kepada Google tentang cara mengurangi upaya yang diperlukan oleh partner.

Mengaktifkan kemampuan penemuan add-on menggunakan ekspresi reguler URL

Pengajar sering membuat tugas dengan lampiran link. Untuk mempromosikan penggunaan add-on Anda, Anda dapat menentukan ekspresi reguler yang cocok dengan URL resource yang dapat diakses di add-on Anda. 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. Mereka hanya akan melihat dialog jika add-on sudah diinstal untuk akun mereka.

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 reguler tersebut dapat diubah agar lebih terbatas atau berbeda.

Gambar 1. Pengajar memilih lampiran link 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 saat link yang ditempelkan cocok dengan ekspresi reguler yang ditentukan oleh developer pihak ketiga.

Jika pengajar memilih "Coba sekarang" di pop-up seperti yang terlihat pada gambar 3, mereka akan dialihkan ke iframe Penemuan Lampiran add-on Anda.