Classroom-Add-on erstellen

Dies ist die erste Anleitung in der Reihe von Anleitungen zu Classroom-Add-ons.

In dieser Anleitung legen Sie den Grundstein für die Entwicklung einer Webanwendung und die Veröffentlichung als Classroom-Add-on. Die zukünftigen Schritte zur Erweiterung dieser App.

In dieser Anleitung führen Sie die folgenden Schritte aus:

• Erstellen Sie ein neues Google Cloud-Projekt für Ihr Add-on.
• Erstellen Sie das Grundgerüst für eine Web-App mit Platzhalter-Anmeldeschaltflächen.
• Veröffentlichen Sie einen Google Workspace Marketplace-Eintrag für Ihr Add-on.

Anschließend können Sie Ihr Add-on installieren und in das Classroom-Add-ons-iFrame laden.

Vorbereitung

Wählen Sie eine Sprache aus, um die entsprechenden Voraussetzungen zu sehen:

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

Google Cloud-Projekt einrichten

Der Zugriff auf die Classroom API und die erforderlichen Authentifizierungsmethoden wird über Google Cloud-Projekte gesteuert. Die folgende Anleitung führt Sie durch die erforderlichen Mindestschritte zum Erstellen und Konfigurieren eines neuen Projekts für die Verwendung mit Ihrem Add-on.

Projekt erstellen

Erstellen Sie ein neues Google Cloud-Projekt auf der Seite zum Erstellen von Projekten. Sie können einen beliebigen Namen für das neue Projekt angeben. Klicken Sie auf Erstellen.

Es dauert einige Augenblicke, bis das neue Projekt vollständig erstellt ist. Wählen Sie das Projekt aus. Sie können es oben auf dem Bildschirm im Drop-down-Menü zur Projektauswahl auswählen oder rechts oben im Benachrichtigungsmenü auf PROJEKT AUSWÄHLEN klicken.

Google Workspace Marketplace SDK an das Google Cloud-Projekt anhängen

Rufen Sie die API-Bibliothek auf. Suchen Sie nach Google Workspace Marketplace SDK. Das SDK sollte in der Liste der Ergebnisse angezeigt werden.

Wählen Sie die Karte „Google Workspace Marketplace SDK“ aus und klicken Sie dann auf Aktivieren.

Google Workspace Marketplace SDK konfigurieren

Der Google Workspace Marketplace bietet das Angebot, über das Nutzer und Administratoren Ihr Add-on installieren. Konfigurieren Sie die App-Konfiguration und den Eintrag im Store des Marketplace SDK sowie den OAuth-Zustimmungsbildschirm, um fortzufahren.

Anwendungskonfiguration

Rufen Sie die Seite App-Konfiguration des Marketplace SDK auf. Geben Sie die folgenden Informationen an:

• Legen Sie die Sichtbarkeit der App auf Public oder Private fest.

  • Die öffentliche Einstellung ist für Apps vorgesehen, die letztendlich für Endnutzer veröffentlicht werden. Eine öffentliche App muss einen Genehmigungsprozess durchlaufen, bevor sie für Endnutzer veröffentlicht wird. Sie können jedoch Nutzer angeben, die sie als Entwurf installieren und testen können. In diesem Status können Sie Ihr Add-on testen und entwickeln, bevor Sie es zur Genehmigung einreichen.
  • Die Einstellung „Privat“ eignet sich für interne Tests und die Entwicklung. Eine private App kann nur von Nutzern in derselben Domain installiert werden, in der das Projekt erstellt wurde. Daher sollten Sie die Sichtbarkeit nur dann auf „Privat“ festlegen, wenn das Projekt in einer Domain mit einem Google Workspace for Education-Abo erstellt wurde. Andernfalls können Ihre Testnutzer keine Classroom-Add-ons starten.

• Legen Sie Installation Settings auf Admin Only install fest, wenn Sie die Installation auf Domainadministratoren beschränken möchten.

• Wählen Sie unter App-Einbindung die Option Classroom-Add-on aus. Sie werden aufgefordert, die sichere Attachment Setup URI anzugeben. Das ist die URL, die geladen werden soll, wenn ein Nutzer Ihr Add-on öffnet. Für diese Anleitung sollte dies https://<your domain>/addon-discovery sein.

• Die zulässigen Präfixe für Anhangs-URIs werden verwendet, um die in AddOnAttachment festgelegten URIs mit den Methoden courses.*.addOnAttachments.create und courses.*.addOnAttachments.patch zu validieren. Die Validierung ist ein exakter Abgleich des String-Präfixes und lässt derzeit keine Verwendung von Platzhaltern zu. Fügen Sie mindestens die Stammdomain Ihres Inhaltsservers hinzu, z. B. https://localhost:5000/ oder https://cdn.myedtech.com/.

• Fügen Sie dieselben OAuth-Bereiche hinzu, die in Ihrem OAuth-Zustimmungsbildschirm im vorherigen Schritt angegeben sind.

• Füllen Sie die Felder unter Entwicklerlinks entsprechend den Anforderungen Ihrer Organisation aus.

Store-Eintrag

Rufen Sie die Seite Store Listing (Play Store-Eintrag) des Marketplace SDK auf. Geben Sie die folgenden Informationen an:

