Classroom-Add-on erstellen

Dies ist die erste Schritt-für-Schritt-Anleitung für Classroom-Add-ons.

In dieser Schritt-für-Schritt-Anleitung legen Sie den Grundstein dafür, wie Sie eine Webanwendung entwickeln und als Classroom-Add-on veröffentlichen können. Zukünftige Schritt-für-Schritt-Anleitungen erweitern diese App.

Im Verlauf dieser Schritt-für-Schritt-Anleitung führen Sie folgende Schritte aus:

• Erstellen Sie ein neues Google Cloud-Projekt für Ihr Add-on.
• Gerüstbasierte Web-App mit Platzhalterschaltflächen für die Anmeldung erstellen.
• Veröffentlichen Sie einen Google Workspace Marketplace-Store-Eintrag für Ihr Add-on.

Anschließend können Sie das Add-on installieren und im iFrame für Classroom-Add-ons laden.

Voraussetzungen

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 werden über Google Cloud-Projekte gesteuert. Die folgende Anleitung führt Sie durch die Mindestschritte zum Erstellen und Konfigurieren eines neuen Projekts zur Verwendung mit Ihrem Add-on.

Projekt erstellen

Erstellen Sie ein neues Google Cloud-Projekt. Rufen Sie dazu die Seite zur Projekterstellung auf. Sie können einen beliebigen Namen für das neue Projekt angeben. Klicken Sie auf Erstellen.

Es dauert einen Moment, bis das neue Projekt vollständig erstellt ist. Wenn Sie fertig sind, wählen Sie das Projekt aus. Sie können es im Drop-down-Menü für die Projektauswahl oben auf dem Bildschirm auswählen oder oben rechts im Benachrichtigungsmenü auf PROJEKT AUSWÄHLEN klicken.

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

Rufen Sie den Browser der API-Bibliothek auf. Suchen Sie nach Google Workspace Marketplace SDK. Das SDK sollte in der Ergebnisliste angezeigt werden.

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

Google Workspace Marketplace SDK konfigurieren

Im Google Workspace Marketplace finden Sie eine Liste, über die Nutzer und Administratoren Ihr Add-on installieren. Konfigurieren Sie die App-Konfiguration und den Store-Eintrag des Marketplace SDK sowie den OAuth-Zustimmungsbildschirm.

Anwendungskonfiguration

Rufen Sie im Marketplace SDK die Seite App-Konfiguration auf. Gib folgende Informationen an:

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

  • Die öffentliche Einstellung ist für Anwendungen vorgesehen, die irgendwann für Endnutzer veröffentlicht werden. Eine öffentliche Anwendung muss einen Genehmigungsprozess durchlaufen, bevor sie für Endnutzer veröffentlicht wird. Sie können jedoch Nutzer angeben, die die Anwendung als Entwurf installieren und testen dürfen. Dies ist ein Status vor der Veröffentlichung, in dem du dein Add-on testen und entwickeln kannst, bevor du es zur Genehmigung einreichst.
  • Die Einstellung „Privat“ eignet sich für interne Tests und die Entwicklung. Eine private Anwendung kann nur von Nutzern in derselben Domain installiert werden, in der das Projekt erstellt wurde. Sie sollten daher die Sichtbarkeit nur dann auf „Privat“ setzen, 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 (Installationseinstellungen) auf Admin Only install fest, wenn Sie die Installation auf Domainadministratoren beschränken möchten.

• Wählen Sie unter App-Integration die Option Classroom-Add-on aus. Sie werden zur Eingabe des secure-URI zur Einrichtung des Anhangs aufgefordert. Dies ist die URL, die geladen wird, wenn ein Nutzer Ihr Add-on öffnet. Für diese Schritt-für-Schritt-Anleitung sollte https://<your domain>/addon-discovery verwendet werden.

• Die zulässigen URI-Präfixe für Anhänge werden verwendet, um die in AddOnAttachment festgelegten URIs mit den Methoden courses.*.addOnAttachments.create und courses.*.addOnAttachments.patch zu validieren. Die Validierung ist eine literale Stringpräfixübereinstimmung und lässt derzeit die Verwendung von Platzhaltern nicht 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 im vorherigen Schritt auf Ihrem OAuth-Zustimmungsbildschirm angegeben wurden.

