Membuat add-on Classroom

Ini adalah panduan pertama dalam seri panduan add-on Classroom.

Dalam panduan ini, Anda akan membangun dasar untuk mengembangkan aplikasi web dan memublikasikannya sebagai add-on Classroom. Langkah panduan mendatang memperluas aplikasi ini.

Dalam panduan ini, Anda akan menyelesaikan hal-hal berikut:

• Buat project Google Cloud baru untuk add-on Anda.
• Membuat aplikasi web kerangka dengan tombol login placeholder.
• Publikasikan Listingan Play Store Google Workspace Marketplace untuk add-on Anda.

Setelah selesai, Anda dapat menginstal add-on dan memuatnya di iframe add-on Classroom.

Prasyarat

Pilih bahasa untuk melihat prasyarat yang sesuai:

python -m ensurepip --upgrade

python3 -m venv .classroom-addon-env
source .classroom-addon-env/bin/activate

cd flask/01-basic-app
pip install -r requirements.txt

npm install

java --version
./mvnw --version

java -version
mvnw.cmd --version

Menyiapkan project Google Cloud

Akses ke Classroom API dan metode autentikasi yang diperlukan dikontrol oleh project Google Cloud. Petunjuk berikut akan memandu Anda melakukan langkah-langkah minimum untuk membuat dan mengonfigurasi project baru yang akan digunakan dengan add-on.

Mulai membuat project

Buat project Google Cloud baru dengan mengunjungi halaman pembuatan project. Anda dapat memberikan nama apa pun untuk project baru. Klik Create.

Perlu waktu beberapa saat sampai project baru tersebut dibuat sepenuhnya. Setelah selesai, pastikan untuk memilih project; Anda dapat memilihnya di menu drop-down pemilih project di bagian atas layar, atau klik SELECT PROJECT dalam menu notifikasi di kanan atas.

Melampirkan Google Workspace Marketplace SDK ke project Google Cloud

Buka browser Library API. Telusuri Google Workspace Marketplace SDK. Anda akan melihat SDK muncul dalam daftar hasil.

Pilih kartu Google Workspace Marketplace SDK, lalu klik Enable.

Mengonfigurasi Google Workspace Marketplace SDK

Google Workspace Marketplace menyediakan listingan tempat pengguna dan administrator menginstal add-on Anda. Konfigurasikan Konfigurasi Aplikasi dan Listingan Toko Marketplace SDK serta Layar Izin OAuth untuk melanjutkan.

Konfigurasi Aplikasi

Buka halaman Konfigurasi Aplikasi SDK Marketplace. Berikan informasi berikut:

• Tetapkan Visibilitas Aplikasi ke Public atau Private.

  • Setelan publik ditujukan untuk aplikasi yang pada akhirnya akan dirilis ke pengguna akhir. Aplikasi publik harus menjalani proses persetujuan sebelum dipublikasikan ke pengguna akhir, tetapi Anda dapat menentukan pengguna yang dapat menginstal dan mengujinya sebagai Draf. Ini adalah status prapublikasi yang akan memungkinkan Anda menguji dan mengembangkan add-on sebelum mengirimkannya untuk mendapatkan persetujuan.
  • Setelan pribadi cocok untuk pengujian dan pengembangan internal. Aplikasi pribadi hanya dapat diinstal oleh pengguna di domain yang sama dengan tempat project dibuat. Oleh karena itu, Anda sebaiknya menyetel visibilitas ke pribadi hanya jika project dibuat di domain dengan langganan Google Workspace for Education. Jika tidak, pengguna uji coba Anda tidak akan dapat meluncurkan add-on Classroom.

• Setel Setelan Penginstalan ke Admin Only install jika ingin membatasi penginstalan hanya untuk administrator domain.

• Di bagian Integrasi Aplikasi, pilih add-on Classroom. Anda akan diminta untuk memasukkan URI Penyiapan Lampiran yang aman; ini adalah URL yang diharapkan akan dimuat saat pengguna membuka add-on Anda. Untuk tujuan panduan ini, nilainya harus berupa https://<your domain>/addon-discovery.

• Awalan URI Lampiran yang Diizinkan digunakan untuk memvalidasi URI yang ditetapkan di AddOnAttachment menggunakan metode courses.*.addOnAttachments.create dan courses.*.addOnAttachments.patch. Validasi adalah kecocokan awalan string literal dan saat ini tidak mengizinkan penggunaan karakter pengganti. Tambahkan setidaknya domain root server konten Anda, seperti https://localhost:5000/ atau https://cdn.myedtech.com/.

