Details zu iFrames und Suchparametern

Classroom-Add-ons werden in einem iFrame geladen, um Endnutzern eine nahtlose und komfortable Nutzererfahrung zu bieten. Es gibt fünf verschiedene iFrame-Typen. Eine Übersicht über Zweck und Aussehen der einzelnen iFrames finden Sie auf den iFrame-Seiten im Verzeichnis „Nutzerpfade“.

Wichtig: Wenn ein Nutzer eine Ihrer Add-on-Ansichten öffnet, erhalten Sie eine Vielzahl von Informationen. Mit diesen Informationen können Sie den Anhang identifizieren, die Anmeldedaten und die Rolle des Nutzers bestätigen und bestimmte API-Anfragen ausführen.

Sicherheitsrichtlinien für iFrames

Entwickler müssen die Best Practices der Branche befolgen, um ihre iFrames zu schützen. Sie sollten jedoch auch bestimmte API-Interaktionen in Ihren Nutzerpfad einbeziehen, um zu bestätigen, dass Sie gültige Anmeldedaten haben und die Rolle des Nutzers im Kurs korrekt identifizieren können.

Serveranwendung konfigurieren

Zum Schutz des iFrames empfehlen wir die folgenden Serverkonfigurationen:

• HTTPS ist erforderlich. Wir empfehlen dringend, TLS 1.2 oder höher zu verwenden und HTTP Strict Transport Security (HSTS) zu aktivieren. Weitere Informationen finden Sie in diesem MDN Artikel zu Strict Transport Security.
• Aktivieren Sie Strict Content Security Policy (Strict CSP). Weitere Informationen finden Sie in diesem OWASP-Artikel und in diesem MDN-Artikel zu Content Security Policy.
• Aktivieren Sie das Attribut „Secure“ für Cookies. Weitere Informationen finden Sie im Attribut „HttpOnly“ und in diesem MDN-Artikel zu Cookies.

Suchparameter

Die iFrames übergeben wichtige Informationen als Suchparameter an das Add-on. Es gibt zwei Kategorien von Parametern: anhangsbezogene und anmeldebezogene Parameter.

Anhangsbezogene Parameter

Die anhangsbezogenen Parameter liefern dem Add-on Informationen zum Kurs, zur Aufgabe, zum Add-on-Anhang, zur Abgabe des Schülers/Studenten und zu einem Autorisierungstoken.

Kurs-ID

Der Wert courseId ist eine ID für den Kurs.

In allen iFrames enthalten.

Artikel-ID

Der Wert itemId ist eine ID für die Announcement, CourseWork oder CourseWorkMaterial, an die dieser Anhang angehängt ist.

In allen iFrames enthalten.

Elementtyp

Der Wert itemType gibt den Ressourcentyp an, an den dieser Anhang angehängt ist. Der übergebene Stringwert ist einer der folgenden: "announcements", "courseWork" oder "courseWorkMaterials".

In allen iFrames enthalten.

Anhangs-ID

Der Wert attachmentId ist eine ID für den Anhang.

In den iFrames teacherViewUri, studentViewUri und studentWorkReviewUri enthalten.

ID der abgegebenen Aufgabe

Der Wert submissionId ist eine ID für die Arbeit des Schülers/Studenten. Er sollte jedoch in Kombination mit attachmentId verwendet werden, um die Arbeit des Schülers/Studenten für eine bestimmte Aufgabe zu identifizieren.

In studentWorkReviewUri enthalten.

Hinweis: Sie können einen zusammengesetzten Schlüssel aus submissionId und attachmentId verwenden, um die Arbeit des Schülers/Studenten zu identifizieren, falls derselbe Anhang demselben Schüler/Studenten in verschiedenen Kursen zugewiesen ist. Weitere Informationen finden Sie unter Kopierte Inhalte.

Add-on-Token

Der Wert addOnToken ist ein Autorisierungstoken, mit dem addOnAttachments.create-Aufrufe ausgeführt werden, um das Add-on zu erstellen.

Im iFrame „Anhangssuche“ und im iFrame „Link-Upgrade “ enthalten.

URL für Upgrade

