Classroom-Add-on erstellen

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

In dieser Anleitung legen Sie die Grundlage für die Entwicklung einer Webanwendung und die Veröffentlichung als Classroom-Add-on. In den folgenden Anleitungen wird diese App erweitert.

Im Rahmen dieser Anleitung führen Sie folgende Schritte aus:

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

Anschließend können Sie Ihr Add-on installieren und im 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 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 zur Projekterstellung. 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. Wenn Sie fertig sind, müssen Sie das Projekt auswählen. 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 API-Bibliotheksbrowser 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

Google Workspace Marketplace bietet den Eintrag, über den Nutzer und Administratoren Ihr Add-on installieren. Konfigurieren Sie die App-Konfiguration und den Store-Eintrag 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 Anwendung auf Public oder Private fest.

  • Die öffentliche Einstellung ist für Apps vorgesehen, die später 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. Dies ist ein Zustand vor der Veröffentlichung, in dem Sie Ihr Add-on testen und entwickeln können, bevor Sie es zur Genehmigung einreichen.
  • Die private Einstellung 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. Sie sollten die Sichtbarkeit daher nur 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 unter Installationseinstellungen die Option 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 nach dem sicheren URI für die Einrichtung von Anhängen gefragt. Dies 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 AddOnAttachmentAddOnAttachment festgelegten URIs mit den Methoden courses.*.addOnAttachments.createcourses.*.addOnAttachments.create und den courses.*.addOnAttachments.patchcourses.*.addOnAttachments.patch Methoden zu validieren. Bei der Validierung wird ein wörtlicher String-Präfix-Abgleich durchgeführt. Die Verwendung von Platzhaltern ist derzeit nicht möglich. 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 Sie im vorherigen Schritt auf dem OAuth-Zustimmungsbildschirm angegeben haben.

• Füllen Sie die Felder unter Links für Entwickler entsprechend Ihrer Organisation aus.

Store-Eintrag

Rufen Sie die Seite „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 auf Fertig , um zu speichern.
• Wählen Sie eine Kategorie für Ihr Add-on aus.
• Geben Sie unter Grafische Assets Bilder für die erforderlichen Felder an. Diese können später geändert werden und können vorerst Platzhalter sein.
• Geben Sie unter Support-Links die angeforderten URLs an. Diese können Platzhalter sein, wenn Sie im vorherigen Schritt die Sichtbarkeit der Anwendung auf Privat gesetzt haben.

Wenn Sie im vorherigen Schritt die Sichtbarkeit der Anwendung auf Privat gesetzt haben, klicken Sie auf VERÖFFENTLICHEN. Ihre App ist sofort zur Installation verfügbar. Wenn Sie die Sichtbarkeit der Anwendung auf Öffentlich gesetzt haben, 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 Bereiche festgelegt.

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 ein. Geben Sie unter Autorisierte Domains alle Domains an, in denen Ihre App gehostet wird. Klicken Sie auf SPEICHERN UND FORTFAHREN.

• Fügen Sie alle OAuth-Bereiche hinzu, die Ihre Webanwendung benötigt. Eine ausführliche Erläuterung der Bereiche und ihres Zwecks finden Sie im Leitfaden zur OAuth Konfiguration.

  Sie müssen mindestens einen der folgenden Bereiche anfordern, damit Google den Abfrageparameter login_hint sendet. Eine detailliertere Erläuterung dieses Verhaltens finden Sie in unserem Leitfaden zur OAuth-Konfiguration:

  • 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

  Fügen Sie außerdem alle anderen Google API-Bereiche hinzu, die Ihre App von End nutzern benötigt.

  Klicken Sie auf SPEICHERN UND FORTFAHREN.

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

Prüfen Sie, ob Ihre Einstellungen korrekt sind, und kehren Sie 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 den Eintrag aufzurufen, und wählen Sie dann Installieren aus.

Einfache Webanwendung erstellen

Richten Sie eine Webanwendung mit zwei Routen ein. In den folgenden Anleitungen wird diese Anwendung erweitert. Erstellen Sie 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: zeigt eine Willkommensnachricht und zwei Schaltflächen an: eine zum Schließen des Add-on-iFrames und eine zum Öffnen einer Website in einem neuen Tab.

Wir fügen Schaltflächen hinzu, um Fenster oder den iFrame zu erstellen und zu schließen. Diese zeigen eine Methode, mit der der Nutzer im nächsten Schritt sicher in einen neuen Tab zur Autorisierung weitergeleitet werden kann.

Hilfsskript erstellen

Erstellen Sie ein Verzeichnis static/scripts. 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 Ihren Server. Melden Sie sich dann in Google Classroom als einer Ihrer Lehrer-Testnutzer an. Rufen Sie den Tab Kursarbeit auf und erstellen Sie eine neue Aufgabe. Wählen Sie Ihr Add-on in der Add-on-Auswahl aus. Der 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 anmelden mit Google SSO.