• Tambahkan Cakupan OAuth yang sama seperti yang diberikan di layar izin OAuth Anda pada langkah sebelumnya.

• Lengkapi kolom yang sesuai untuk organisasi Anda di bagian Link Developer.

Listingan Store

Buka halaman Listingan Play Store SDK Marketplace. Berikan informasi berikut:

• Di bagian App Details, tambahkan bahasa atau luaskan menu drop-down di samping bahasa yang sudah tercantum. Berikan Nama Aplikasi dan deskripsi; keduanya muncul di halaman listingan Play Store Google Workspace Marketplace add-on Anda. Klik Selesai untuk menyimpan.
• Pilih Kategori untuk add-on Anda.
• Di bagian Aset Grafik, berikan gambar untuk kolom yang wajib diisi. Nama ini dapat diubah nanti, dan dapat menjadi placeholder untuk saat ini.
• Di bagian Link Dukungan, berikan URL yang diminta. URL ini dapat menjadi placeholder jika Anda menetapkan Visibilitas Aplikasi ke Pribadi pada langkah sebelumnya.

Jika Anda menetapkan Visibilitas Aplikasi ke Pribadi pada langkah sebelumnya, klik PUBLIKASIKAN; aplikasi Anda akan segera tersedia untuk diinstal. Jika Anda menetapkan Visibilitas Aplikasi ke Publik, tambahkan alamat email di area Penguji Draf untuk setiap pengguna pengujian dan klik Simpan Draf.

Layar Izin OAuth

Layar Izin OAuth muncul saat pengguna pertama kali memberikan otorisasi pada aplikasi Anda. Layar ini akan meminta mereka untuk mengizinkan aplikasi Anda mengakses informasi pribadi dan akun mereka, seperti yang ditentukan oleh cakupan yang Anda aktifkan.

Buka halaman pembuatan Layar izin OAuth. Berikan informasi berikut:

• Tetapkan User Type ke External. Klik Buat.
• Di halaman berikutnya, isi detail aplikasi dan informasi kontak yang diperlukan. Berikan domain yang menghosting aplikasi Anda di bagian Domain yang Diotorisasi. Klik SIMPAN DAN LANJUTKAN.

• Tambahkan Cakupan OAuth yang diperlukan aplikasi web Anda. Lihat panduan konfigurasi OAuth untuk pembahasan mendalam tentang cakupan dan tujuannya.

  Anda harus meminta setidaknya salah satu cakupan berikut agar Google dapat mengirimkan parameter kueri login_hint. Penjelasan yang lebih mendetail tentang perilaku ini tersedia di panduan konfigurasi OAuth:

  • https://www.googleapis.com/auth/userinfo.email (sudah disertakan)
  • https://www.googleapis.com/auth/userinfo.profile (sudah disertakan)

  Cakupan berikut khusus untuk add-on Classroom:

  • https://www.googleapis.com/auth/classroom.addons.teacher
  • https://www.googleapis.com/auth/classroom.addons.student

  Sertakan juga cakupan Google API lain yang diperlukan aplikasi Anda dari pengguna akhir.

  Klik SIMPAN DAN LANJUTKAN.

• Tampilkan daftar alamat email akun pengujian di halaman Pengguna pengujian. Klik SIMPAN DAN LANJUTKAN.

Pastikan setelan Anda sudah benar, lalu kembali ke dasbor.

Instal add-on

Sekarang Anda dapat menginstal add-on menggunakan link di bagian atas halaman Listingan Play Store Marketplace SDK. Klik URL Aplikasi di bagian atas halaman untuk melihat listingan, lalu pilih Instal.

Membangun aplikasi web dasar

Siapkan aplikasi web kerangka dengan dua rute. Langkah panduan di masa mendatang akan memperluas aplikasi ini, jadi untuk saat ini cukup buat halaman landing untuk add-on /addon-discovery dan halaman indeks tiruan / untuk "situs perusahaan" kami.

Terapkan kedua endpoint ini:

• /: menampilkan pesan selamat datang dan tombol untuk menutup tab saat ini dan iframe add-on.
• /addon-discovery: menampilkan pesan selamat datang dan dua tombol: satu untuk menutup iframe add-on dan satu lagi untuk membuka situs di tab baru.

Perhatikan bahwa kami menambahkan tombol untuk membuat dan menutup jendela atau iframe. Cara ini menunjukkan metode untuk mengarahkan pengguna ke tab baru dengan aman untuk otorisasi dalam panduan berikutnya.

Membuat skrip utilitas