Das Vorhandensein des Werts urlToUpgrade bedeutet, dass die Lehrkraft einen Link-Anhang in die Aufgabe eingefügt und zugestimmt hat, ihn in einen Add-on-Anhang zu konvertieren. Wenn Sie diese Funktion noch nicht konfiguriert haben, finden Sie in der Anleitung zum Konvertieren von Links in Add-on Anhänge weitere Informationen.

Im iFrame „Link-Upgrade“ enthalten.

Anmeldebezogene Parameter

Der Suchparameter login_hint enthält Informationen zum Classroom-Nutzer, der die Add-on-Webseite besucht. Dieser Suchparameter wird in der src-URL des iFrames angegeben. Er wird gesendet, wenn der Nutzer Ihr Add-on bereits verwendet hat, um die Anmeldung für Endnutzer zu vereinfachen. Sie müssen diesen Suchparameter in Ihrer Add-on-Implementierung verarbeiten.

Anmeldehinweis

login_hint ist eine eindeutige ID für das Google-Konto des Nutzers. Nachdem sich der Nutzer zum ersten Mal in Ihrem Add-on angemeldet hat, wird der Parameter login_hint bei jedem weiteren Besuch Ihres Add-ons durch denselben Nutzer übergeben.

Es gibt zwei mögliche Verwendungszwecke für den Parameter login_hint:

1. Übergeben Sie den Wert login_hint während des Authentifizierungsprozesses, damit der Nutzer seine Anmeldedaten nicht eingeben muss, wenn das Anmeldedialogfeld angezeigt wird. Der Nutzer wird nicht automatisch angemeldet.
2. Nachdem sich der Nutzer angemeldet hat, können Sie mit diesem Parameter den Wert mit allen Nutzern vergleichen, die sich möglicherweise bereits in Ihrem Add-on angemeldet haben. Wenn Sie eine Übereinstimmung finden, können Sie den Nutzer angemeldet lassen und die Anmeldung überspringen. Wenn der Parameter mit keinem Ihrer angemeldeten Nutzer übereinstimmt, fordern Sie den Nutzer auf, sich mit einer Google-Anmeldeschaltfläche anzumelden.

In allen iFrames enthalten.

Hinweis: Weitere Informationen zur Implementierung des login_hint Parameters und zum Anmeldeprozess finden Sie auf den Seiten zu SSO, reibungsfreier Anmeldung und wiederholten Anmeldungen.

iFrame „Anhangssuche“

Dimension	Beschreibung
Erforderlich	Ja
URI	In den Add-on-Metadaten angegeben
Abfrageparameter	courseId, itemId, itemType, addOnToken und login_hint.
Höhe	80% der Fensterhöhe minus 60 Pixel für den oberen Header
Breite	Maximal 1.600 Pixel 90% der Fensterbreite, wenn das Fenster <= 600 Pixel breit ist 80% der Fensterbreite, wenn das Fenster > 600 Pixel breit ist

Beispielszenario für die Anhangssuche

1. Ein Classroom-Add-on ist im Google Workspace Marketplace mit dem URI für die Anhangssuche https://example.com/addon registriert.
2. Eine Lehrkraft installiert dieses Add-on und erstellt eine neue Ankündigung, Aufgabe oder ein neues Material in einem ihrer Kurse. Beispiel: itemId=234, itemType=courseWork und courseId=123.
3. Beim Konfigurieren dieses Elements wählt die Lehrkraft das neu installierte Add-on als Anhang aus.
4. Classroom erstellt einen iFrame, dessen `src`-URL auf https://example.com/addon?courseId=123&itemId=234&itemType=courseWork&addOnToken=456 festgelegt ist.
   1. Die Lehrkraft wählt im iFrame einen Anhang aus.
5. Nach der Auswahl des Anhangs sendet das Add-on eine postMessage an Classroom, um den iFrame zu schließen.

iFrames „teacherViewUri“ und „studentViewUri“

Dimension	Beschreibung
Erforderlich	Ja
URI	teacherViewUri oder studentViewUri
Abfrageparameter	courseId, itemId, itemType, attachmentId und login_hint.
Höhe	100% der Fensterhöhe minus 140 Pixel für den oberen Header
Breite	100% der Fensterbreite

iFrame „studentWorkReviewUri“

