Mengupgrade lampiran Link ke lampiran add-on Classroom

Salah satu cara pengajar menambahkan konten pihak ketiga ke Classroom adalah dengan menempel link sebagai Lampiran link di halaman pembuatan tugas. Untuk mengembangkan hal yang sudah dipahami pengajar, kini Anda dapat mengonfigurasi add-on agar pengajar dapat mengupgrade lampiran Link ke lampiran add-on.

Ringkasan

Jika Anda mengonfigurasi add-on dengan kemampuan ini, pengajar akan diminta untuk mengupgrade link ke lampiran add-on saat menempelkan lampiran Link di halaman pembuatan tugas. Pengajar hanya akan diminta untuk melakukannya jika sudah menginstal add-on.

Setelah pengajar setuju untuk mengupgrade link ke lampiran add-on, iframe Link Upgrade akan diluncurkan dengan parameter kueri berikut:

• courseId
• itemId
• itemType
• addOnToken
• urlToUpgrade
• login_hint (hanya jika pengguna telah mengizinkan aplikasi Anda)

Empat parameter kueri pertama mencerminkan parameter kueri yang diluncurkan di iframe Lampiran Discovery. Parameter kueri urlToUpgrade masih baru dan dapat membantu Anda mengevaluasi cara pembuatan lampiran add-on. Kemudian, Anda dapat menggunakan parameter kueri lainnya untuk memeriksa apakah pengguna sudah login dan memanggil metode CreateAddOnAttachment dari courseWork, courseWorkMaterials, atau announcements berdasarkan nilai itemType. Dalam iframe, Anda dapat menampilkan layar pemuatan untuk menunjukkan kepada pengajar bahwa lampiran add-on sedang dibuat.

Setelah lampiran add-on dibuat, iframe akan ditutup dan pengajar dapat melihat lampiran dalam tugas seperti biasa.

Detail penerapan teknis

Bagian ini menyoroti beberapa detail teknis penting untuk fitur tersebut.

Membaca parameter kueri urlToUpgrade

Parameter kueri urlToUpgrade dienkode dengan URI saat diteruskan pada iframe Link Upgrade. Anda harus mendekode URL untuk mendapatkannya dalam bentuk aslinya. Jika Anda menggunakan JavaScript, misalnya, Anda dapat menggunakan fungsi decodeURIComponent() untuk melakukannya.

Tutup iframe Upgrade Link

Guna memastikan pengalaman pengguna yang optimal untuk fitur ini, kirim postMessage setelah lampiran add-on berhasil dibuat. Tindakan ini akan menutup iframe. Lihat halaman detail implementasi iframe untuk detail selengkapnya.

Detail konfigurasi

Konfigurasi berikut diperlukan untuk mengintegrasikan fitur ini ke dalam add-on Anda:

• URL untuk iframe Upgrade Link: Ini adalah URL yang akan terbuka di iframe saat pengajar setuju untuk melakukan upgrade.

• Pola URL yang harus dideteksi oleh Classroom dan coba diupgrade: Pola URL dapat terdiri dari host dan beberapa awalan jalur.

  • Anda dapat memberikan beberapa pola URL.
  • Jika Anda tidak memberikan awalan jalur apa pun, URL apa pun yang cocok dengan host dapat diupgrade.
  • Hanya URL dengan skema https yang dapat diupgrade.
  • Pola URL tidak boleh berisi localhost.
  • Awalan jalur tidak boleh berisi parameter kueri atau fragmen URL.
  • Awalan jalur dapat mendukung karakter pengganti saat ini, tetapi host tidak dapat:
    • example.com adalah host yang valid, serta /foo dan /bar/*/baz adalah awalan jalur yang valid.
    • example.*.host.com bukan host yang valid.
  • Karakter pengganti di antara komponen awalan jalur hanya cocok dengan satu komponen, dan tidak cocok dengan beberapa komponen yang dipisahkan oleh garis miring. Pertimbangkan pola URL dengan host example.com dan awalan jalur /bar/*/baz:
    • https://example.com/bar/123/baz adalah kecocokan yang valid untuk pola URL.
    • https://example.com/bar/123/baz/456/789 adalah kecocokan yang valid untuk pola URL.
    • https://example.com/bar/123/456/baz bukan kecocokan yang valid untuk pola URL karena karakter pengganti di awalan jalur tidak cocok dengan /123/456/.

