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 den Zweck und das Aussehen der einzelnen iframes finden Sie auf den iframe-Seiten im Verzeichnis „User journeys“.

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 Nutzerfluss einbauen, um zu bestätigen, dass Sie gültige Anmeldedaten haben und die Rolle des Nutzers im Kurs korrekt identifizieren können.

Konfiguration der Serveranwendung

Zum Schutz des iFrames empfehlen wir die folgenden Serverkonfigurationen:

Abfrageparameter

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

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

Kurs-ID

Der courseId-Wert ist eine Kennung für den Kurs.

In allen iFrames enthalten.

Artikel-ID

Der Wert itemId ist eine Kennzeichnung der Announcement, CourseWork oder CourseWorkMaterial, an die diese Anlage angehängt ist.

In allen iFrames enthalten.

Elementtyp

Der itemType-Wert gibt den Ressourcentyp an, an den diese Anlage angehängt ist. Der übergebene Stringwert ist "announcements", "courseWork" oder "courseWorkMaterials".

In allen iFrames enthalten.

Anhangs-ID

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

In den iFrames teacherViewUri, studentViewUri und studentWorkReviewUri enthalten.

ID der eingereichten Aufgabe

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

Im studentWorkReviewUri enthalten.

Add-on-Token

Der Wert addOnToken ist ein Autorisierungstoken, das verwendet wird, um addOnAttachments.create-Aufrufe zum Erstellen des Add-ons auszuführen.

Enthalten im Attachment Discovery-Iframe und im Link Upgrade-Iframe.

Zu aktualisierende URL

Das Vorhandensein des Werts urlToUpgrade bedeutet, dass der Lehrer einen Link-Anhang in die Aufgabe eingefügt und zugestimmt hat, ihn auf einen Add-on-Anhang zu aktualisieren. Wenn Sie diese Funktion noch nicht konfiguriert haben, finden Sie weitere Informationen im Leitfaden zum Aktualisieren von Links zum Hinzufügen von Add-on-Anhängen.

Im iFrame für Link-Upgrade enthalten.

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

Anmeldehinweis

login_hint ist eine eindeutige Kennung 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 Authentifizierungsablaufs, 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 Nutzern vergleichen, die sich bereits im Add-on angemeldet haben. Wenn Sie eine Übereinstimmung finden, können Sie den Nutzer angemeldet lassen und vermeiden, dass ein Anmeldevorgang angezeigt wird. Wenn der Parameter mit keinem Ihrer angemeldeten Nutzer übereinstimmt, fordern Sie den Nutzer auf, sich mit einer Anmeldeschaltfläche mit Google-Branding anzumelden.

In allen iFrames enthalten.

iFrame für die Suche nach Anhängen

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 Erkennung von Anhängen

  1. Ein Classroom-Add‑on ist im Google Workspace Marketplace mit dem Attachment Discovery-URI 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. Beim Konfigurieren dieses Elements wählt die Lehrkraft das neu installierte Add-on als Anhang aus.
  4. In Classroom wird ein iFrame mit der auf https://example.com/addon?courseId=123&itemId=234&itemType=courseWork&addOnToken=456 festgelegten Quell-URL erstellt.
    1. Der Kursleiter wählt im iFrame eine Anlage aus.
  5. Wenn ein Anhang ausgewählt wird, sendet das Add‑on ein postMessage an Classroom, um das iFrame zu schließen.

iFrames für 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