• Fügen Sie unter App-Details eine Sprache hinzu oder maximieren Sie das Drop-down-Menü neben der bereits aufgeführten Sprache. Geben Sie einen Anwendungsnamen und Beschreibungen an. Diese werden auf der Store-Eintragsseite Ihres Add-ons im Google Workspace Marketplace angezeigt. Klicken Sie zum Speichern auf Fertig.
• Wählen Sie eine Kategorie für Ihr Add-on aus.
• Geben Sie unter Grafikinhalte Bilder für die Pflichtfelder an. Diese können später geändert werden und können vorerst Platzhalter sein.
• Geben Sie unter Support-Links die angeforderten URLs an. Das können Platzhalter sein, wenn Sie im vorherigen Schritt die App-Sichtbarkeit auf Privat festgelegt haben.

Wenn Sie im vorherigen Schritt die App-Sichtbarkeit auf Privat festgelegt haben, klicken Sie auf VERÖFFENTLICHEN. Ihre App ist dann sofort zur Installation verfügbar. Wenn Sie die App-Sichtbarkeit auf Öffentlich festlegen, fügen Sie im Bereich Entwurfstester E‑Mail-Adressen für alle Testnutzer hinzu und klicken Sie auf Entwurf speichern.

OAuth-Zustimmungsbildschirm

Der OAuth-Zustimmungsbildschirm wird angezeigt, wenn Nutzer Ihre App zum ersten Mal autorisieren. Sie werden aufgefordert, Ihrer App den Zugriff auf ihre persönlichen Daten und Kontoinformationen zu erlauben, wie durch die von Ihnen aktivierten Bereiche festgelegt.

Rufen Sie die Seite zum Erstellen des OAuth-Zustimmungsbildschirms auf. Geben Sie die folgenden Informationen an:

• Legen Sie für Nutzertyp den Wert Extern fest. Klicken Sie auf Erstellen.
• Geben Sie auf der nächsten Seite die erforderlichen App-Details und Kontaktdaten ein. Geben Sie unter Autorisierte Domains alle Domains an, auf denen Ihre App gehostet wird. Klicken Sie auf SPEICHERN UND FORTFAHREN.

• Fügen Sie alle OAuth-Bereiche hinzu, die für Ihre Webanwendung erforderlich sind. Eine ausführliche Erläuterung der Bereiche und ihres Zwecks finden Sie im OAuth-Konfigurationsleitfaden.

  Sie müssen mindestens einen der folgenden Bereiche anfordern, damit Google den Abfrageparameter login_hint sendet. Eine detailliertere Erklärung dieses Verhaltens finden Sie in unserem OAuth-Konfigurationsleitfaden:

  • https://www.googleapis.com/auth/userinfo.email (bereits enthalten)
  • https://www.googleapis.com/auth/userinfo.profile (bereits enthalten)

  Die folgenden Bereiche sind spezifisch für Classroom-Add-ons:

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

  Geben Sie auch alle anderen Google API-Bereiche an, die Ihre App von Endnutzern benötigt.

  Klicken Sie auf SPEICHERN UND FORTFAHREN.

• Listen Sie die E‑Mail-Adressen aller Testkonten auf der Seite Testnutzer auf. Klicken Sie auf SPEICHERN UND FORTFAHREN.

Prüfe, ob deine Einstellungen korrekt sind, und kehre dann zum Dashboard zurück.

Add-on installieren

Sie können Ihr Add-on jetzt über den Link oben auf der Seite Store-Eintrag des Marketplace SDK installieren. Klicken Sie oben auf der Seite auf Im Marketplace ansehen, um das Angebot aufzurufen, und wählen Sie dann Installieren aus.

Einfache Webanwendung erstellen

Richten Sie eine einfache Webanwendung mit zwei Routen ein. In zukünftigen Schritten werden wir diese Anwendung erweitern. Erstellen Sie daher vorerst nur eine Landingpage für das Add-on /addon-discovery und eine Mock-Indexseite / für unsere „Unternehmenswebsite“.

Implementieren Sie diese beiden Endpunkte:

• /: Zeigt eine Willkommensnachricht und eine Schaltfläche zum Schließen des aktuellen Tabs und des Add-on-iFrames an.
• /addon-discovery: Hier wird eine Willkommensnachricht und zwei Schaltflächen angezeigt: eine zum Schließen des Add-on-iFrames und eine zum Öffnen einer Website in einem neuen Tab.

Wir fügen Schaltflächen zum Erstellen und Schließen von Fenstern oder dem iFrame hinzu. In diesen Beispielen wird eine Methode zum sicheren Öffnen eines neuen Tabs für die Autorisierung im nächsten Walkthrough gezeigt.

Hilfsskript erstellen

Erstellen Sie ein static/scripts-Verzeichnis. Erstellen Sie eine neue Datei mit dem Namen addon-utils.js. Fügen Sie die folgenden zwei Funktionen hinzu.

/**
 *   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',
  }, '*');
};

Routen erstellen

Implementieren Sie die Endpunkte /addon-discovery und /.

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";
}

Add-on testen

Starten Sie den Server. Melden Sie sich dann in Google Classroom als einer Ihrer Lehrkraft-Testnutzer an. Gehen Sie zum Tab Kursaufgaben und erstellen Sie eine neue Aufgabe. Wählen Sie Ihr Add‑on in der Auswahl Add‑ons aus. Das iFrame wird geöffnet und das Add‑on lädt den URI für die Einrichtung von Anhängen, den Sie auf der Seite App-Konfiguration des Marketplace SDK angegeben haben.

Glückwunsch! Sie können mit dem nächsten Schritt fortfahren: Nutzer mit Google-SSO anmelden.