Catatan: Karakter pengganti di antara komponen awalan jalur hanya cocok dengan satu komponen.

Proses pengembangan

Kirim URL iframe Upgrade Link dan pola URL untuk add-on pengujian atau produksi Anda dengan mengirim email ke [e-mail].

Pertama-tama, Anda dapat memberikan konfigurasi untuk add-on pribadi dan lingkungan pengujian atau pengembangan yang Anda miliki. Tim Classroom dapat mengaktifkan konfigurasi pengujian ini sebelum mengaktifkan konfigurasi produksi untuk memungkinkan Anda menguji alur di domain demo. Anda akan menerima respons melalui email saat konfigurasi telah diaktifkan. Perhatikan bahwa pola URL yang menggunakan localhost tidak didukung untuk fitur ini.

Penting: Pengguna yang dapat menginstal dan menggunakan add-on Anda dapat mengupgrade link ke lampiran add-on segera setelah konfigurasi diaktifkan oleh tim Classroom. Itulah sebabnya penting untuk menyediakan konfigurasi untuk add-on pengujian Anda terlebih dahulu dalam lingkungan pengujian atau pengembangan sebelum memberikan konfigurasi produksi.

Format email untuk menyertakan hal berikut:

Google Cloud Project number: GCP_PROJECT_NUMBER

Link Upgrade iframe URL: LINK_UPGRADE_IFRAME_URL

URL Patterns:
- Host:HOST_1
- Path prefixes:
  - PATH_PREFIX_1
  - PATH_PREFIX_2

- Host:HOST_2
- Path prefixes:
  - PATH_PREFIX_3
  - PATH_PREFIX_4

// add more hosts and path prefixes as needed

Ganti kode berikut:

• GCP_PROJECT_NUMBER: nomor project Google Cloud yang terkait dengan add-on.
• LINK_UPGRADE_IFRAME_URL URL yang akan terbuka di iframe Link Upgrade.
• HOST_1: host yang harus dideteksi Classroom. Hanya skema https yang didukung.
• PATH_PREFIX_1 dan PATH_PREFIX_2: awalan jalur yang terkait dengan HOST_1 yang harus dideteksi oleh Classroom dan dicoba diupgrade.
• HOST_2: host yang harus dideteksi Classroom. Hanya skema https yang didukung.
• PATH_PREFIX_3dan PATH_PREFIX_4: awalan jalur yang terkait dengan HOST_2 yang harus dideteksi oleh Classroom dan dicoba diupgrade.

Pengalaman pengguna yang direkomendasikan

Berikut adalah saran yang perlu dipertimbangkan saat menerapkan fitur ini.

Menghindari pekerjaan ekstra bagi pengajar

Sebaiknya gunakan iframe untuk memfasilitasi login, jika diperlukan, atau menampilkan indikator pemuatan. Untuk pengalaman pengguna terbaik, pengajar tidak boleh diminta untuk memberikan informasi tambahan apa pun setelah menyetujui untuk mengupgrade link yang ditempelkan ke lampiran add-on. Namun, jika tidak memungkinkan untuk add-on Anda, Anda dapat menggunakan iframe Upgrade Link untuk mengumpulkan informasi tambahan yang diperlukan. iframe juga dapat digunakan untuk memberi tahu pengajar jika upgrade link tidak dapat dilakukan atau jika terjadi error.

Menyertakan pesan error akses yang mudah digunakan

Jika pengajar menempelkan dan mengupgrade link yang tidak dapat mereka akses, tampilkan pesan error yang mudah digunakan dalam iframe agar pengajar mengetahui masalah tersebut. iframe juga dapat digunakan untuk memberi pengajar izin yang sesuai untuk mengakses konten.