Classroom-Add-ons werden in einem iFrame geladen, um dem Endnutzer eine nahtlose und praktische Nutzung zu bieten. Es gibt vier verschiedene iFrame-Typen. Eine Übersicht über den Zweck und die Darstellung der einzelnen iFrames finden Sie auf den iFrame-Seiten im Verzeichnis „User Journeys“.
iFrame-Sicherheitsrichtlinien
Partner müssen die Best Practices der Branche befolgen, um ihre iFrames zu sichern. Zum Schutz des iFrames empfiehlt unser Sicherheitsteam Folgendes:
HTTPS ist erforderlich. Wir empfehlen dringend, TLS 1.2 oder höher zu verwenden und HTTP Strict Transport Security zu aktivieren. Weitere Informationen finden Sie in diesem MDN-Artikel zu Strict Transport Security.
Aktivieren Sie Strict Content Security Policy. Weitere Informationen finden Sie in diesem OWASP-Artikel und diesem zugehörigen MDN-Artikel zur Content Security Policy.
Aktivieren Sie das Attribut „Sicheres Cookie“. Weitere Informationen finden Sie unter HttpOnly-Attribut und im zugehörigen Cookies MDN-Artikel.
iFrame-URI-Konfiguration
Der URI für die Anhangeinrichtung wird in den iFrame der Anhangserkennung geladen. Über diesen URI beginnen Lehrkräfte mit dem Erstellen von Add-on-Anhängen für einen Classroom-Beitrag. Er kann in der Google Cloud-Projektkonsole festgelegt werden. Legen Sie diesen URI auf der Seite „API und Dienst“ > „Google Workspace Marketplace SDK“ > App-Konfiguration Ihres Google Cloud-Projekts fest.
Die zulässigen URI-Präfixe für Anhänge werden verwendet, um die in AddOnAttachment festgelegten URIs mithilfe der Methoden *.addOnAttachments.create
und *.addOnAttachments.patch
zu validieren. Die Validierung ist eine literale Stringpräfixübereinstimmung und lässt derzeit die Verwendung von Platzhaltern nicht zu.
Abfrageparameter
Die iFrames übergeben wichtige Informationen als Abfrageparameter an das Add-on. Es gibt zwei Kategorien von Parametern: anhangs- und anmeldebezogene Parameter.
Anhangsbezogene Parameter
Die anhangsbezogenen Parameter liefern dem Add-on Informationen über den Kurs, die Aufgabe, den Add-on-Anhang, die abgegebene Aufgabe des Teilnehmers und ein Autorisierungstoken.
- Kurs-ID
Der Wert
courseId
ist eine Kennung für den Kurs.Bei allen iFrames enthalten.
- Artikel-ID
Der Wert
itemId
ist eine Kennung vonAnnouncement
.CourseWork
oderCourseWorkMaterial
, an die dieser Anhang angehängt ist.Bei allen iFrames enthalten.
- Elementtyp
Der Wert
itemType
gibt den Ressourcentyp an, auf dem diesAnhang ist angehängt. Der übergebene Stringwert ist
"announcements"
,"courseWork"
oder"courseWorkMaterials"
.Bei allen iFrames enthalten.
- Anhangs-ID
Der Wert
attachmentId
ist eine Kennung für den Anhang.In den iFrames
teacherViewUri
,studentViewUri
undstudentWorkReviewUri
enthalten.- Einreichungs-ID
Der Wert
submissionId
ist eine Kennzeichnung der Arbeit des Schülers/Studenten. Er sollte aber in Kombination mit demattachmentId
verwendet werden, um die Arbeit des Schülers/Studenten für eine bestimmte Aufgabe zu identifizieren.Im
studentWorkReviewUri
enthalten.
- Add-on-Token
Der Wert
addOnToken
ist ein Autorisierungstoken, mit demaddOnAttachments.create
-Aufrufe, um das Add-on zu erstellen.Im iFrame der Anhangserkennung und im iFrame für das Linkupgrade enthalten.
- Umzustellende URL
Das Vorhandensein des Werts
urlToUpgrade
impliziert, dass der WertDie Lehrkraft hat der Aufgabe einen Linkanhang hinzugefügt und zugestimmt, sie in einen Add-on-Anhang zu aktualisieren. Wenn Sie diese Funktion noch nicht konfiguriert haben, finden Sie weitere Informationen in der Anleitung zum Upgrade von Links zu Add-on-Anhängen.
Im iFrame für das Linkupgrade enthalten.
Anmeldebezogene Parameter
Der Abfrageparameter login_hint
liefert Informationen zu dem Classroom-Nutzer, der die Webseite des Add-ons besucht. Dieser Abfrageparameter wird in der iFrame-URL src
bereitgestellt. Sie wird gesendet, wenn der Nutzer Ihr Add-on bereits verwendet hat, um die Anmeldung des Endnutzers zu vereinfachen. Dieser Abfrageparameter muss in der Add-on-Implementierung verarbeitet werden.
- Anmeldehinweis
Die
login_hint
ist eine eindeutige Kennung für das Google-Konto des NutzersKonto. Nachdem sich der Nutzer zum ersten Mal in Ihrem Add-on angemeldet hat, wird der Parameter
login_hint
bei jedem nachfolgenden Besuch Ihres Add-ons vom selben Nutzer übergeben.Für den Parameter
login_hint
gibt es zwei mögliche Anwendungsfälle:- Übergeben Sie während des Authentifizierungsvorgangs den Wert
login_hint
, damit der Nutzer im Anmeldedialogfeld nicht seine Anmeldedaten eingeben muss. Der Nutzer wird nicht automatisch angemeldet. - Verwenden Sie diesen Parameter, nachdem der Nutzer angemeldet ist, um den Wert mit anderen Nutzern zu vergleichen, die Sie möglicherweise bereits beim Add-on angemeldet haben. Wenn du eine Übereinstimmung findest, kannst du den Nutzer angemeldet lassen und einen Anmeldevorgang vermeiden. Wenn der Parameter mit keinem Ihrer angemeldeten Nutzer übereinstimmt, fordern Sie den Nutzer über die Anmeldeschaltfläche mit Google-Logo auf, sich anzumelden.
Bei allen iFrames enthalten.
- Übergeben Sie während des Authentifizierungsvorgangs den Wert
iFrame für die Anhangserkennung
Dimension | Beschreibung |
---|---|
Erforderlich | Ja |
URI | In den Add-on-Metadaten angegeben |
Abfrageparameter | courseId , itemId , itemType , addOnToken und login_hint . |
Größe | 80% Fensterhöhe minus 60 Pixel für den oberen Header |
Breite | Maximal 1.600 px 90% Fensterbreite, wenn Fenster <= 600 px breit 80% Fensterbreite bei Fenster > 600 px breit |
Beispielszenario für die Anhangerkennung
- Ein Classroom-Add-on ist in Google Workspace Marketplace mit dem URI für die Anhangserkennung
https://example.com/addon
registriert. - Eine Lehrkraft installiert dieses Add-on und erstellt in einem ihrer Kurse eine neue Ankündigung, Aufgabe oder ein neues Material. Beispiel:
itemId=234
,itemType=courseWork
undcourseId=123
. - Bei der Konfiguration dieses Elements wählt die Lehrkraft das neu installierte Add-on als Anhang aus.
- Classroom erstellt einen iFrame, wobei die src-URL auf
https://example.com/addon?courseId=123&itemId=234&itemType=courseWork&addOnToken=456
gesetzt ist.- Die Lehrkraft führt Aufgaben innerhalb des iFrames aus, um einen Anhang auszuwählen.
- Bei der Auswahl des Anhangs sendet das Add-on eine
postMessage
an Classroom, um den iFrame zu schließen.
iFrames von LehrerViewUri und studentViewUri
Dimension | Beschreibung |
---|---|
Erforderlich | Ja |
URI | teacherViewUri oder studentViewUri |
Abfrageparameter | courseId , itemId , itemType , attachmentId und login_hint . |
Größe | 100% Fensterhöhe minus 140 Pixel für die obere Kopfzeile |
Breite | Fensterbreite: 100 % |
studentWorkReviewUri-iFrame
Dimension | Beschreibung |
---|---|
Erforderlich | Nein (bestimmt, ob es sich um einen Anhang vom Typ „Aktivität“ handelt) |
URI | studentWorkReviewUri |
Abfrageparameter | courseId , itemId , itemType , attachmentId , submissionId und login_hint . |
Größe | 100% Fensterhöhe minus 168 Pixel für die obere Kopfzeile |
Breite | 100% Fensterbreite minus Seitenleistenbreite: 312 Pixel im maximierten Zustand und 56 Pixel im minimierten Zustand |
iFrame für Linkupgrade
Dimension | Beschreibung |
---|---|
Erforderlich | Ja, wenn das Upgrade von Links zu Add-on-Anhängen von Ihrem Add-on unterstützt wird. |
URI | In den Add-on-Metadaten angegeben |
Abfrageparameter | courseId , itemId , itemType , addOnToken , urlToUpgrade und login_hint . |
Größe | 80% Fensterhöhe minus 60 Pixel für den oberen Header |
Breite | Maximal 1.600 px 90% Fensterbreite, wenn Fenster <= 600 px breit 80% Fensterbreite bei Fenster > 600 px breit |
Beispiel für ein Szenario für ein Linkupgrade
- Ein Classroom-Add-on ist mit dem URI für das Linkupgrade
https://example.com/upgrade
registriert. Sie haben die folgenden Host- und Pfadpräfixmuster für Linkanhänge angegeben, die Classroom zu einem Add-on-Anhang aktualisieren soll:- Der Host ist
example.com
und das Pfadpräfix ist/quiz
.
- Der Host ist
- Eine Lehrkraft erstellt im Rahmen eines Kurses eine neue Ankündigung, eine Aufgabe oder ein neues Material. Beispiel:
itemId=234
,itemType=courseWork
undcourseId=123
. - Eine Lehrkraft fügt in das Dialogfeld „Linkanhang“ den Link
https://example.com/quiz/5678
ein, der einem von Ihnen angegebenen URL-Muster entspricht. Die Lehrkraft wird dann aufgefordert, den Link auf einen Add-on-Anhang zu aktualisieren. Classroom startet den iFrame des Linkupgrades mit der URL
https://example.com/upgrade?courseId=123&itemId=234&itemType=courseWork&addOnToken=456&urlToUpgrade=https%3A%2F%2Fexample.com%2Fquiz%2F5678
.Sie werten die an den iFrame übergebenen Abfrageparameter aus und rufen den Endpunkt
CreateAddOnAttachment
auf. Der AbfrageparameterurlToUpgrade
wird URI-codiert, wenn er an den iFrame übergeben wird. Sie müssen den Parameter decodieren, um ihn in seiner ursprünglichen Form zu erhalten. JavaScript bietet beispielsweise die FunktiondecodeURIComponent()
.Wenn ein Add-on-Anhang über einen 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. Dazu wird ein postMessage
mit der Nutzlast {type: 'Classroom', action: 'closeIframe'}
gesendet.
Classroom akzeptiert diese postMessage
nur von dem Hostname+Port, der dem ursprünglichen URI entspricht, der geöffnet wurde.
<button id="close">Send message to close iframe</button>
<script>
document.querySelector('#close')
.addEventListener('click', () => {
window.parent.postMessage({
type: 'Classroom',
action: 'closeIframe',
}, '*');
});
</script>
iFrame aus dem iFrame schließen
Domain+Port der Seite, von der das postMessage
-Ereignis gesendet wird, muss dieselbe Domain haben wie der URI, mit dem der iFrame gestartet wird. Andernfalls wird die Nachricht ignoriert. Sie können das Problem umgehen, indem Sie zurück zu einer Seite in der ursprünglichen Domain weiterleiten, die lediglich das Ereignis postMessage
sendet.
iFrame in einem neuen Tab schließen
Domainübergreifende Schutzmaßnahmen verhindern das. Sie können das Problem umgehen, indem Sie die Kommunikation zwischen dem iFrame und dem neuen Tab selbst verwalten und letztendlich dem iFrame das Auslösen des Ereignisses postMessage
überlassen. Hinweis: Der Hyperlink „In Partnername öffnen“ wurde entfernt, damit Nutzer in naher Zukunft keine Tabs auf diese Weise erstellen können.
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 die folgende Funktionsrichtlinie
allow="microphone *"
Drittanbieter-Cookies blockieren
Durch das Blockieren von Drittanbieter-Cookies ist es schwierig, eine angemeldete Sitzung in einem iFrame zu führen. Informationen zum aktuellen Status der Cookie-Blockierung in verschiedenen Browsern finden Sie unter https://www.cookiestatus.com. Natürlich betrifft dieses Problem nicht nur Google Classroom-Add-ons, sondern betrifft alle Websites, auf denen Drittanbieter-iFrames verwendet werden. Viele unserer Partner haben dieses Problem bereits festgestellt.
Im Folgenden finden Sie einige allgemeine Problemumgehungen:
- Öffnen Sie einen neuen Tab, um das Cookie in einem eigenen Kontext zu erstellen. Einige Browser gewähren Zugriff auf Cookies, die im Kontext eines Drittanbieters erstellt wurden.
- Nutzer bitten, Drittanbieter-Cookies zuzulassen Dies ist nicht immer bei allen Nutzenden möglich.
- Entwerfen Sie Single-Page-Webanwendungen, die keine Cookies benötigen.
In zukünftigen Browserversionen sind weitere Cookie-Einschränkungen zu erwarten. Sie können Funktionsanfragen erstellen, um Google Feedback dazu zu senden, wie Partner die erforderliche Anzeigenwirkung auf die Markenbekanntheit reduzieren können.
Sichtbarkeit von Add-ons mithilfe regulärer URL-Ausdrücke aktivieren
Lehrkräfte erstellen häufig Aufgaben mit Linkanhängen. Um die Verwendung des Add-ons zu fördern, können Sie reguläre Ausdrücke angeben, die mit den 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, das sie schließen können und aufgefordert werden, das Add-on auszuprobieren. Sie sehen das Dialogfeld nur, wenn das Add-on bereits für ihr Konto installiert ist.
Wenn Sie Lehrkräften dieses Verhalten zur Verfügung stellen möchten, stellen Sie Ihren Google-Kontakten die entsprechenden regulären Ausdrücke zur Verfügung. Wenn die von Ihnen angegebenen regulären Ausdrücke zu weit gefasst sind oder mit einem anderen Add-on in Konflikt stehen, werden sie möglicherweise geändert, sodass sie stärker voneinander abweichen können.
Abbildung 1: Eine Lehrkraft wählt einen Linkanhang für eine neue Aufgabe aus.
Abbildung 2: Die Lehrkraft fügt einen Link von einer Drittanbieterquelle ein. Die Lehrkraft hat bereits das Classroom-Add-on des Drittanbieters installiert.
Abbildung 3: Das interaktive Dialogfeld, das der Lehrkraft angezeigt wird, wenn der eingefügte Link mit einem regulären Ausdruck übereinstimmt, der vom Entwickler des Drittanbieters angegeben wurde.
Wenn eine Lehrkraft in der Pop-up-Datei die Option "Jetzt testen" auswählt (siehe Abbildung 3), wird sie zum iFrame der Anhangserkennung Ihres Add-ons weitergeleitet.