Dimension	Beschreibung
Erforderlich	Nein (gibt an, ob es sich um einen Anhang vom Typ „Aktivität“ handelt)
URI	studentWorkReviewUri
Abfrageparameter	courseId, itemId, itemType, attachmentId, submissionId und login_hint.
Höhe	100% der Fensterhöhe minus 168 Pixel für den oberen Header
Breite	100% der Fensterbreite minus die Breite der Seitenleiste<> Die Seitenleiste ist im erweiterten Zustand 312 Pixel und im minimierten Zustand 56 Pixel breit.

Hinweis: Lehrkräfte können den iFrame „Student Work Review“ für einen Schüler/Studenten öffnen, der den Add-on-Anhang noch nicht aufgerufen hat. In diesem Fall ist das Add-on möglicherweise noch nicht über diesen Schüler/Studenten informiert und sollte eine entsprechende Meldung anzeigen.

iFrame „Link-Upgrade“

Dimension	Beschreibung
Erforderlich	Ja, wenn das Konvertieren von Links in Add-on-Anhänge von Ihrem Add-on unterstützt wird.
URI	In den Add-on-Metadaten angegeben
Abfrageparameter	courseId, itemId, itemType, addOnToken, urlToUpgrade und login_hint.
Höhe	80% der Fensterhöhe minus 60 Pixel für den oberen Header
Breite	Maximal 1.600 Pixel 90% der Fensterbreite, wenn das Fenster <= 600 Pixel breit ist 80% der Fensterbreite, wenn das Fenster > 600 Pixel breit ist

Beispielszenario für das Link-Upgrade

1. Ein Classroom-Add-on ist mit dem URI für das Link-Upgrade https://example.com/upgrade registriert. Sie haben die folgenden Host- und Pfad präfixmuster für Link-Anhänge angegeben, die Classroom in Add-on-Anhänge konvertieren soll:
   • Der Host ist example.com und das Pfadpräfix ist /quiz.
2. Eine Lehrkraft erstellt eine neue Ankündigung, Aufgabe oder ein neues Material in einem ihrer Kurse. Beispiel: itemId=234, itemType=courseWork und courseId=123.
3. Eine Lehrkraft fügt im Dialogfeld „Link-Anhang“ einen Link ein, z. B. https://example.com/quiz/5678, der mit einem von Ihnen angegebenen URL-Muster übereinstimmt. Die Lehrkraft wird dann aufgefordert, den Link in einen Add-on-Anhang zu konvertieren.

4. Classroom startet den iFrame „Link-Upgrade“ mit der URL set to https://example.com/upgrade?courseId=123&itemId=234&itemType=courseWork&addOnToken=456&urlToUpgrade=https%3A%2F%2Fexample.com%2Fquiz%2F5678.

5. Sie werten die im iFrame übergebenen Suchparameter aus und rufen den CreateAddOnAttachment Endpunkt auf. Beachten Sie, dass der Suchparameter urlToUpgrade URI-codiert ist, wenn er im iFrame übergeben wird. Sie müssen den Parameter decodieren, um ihn in seiner ursprünglichen Form zu erhalten. In JavaScript gibt es beispielsweise die Funktion decodeURIComponent().

6. Wenn ein Add-on-Anhang erfolgreich aus einem Link erstellt wurde, senden Sie eine postMessage an Classroom, um den iFrame zu schließen.

iFrame schließen

Der iFrame kann über das Lerntool geschlossen werden, indem ein postMessage mit der Nutzlast {type: 'Classroom', action: 'closeIframe'} gesendet wird. Classroom akzeptiert diese postMessage nur vom Hostnamen und Port, die dem ursprünglich geöffneten URI entsprechen.

<button id="close">Send message to close iframe</button>
<script>
  document.querySelector('#close')
    .addEventListener('click', () => {
        window.parent.postMessage({
            type: 'Classroom',
            action: 'closeIframe',
        }, '*');
    });
</script>

iFrame über den iFrame schließen

Die Domain und der Port der Seite, die das postMessage-Ereignis sendet, müssen mit der Domain und dem Port des URI übereinstimmen, der zum Starten des iFrames verwendet wurde. Andernfalls wird die Nachricht ignoriert. Eine mögliche Lösung besteht darin, zu einer Seite in der ursprünglichen Domain zurückzuleiten, die nichts weiter tut, als das postMessage-Ereignis zu senden.