studentWorkReviewUri-iFrame

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 px für den oberen Header
Breite 100% der Fensterbreite minus der Breite der Seitenleiste<> Die Seitenleiste ist im maximierten Zustand 312 px und im minimierten Zustand 56 px breit.
Dimension Beschreibung
Erforderlich Ja, wenn Ihr Add‑on das Aktualisieren von Links auf Add‑on-Anhänge unterstützt.
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
  1. Ein Classroom-Add-on ist mit dem Link-Upgrade-URI https://example.com/upgrade registriert. Sie haben die folgenden Host- und Pfadpräfixmuster für Linkanhänge angegeben, die in Classroom in einen Add-on-Anhang umgewandelt werden sollen:
    • Der Host ist example.com und das Pfadpräfix ist /quiz.
  2. Ein Kursleiter erstellt in einem seiner Kurse eine neue Ankündigung, Aufgabe oder ein neues Material. Beispiel: itemId=234, itemType=courseWork und courseId=123.
  3. Eine Lehrkraft fügt im Dialogfeld „Link-Anhang“ einen Link (https://example.com/quiz/5678) ein, der einem von Ihnen angegebenen URL-Muster entspricht. Die Lehrkraft wird dann aufgefordert, den Link in einen Add‑on-Anhang zu aktualisieren.

  4. In Classroom wird der iFrame für das Link-Upgrade mit der URL https://example.com/upgrade?courseId=123&itemId=234&itemType=courseWork&addOnToken=456&urlToUpgrade=https%3A%2F%2Fexample.com%2Fquiz%2F5678 geöffnet.

  5. Sie werten die im iFrame übergebenen Suchparameter aus und rufen den CreateAddOnAttachment-Endpunkt auf. Der Abfrageparameter urlToUpgrade wird URI-codiert, wenn er an das 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 Sie einen Add-on-Anhang erfolgreich über einen Link erstellt haben, senden Sie ein postMessage an Classroom, um das iFrame zu schließen.

iFrame schließen

Der iFrame kann über das Lern-Tool geschlossen werden, indem ein postMessage mit der Nutzlast {type: 'Classroom', action: 'closeIframe'} gesendet wird. Classroom akzeptiert dieses postMessage nur vom host_name+port, der der ursprünglichen URI entspricht, die 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 über den iFrame schließen

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

iFrame über einen neuen Tab schließen

Durch Cross-Domain-Schutzmaßnahmen wird dies verhindert. Eine mögliche Lösung besteht darin, die Kommunikation zwischen dem iFrame und dem neuen Tab selbst zu verarbeiten und das Schließen des postMessage-Ereignisses letztendlich dem iFrame zu überlassen. Die Schaltfläche „In [Partnername] öffnen“ wird entfernt, damit Nutzer in Zukunft keine Tabs mehr 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 die folgende Richtlinie für Funktionen:

  • allow="microphone *"

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 Status der Cookie-Blockierung in verschiedenen Browsern. Dieses Problem betrifft nicht nur Google Classroom-Add-ons, sondern alle Websites, die Drittanbieter-iFrames verwenden. Viele unserer Partner hatten dieses Problem bereits.

Allgemeine Problemumgehungen:

  • Öffnen Sie einen neuen Tab, um das Cookie im Kontext von Erstanbietern zu erstellen. Einige Browser gewähren Zugriff auf Cookies, die im Erstanbieterkontext erstellt wurden, während sie sich in einem Drittanbieterkontext befinden.
  • Nutzer bitten, Drittanbieter-Cookies zuzulassen Das ist möglicherweise nicht immer bei allen Nutzern möglich.
  • Einseitige Webanwendungen entwickeln, die nicht auf Cookies angewiesen sind

In zukünftigen Browserversionen sind weitere Cookie-Einschränkungen zu erwarten. Funktionsanfragen erstellen, um Google Feedback dazu zu geben, wie der Aufwand für Partner reduziert werden kann.

Auffindbarkeit von Add-ons über reguläre URL-Ausdrücke aktivieren

Lehrkräfte erstellen häufig Aufgaben mit Linkanhä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 schließbares Dialogfeld angezeigt, in dem sie aufgefordert wird, Ihr Add-on auszuprobieren. Das Dialogfeld wird nur angezeigt, wenn das Add-on bereits für das Konto installiert ist.

Wenn Sie Lehrkräften diese Funktion zur Verfügung stellen möchten, geben Sie Ihren Google-Kontakten die entsprechenden regulären Ausdrücke an. Wenn die von Ihnen angegebenen regulären Ausdrücke zu allgemein sind oder mit einem anderen Add-on in Konflikt stehen, werden sie möglicherweise eingeschränkt oder eindeutiger formuliert.

Lehrkraft wählt Linkanhang aus Abbildung 1: Ein Kursleiter wählt einen Link als Anhang für eine neue Aufgabe aus.

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

Dialogfeld zur Auffindbarkeit von regulären Ausdrücken Abbildung 3: Der interaktive Dialog, der der Lehrkraft angezeigt wird, wenn der eingefügte Link mit einem regulären Ausdruck übereinstimmt, der vom Drittanbieterentwickler angegeben wurde.

Wenn eine Lehrkraft im Pop-up (siehe Abbildung 3) „Jetzt ausprobieren“ auswählt, wird sie zum Attachment Discovery-iFrame Ihres Add-ons weitergeleitet.