• Füllen Sie die Felder unter Entwicklerlinks entsprechend für Ihre Organisation aus.

Store-Eintrag

Gehen Sie im Marketplace SDK zur Seite Store-Eintrag. Gib folgende 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 Namen und Beschreibungen für die Anwendung an. Diese werden auf der Seite des Google Workspace Marketplace-Store-Eintrags Ihres Add-ons angezeigt. Klicken Sie zum Speichern auf Fertig.
• Wählen Sie eine Kategorie für das Add-on aus.
• Stellen Sie unter Grafikinhalte Bilder für die Pflichtfelder bereit. Diese können später geändert werden und vorerst Platzhalter sein.
• Geben Sie unter Supportlinks die angeforderten URLs an. Das können Platzhalter sein, wenn Sie die App-Sichtbarkeit im vorherigen Schritt auf Privat gesetzt haben.

Wenn Sie die Sichtbarkeit der App im vorherigen Schritt auf Privat gesetzt haben, klicken Sie auf VERÖFFENTLICHEN. Die Anwendung ist sofort zur Installation verfügbar. Wenn Sie die App-Sichtbarkeit auf Öffentlich setzen, fügen Sie im Bereich Entwurftester für alle Testnutzer E-Mail-Adressen hinzu und klicken Sie auf Entwurf speichern.

OAuth-Zustimmungsbildschirm

Der OAuth-Zustimmungsbildschirm wird angezeigt, wenn Nutzer Ihre App zum ersten Mal autorisieren. Er fordert sie auf, Ihrer App den Zugriff auf ihre personenbezogenen Daten und Kontoinformationen gemäß den von Ihnen aktivierten Bereichen zu erlauben.

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

• Setzen Sie Nutzertyp auf Extern. Klicken Sie auf Erstellen.
• Geben Sie auf der nächsten Seite die erforderlichen App-Details und Kontaktdaten an. Geben Sie unter Autorisierte Domains alle Domains an, auf denen Ihre Anwendung gehostet wird. Klicken Sie auf SPEICHERN UND FORTFAHREN.

• Fügen Sie alle OAuth-Bereiche hinzu, die für Ihre Webanwendung erforderlich sind. Im OAuth-Konfigurationsleitfaden finden Sie eine ausführliche Beschreibung der Bereiche und ihres Zwecks.

  Sie müssen mindestens einen der folgenden Bereiche anfordern, damit Google den Abfrageparameter login_hint senden kann. Eine ausführlichere Erläuterung dieses Verhaltens finden Sie in unserem OAuth-Konfigurationsleitfaden:

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

  Die folgenden Bereiche gelten nur für Classroom-Add-ons:

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

  Schließen Sie auch alle anderen Google API-Bereiche ein, die Ihre Anwendung 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.

Bestätigen Sie, dass Ihre Einstellungen korrekt sind, und kehren Sie dann zum Dashboard zurück.

Add-on installieren

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

Einfache Webanwendung erstellen

Gebaute Webanwendung mit zwei Routen einrichten In zukünftigen Schritt-für-Schritt-Anleitungen wird diese Anwendung erweitert. Erstellen Sie vorerst nur eine Landingpage für das Add-on /addon-discovery und eine simulierte 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: Es werden 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.

Beachten Sie, dass wir Schaltflächen zum Erstellen und Schließen von Fenstern oder dem iFrame hinzufügen. Darin wird eine Methode gezeigt, mit der der Nutzer in der nächsten Schritt-für-Schritt-Anleitung sicher in einen neuen Tab zur Autorisierung weitergeleitet werden kann.

Dienstprogrammskript erstellen

Erstellen Sie ein static/scripts-Verzeichnis. Erstellen Sie eine neue Datei addon-utils.js. Fügen Sie die folgenden beiden 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 als einer Ihrer Teacher-Testnutzer in Google Classroom an. Gehen Sie zum Tab Kursaufgaben und erstellen Sie eine neue Aufgabe. Wählen Sie das Add-on in der Auswahl Add-ons aus. Der iFrame wird geöffnet und das Add-on lädt den Einrichtungs-URI für Anhänge, den Sie auf der Seite App-Konfiguration des Marketplace SDK angegeben haben.

Glückwunsch! Sie können jetzt mit dem nächsten Schritt fortfahren: Nutzer mit der Einmalanmeldung (SSO) von Google anmelden.