iFrame über einen neuen Tab schließen

Schutzmaßnahmen für domänenübergreifende Anfragen verhindern, dass dies funktioniert. Eine mögliche Lösung besteht darin, die Kommunikation zwischen dem iFrame und dem neuen Tab selbst zu verarbeiten und den iFrame letztendlich für das Auslösen des postMessage-Ereignisses zum Schließen verantwortlich zu machen. Außerdem wird der Hyperlink „In [Partnername] öffnen“ entfernt, damit Nutzer in naher Zukunft keine Tabs auf diese Weise erstellen.

Einschränkungen

Alle iFrames werden mit den folgenden Sandbox-Attributen geöffnet:

• allow-popups
• allow-popups-to-escape-sandbox
• allow-forms
• allow-scripts
• allow-storage-access-by-user-activation
• allow-same-origin

und der folgenden Feature-Richtlinie:

• allow="microphone *"

Drittanbieter-Cookies blockieren

Wenn Drittanbieter-Cookies blockiert werden, ist es schwierig, eine angemeldete Sitzung in einem iFrame aufrechtzuerhalten. Unter https://www.cookiestatus.com finden Sie Informationen zum aktuellen Stand der Cookie-Blockierung in verschiedenen Browsern. Dieses Problem betrifft nicht nur Google Classroom-Add-ons, sondern alle Websites, die iFrames von Drittanbietern verwenden. Viele unserer Partner sind bereits auf dieses Problem gestoßen.

Einige allgemeine Lösungen sind:

• Öffnen Sie einen neuen Tab, um das Cookie im Kontext der eigenen Website zu erstellen. Einige Browser gewähren Zugriff auf Cookies, die im Kontext der eigenen Website erstellt wurden, auch wenn sie im Kontext einer Drittanbieter-Website verwendet werden.
• Bitten Sie den Nutzer, Drittanbieter-Cookies zuzulassen. Das ist möglicherweise nicht immer für alle Nutzer möglich.
• Entwickeln Sie Single-Page-Webanwendungen, die nicht auf Cookies angewiesen sind.

In zukünftigen Browserversionen werden voraussichtlich weitere Cookie-Einschränkungen eingeführt. Erstellen Sie Feature-Anfragen um Google Feedback dazu zu geben, wie der Aufwand für Partner reduziert werden kann.

Add-ons mithilfe von regulären Ausdrücken für URLs auffindbar machen

Lehrkräfte erstellen häufig Aufgaben mit Link-Anhängen. Um die Verwendung Ihres Add-ons zu fördern, können Sie reguläre Ausdrücke angeben, die mit URLs von Ressourcen übereinstimmen, auf die in Ihrem Add-on zugegriffen werden kann. Wenn eine Lehrkraft einen Link anhängt, der mit einem Ihrer regulären Ausdrücke übereinstimmt, wird ein Dialogfeld angezeigt, in dem sie aufgefordert wird, Ihr Add-on auszuprobieren. Das Dialogfeld wird nur angezeigt, wenn das Add-on bereits für ihr Konto installiert ist.

Wenn Sie Lehrkräften diese Funktion zur Verfügung stellen möchten, geben Sie Ihren Google-Ansprechpartnern die entsprechenden regulären Ausdrücke. Wenn die von Ihnen angegebenen regulären Ausdrücke zu allgemein sind oder mit einem anderen Add-on in Konflikt geraten, werden sie möglicherweise so geändert, dass sie spezifischer oder eindeutiger sind.

Abbildung 1. Lehrkraft wählt einen Link-Anhang für eine neue Aufgabe aus.

Abbildung 2. Lehrkraft fügt einen Link aus einer Drittanbieterquelle ein. Die Lehrkraft hat das Classroom-Add-on des Drittanbieters bereits installiert.

Abbildung 3. Das interaktive Dialogfeld, das der Lehrkraft angezeigt wird, wenn der eingefügte Link mit einem regulären Ausdruck übereinstimmt, der vom Drittanbieter-Entwickler angegeben wurde.

Wenn eine Lehrkraft im Pop-up-Fenster in Abbildung 3 die Option „Jetzt testen“ auswählt, wird sie zum iFrame „Anhangssuche“ Ihres Add-ons weitergeleitet.