Buat direktori static/scripts. Buat file baru addon-utils.js. Tambahkan dua fungsi berikut.

/**
 *   Opens a given destination route in a new window. This function uses
 *   window.open() so as to force window.opener to retain a reference to the
 *   iframe from which it was called.
 *   @param {string} destinationURL The endpoint to open, or "/" if none is
 *   provided.
 */
function openWebsiteInNewTab(destinationURL = '/') {
  window.open(destinationURL, '_blank');
}

/**
 *   Close the iframe by calling postMessage() in the host Classroom page. This
 *   function can be called directly when in a Classroom add-on iframe.
 *
 *   Alternatively, it can be used to close an add-on iframe in another window.
 *   For example, if an add-on iframe in Window 1 opens a link in a new Window 2
 *   using the openWebsiteInNewTab function, you can call
 *   window.opener.closeAddonIframe() from Window 2 to close the iframe in Window
 *   1.
 */
function closeAddonIframe() {
  window.parent.postMessage({
    type: 'Classroom',
    action: 'closeIframe',
  }, '*');
};

Membuat rute

Implementasikan endpoint /addon-discovery dan /.

from flask import Flask
import config

app = Flask(__name__)
app.config.from_object(config.Config)

# Load other module script files. This import statement refers to the
# 'routes.py' file described below.
from webapp import routes

from webapp import app
import flask

@app.route("/")
def index():
    return flask.render_template("index.html",
                                message="You've reached the index page.")

@app.route("/classroom-addon")
def classroom_addon():
    return flask.render_template(
        "addon-discovery.html",
        message="You've reached the addon discovery page.")

import os

class Config(object):
    # Note: A secret key is included in the sample so that it works.
    # If you use this code in your application, replace this with a truly secret
    # key. See https://flask.palletsprojects.com/quickstart/#sessions.
    SECRET_KEY = os.environ.get(
        'SECRET_KEY') or "REPLACE ME - this value is here as a placeholder."

from webapp import app

if __name__ == "__main__":
    # Run the application over HTTPs with a locally stored certificate and key.
    # Defaults to https://localhost:5000.
    app.run(
        host="localhost",
        ssl_context=("localhost.pem", "localhost-key.pem"),
        debug=True)

const websiteRouter = require('./routes/index');
const addonRouter = require('./routes/classroom-addon');

app.use('/', websiteRouter);
app.use('/addon-discovery', addonRouter);

router.get('/', function (req, res, next) {
  res.render('index', {
    title: 'Education Technology',
    message: 'Welcome to our website!'
  });
});

router.get('/', function (req, res, next) {
  res.render('discovery', {
    layout: 'addon.hbs',
    title: 'Education Technology Classroom add-on',
    message: `Welcome.`
  });
});

import org.springframework.web.bind.annotation.GetMapping;

@org.springframework.stereotype.Controller
public class Controller {

/** Returns the index page that will be displayed when the add-on opens in a
*   new tab.
*   @param model the Model interface to pass error information that's
*   displayed on the error page.
*   @return the index page template if successful, or the onError method to
*   handle and display the error message.
*/
@GetMapping(value = {"/"})
public String index(Model model) {
  try {
    return "index";
  } catch (Exception e) {
    return onError(e.getMessage(), model);
  }
}

/** Returns the add-on discovery page that will be displayed when the iframe
*   is first opened in Classroom.
*   @param model the Model interface to pass error information that's
*   displayed on the error page.
*   @return the addon-discovery page.
*/
@GetMapping(value = {"/addon-discovery"})
public String addon_discovery(Model model) {
  try {
    return "addon-discovery";
  } catch (Exception e) {
    return onError(e.getMessage(), model);
  }
}

/** Handles application errors.
*   @param errorMessage message to be displayed on the error page.
*   @param model the Model interface to pass error information to display on
*   the error page.
*   @return the error page.
*/
@GetMapping(value = {"/error"})
public String onError(String errorMessage, Model model) {
  model.addAttribute("error", errorMessage);
  return "error";
}

Menguji add-on

Luncurkan server Anda. Selanjutnya, login ke Google Classroom sebagai salah satu pengguna uji coba Teacher. Pilih tab Tugas Kelas dan buat Tugas baru. Pilih add-on dari pemilih Add-on. iframe akan terbuka dan add-on memuat URI Penyiapan Lampiran yang Anda tentukan di halaman Konfigurasi Aplikasi SDK Marketplace.

Selamat! Anda siap melanjutkan ke langkah berikutnya: membuat pengguna login dengan SSO Google.