Details zu iFrames und Suchparametern

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:

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.

iFrame-URI-Konfiguration

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.

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 von Announcement.

CourseWork oder CourseWorkMaterial, an die dieser Anhang angehängt ist.

Bei allen iFrames enthalten.

Elementtyp

Der Wert itemType gibt den Ressourcentyp an, auf dem dies

Anhang 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 und studentWorkReviewUri enthalten.

Einreichungs-ID

Der Wert submissionId ist eine Kennzeichnung der Arbeit des Schülers/Studenten. Er sollte aber in Kombination mit dem attachmentId 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 dem

addOnAttachments.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 Wert

Die 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.

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 Nutzers

Konto. 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:

  1. Ü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.
  2. 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.

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

  1. Ein Classroom-Add-on ist in Google Workspace Marketplace mit dem URI für die Anhangserkennung https://example.com/addon registriert.
  2. 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 und courseId=123.
  3. Bei der Konfiguration dieses Elements wählt die Lehrkraft das neu installierte Add-on als Anhang aus.
  4. Classroom erstellt einen iFrame, wobei die src-URL auf https://example.com/addon?courseId=123&itemId=234&itemType=courseWork&addOnToken=456 gesetzt ist.
    1. Die Lehrkraft führt Aufgaben innerhalb des iFrames aus, um einen Anhang auszuwählen.
  5. 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

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
  1. 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.
  2. Eine Lehrkraft erstellt im Rahmen eines Kurses eine neue Ankündigung, eine Aufgabe oder ein neues Material. Beispiel: itemId=234, itemType=courseWork und courseId=123.
  3. 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.

  4. 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.

  5. Sie werten die an den iFrame übergebenen Abfrageparameter aus und rufen den Endpunkt CreateAddOnAttachment auf. Der Abfrageparameter urlToUpgrade 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 Funktion decodeURIComponent().

  6. 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 *"

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.

Lehrkraft wählt Linkanhang aus Abbildung 1: Eine Lehrkraft wählt einen Linkanhang für eine neue Aufgabe aus.

Link zum Einfügen der Lehrkraft Abbildung 2: Die Lehrkraft fügt einen Link von einer Drittanbieterquelle ein. Die Lehrkraft hat bereits das Classroom-Add-on des Drittanbieters installiert.

Dialogfeld „Regex-Sichtbarkeit“ 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.