Details zu iFrames und Suchparametern

Classroom-Add-ons werden in einem iFrame geladen, um Endnutzern eine nahtlose und praktische Nutzung zu bieten. Es gibt vier verschiedene iFrame-Typen. Einen Überblick über den Zweck und das Aussehen der einzelnen iFrames erhalten Sie im Verzeichnis der Nutzerpfade unter iFrame-Seiten.

iFrame-Sicherheitsrichtlinien

Von Partnern wird erwartet, dass sie die branchenüblichen Best Practices befolgen, um ihre iFrames zu schützen. Zum Schutz des iFrames empfiehlt unser Sicherheitsteam Folgendes:

iFrame-URI-Konfiguration

Der URI für die Anhangeinrichtung wird vom iFrame für die Anhangerkennung geladen. Hier beginnen die Lehrkräfte mit dem Erstellen von Add-on-Anhängen zu einem Classroom-Beitrag. Sie kann in der Google Cloud-Projektkonsole festgelegt werden. Legen Sie diesen URI unter „API und Dienst“ > „Google Workspace Marketplace SDK“ > App-Konfiguration in Ihrem Google Cloud-Projekt fest.

iFrame-URI-Konfiguration

Die Zulässigen Präfixe für Anhangs-URIs werden verwendet, um die in AddOnAttachment festgelegten URIs mithilfe der Methoden *.addOnAttachments.create und *.addOnAttachments.patch zu validieren. Die Validierung erfolgt durch eine literale Stringpräfix-Übereinstimmung und die Verwendung von Platzhaltern ist derzeit nicht zulässig.

Abfrageparameter

Die iFrames geben wichtige Informationen als Abfrageparameter an das Add-on weiter. Es gibt zwei Kategorien von Parametern: anhangbezogene Parameter und anmeldebezogene Parameter.

Die anhangbezogenen Parameter stellen dem Add-on Informationen über den Kurs, die Aufgabe, den Add-on-Anhang, die Einreichung des Schülers/Studenten und ein Autorisierungstoken bereit.

Kurs-ID

Der Wert courseId ist eine Kennung des Kurses.

In allen iFrames enthalten.

Beitrags-ID (eingestellt)

Der Wert postId ist eine ID des Beitrags (Ankündigung, Kursaufgabe oder Kursmaterial), dem dieser Anhang zugeordnet ist.

In allen iFrames enthalten.

Artikel-ID

Der Wert itemId ist eine Kennung von 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 "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.

Einreichungs-ID

Der Wert submissionId ist eine Kennung für die Aufgabe des Schülers/Studenten. Er sollte aber in Kombination mit dem attachmentId verwendet werden, um die Arbeit des Schülers/Studenten bei einer bestimmten Aufgabe zu identifizieren.

Im studentWorkReviewUri enthalten.

Add-on-Token

Der Wert addOnToken ist ein Autorisierungstoken, mit dem addOnAttachments.create-Aufrufe zum Erstellen des Add-ons ausgeführt werden.

Im iFrame für die Anhangerkennung und im iFrame für das Linkupgrade enthalten.

Umzustellende URL

Wenn der Wert urlToUpgrade vorhanden ist, bedeutet dies, dass die Lehrkraft der Aufgabe einen Linkanhang hinzugefügt und zugestimmt hat, ein Upgrade auf einen Add-on-Anhang durchzuführen. Wenn Sie dieses Feature noch nicht konfiguriert haben, finden Sie weitere Informationen in der Anleitung zum Aktualisieren von Links auf Add-on-Anhänge.

Im iFrame für die Linkaktualisierung enthalten

Der Abfrageparameter login_hint liefert Informationen zu dem Classroom-Nutzer, der die Add-on-Webseite 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 für Endnutzer zu vereinfachen. Sie müssen diesen Abfrageparameter in Ihrer Add-on-Implementierung verarbeiten.

Anmeldehinweis

Die login_hint ist eine eindeutige Kennung für das Google

Konto. Nachdem sich der Nutzer zum ersten Mal bei Ihrem Add-on angemeldet hat, wird der Parameter login_hint bei jedem nachfolgenden Besuch von demselben Nutzer übergeben.

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

  1. Übergeben Sie den Wert login_hint während des Authentifizierungsvorgangs, damit der Nutzer seine Anmeldedaten nicht eingeben muss, wenn das Anmeldedialogfeld angezeigt wird. Der Nutzer wird nicht automatisch angemeldet.
  2. Nachdem der Nutzer angemeldet ist, können Sie diesen Parameter verwenden, um den Wert mit anderen Nutzern zu vergleichen, die Sie sich möglicherweise bereits beim Add-on angemeldet haben. Wenn du eine Übereinstimmung findest, kannst du den Nutzer angemeldet lassen und keinen Anmeldevorgang anzeigen. Wenn der Parameter mit keinem Ihrer angemeldeten Nutzer übereinstimmt, fordern Sie ihn auf, sich mit einer Anmeldeschaltfläche von Google anzumelden.

In allen iFrames enthalten.

Anhangerkennung-iFrame

Dimension Beschreibung
Erforderlich Ja
URI In den Add-on-Metadaten angegeben
Abfrageparameter courseId, postId (verworfen), itemId, itemType, addOnToken und login_hint.
Größe 80% Fensterhöhe minus 60 Pixel für die obere Kopfzeile
Breite Maximal 1.600 Pixel
90% Fensterbreite, wenn das Fenster mindestens 600 Pixel breit ist
80% Fensterbreite, wenn das Fenster > 600 Pixel breit ist

Beispielszenario für die Anhangerkennung

  1. Ein Classroom-Add-on ist im Google Workspace Marketplace mit dem URI der Anhangerkennung https://example.com/addon registriert.
  2. Eine Lehrkraft installiert dieses Add-on und erstellt in einem ihrer Kurse neue Ankündigungen, Aufgaben oder Materialien. 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, für den die src-URL auf https://example.com/addon?courseId=123&itemId=234&itemType=courseWork&addOnToken=456 festgelegt ist.
    1. Die Lehrkraft muss innerhalb des iFrames einen Anhang auswählen.
  5. Bei der Auswahl des Anhangs sendet das Add-on eine postMessage an Classroom, um den iFrame zu schließen.

TeacherViewUri- und studentViewUri-iFrames

Dimension Beschreibung
Erforderlich Ja
URI teacherViewUri oder studentViewUri
Abfrageparameter courseId, postId (verworfen), itemId, itemType, attachmentId und login_hint.
Größe 100% Fensterhöhe minus 140 Pixel für die obere Kopfzeile
Breite 100% Fensterbreite

studentWorkReviewUri iFrame

Dimension Beschreibung
Erforderlich Nein (bestimmt, ob es sich um einen Anhang vom Typ „Aktivität“ handelt)
URI studentWorkReviewUri
Abfrageparameter courseId, postId (verworfen), itemId, itemType, attachmentId, submissionId und login_hint.
Größe 100% Fensterhöhe minus 168 Pixel für die obere Kopfzeile
Breite 100% Fensterbreite minus Breite der Seitenleiste<> die Seitenleiste beträgt 312 Pixel, wenn sie maximiert ist, und 56 Pixel, wenn sie minimiert ist.

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, postId (verworfen), itemId, itemType, addOnToken, urlToUpgrade und login_hint.
Größe 80% Fensterhöhe minus 60 Pixel für die obere Kopfzeile
Breite Maximal 1.600 Pixel
90% Fensterbreite, wenn das Fenster mindestens 600 Pixel breit ist
80% Fensterbreite, wenn das Fenster > 600 Pixel breit ist
  1. Ein Classroom-Add-on wird mit dem Link-Upgrade-URI https://example.com/upgrade registriert. Sie haben die folgenden Host- und Pfadpräfixe für Linkanhänge angegeben, die Classroom nach einem Upgrade auf einen Add-on-Anhang ausführen sollte:
    • Der Host ist example.com und das Pfadpräfix /quiz.
  2. Eine Lehrkraft erstellt in einem ihrer Kurse eine neue Ankündigung, Aufgabe oder Material. Beispiel: itemId=234, itemType=courseWork und courseId=123.
  3. Eine Lehrkraft fügt in das Dialogfeld zum Anhängen von Links einen 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 für die Link-Umstellung mit der URL https://example.com/upgrade?courseId=123&postId=234&addOnToken=456&urlToUpgrade=https%3A%2F%2Fexample.com%2Fquiz%2F5678.

  5. Sie werten die Abfrageparameter aus, die an den iFrame übergeben wurden, 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, indem ein postMessage mit der Nutzlast {type: 'Classroom', action: 'closeIframe'} gesendet wird. Classroom akzeptiert diese postMessage nur aus dem Hostnamen und dem 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

Der Domain+Port der Seite, die das postMessage-Ereignis sendet, muss denselben Domain+Port haben wie der URI, der zum Starten des iFrames verwendet wurde. Andernfalls wird die Meldung ignoriert. Sie können das Problem umgehen, indem Sie wieder zu einer Seite in der ursprünglichen Domain weiterleiten, die lediglich das postMessage-Ereignis 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 das Schließen-postMessage-Ereignis vom iFrame auslösen lassen. Hinweis: Der Hyperlink „Open in Partner Name“ (In Partnername öffnen) wird entfernt, damit Nutzer Tabs in naher Zukunft nicht 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 folgenden Richtlinien für Funktionen

  • allow="microphone *"

Durch das Blockieren von Drittanbieter-Cookies wird 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. Natürlich tritt dieses Problem nicht nur auf Google Classroom-Add-ons auf und betrifft alle Websites, die von Drittanbietern in Frames eingebunden werden. Viele unserer Partner haben dieses Problem bereits festgestellt.

Hier einige allgemeine Tipps, wie Sie das Problem umgehen können:

  • Öffnen Sie einen neuen Tab, um das Cookie in einem eigenen Kontext zu erstellen. Einige Browser gewähren Zugriff auf Cookies, die im Erstanbieterkontext in einem Drittanbieterkontext erstellt wurden.
  • Bitten Sie den Nutzer, Drittanbieter-Cookies zuzulassen. Dies ist möglicherweise nicht immer bei allen Nutzenden möglich.
  • Erstellen Sie einseitige Web-Apps, die nicht auf Cookies angewiesen sind.

In zukünftigen Browserversionen sind mehr Cookie-Einschränkungen zu erwarten. Sie können Funktionsanfragen erstellen, um Google Feedback dazu zu senden, wie die von Partnern benötigten Steigerungen reduziert werden können.

Sichtbarkeit von Add-ons mithilfe von regulären URL-Ausdrücken 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. Eine Lehrkraft, die einen Link anhängt, der mit einem Ihrer regulären Ausdrücke übereinstimmt, sieht ein schließbares Dialogfeld, in dem sie aufgefordert wird, das Add-on auszuprobieren. Sie sehen das Dialogfeld nur, wenn das Add-on bereits für ihr Konto installiert ist.

Wenn du Lehrkräften dieses Verhalten anbieten möchtest, stelle deinen Google-Kontakten die entsprechenden regulären Ausdrücke zur Verfügung. Wenn die regulären Ausdrücke, die Sie angeben, zu allgemein sind oder mit einem anderen Add-on in Konflikt stehen, werden sie möglicherweise so geändert, dass sie stärker eingeschränkt oder eigenständig sind.

Lehrkraft wählt Linkanhang aus Abbildung 1: Die Lehrkraft wählt einen Link an eine neue Aufgabe aus.

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

Dialogfeld für die Auffindbarkeit von regulären Ausdrücken Abbildung 3: Das interaktive Dialogfeld, das der Lehrkraft angezeigt wird, wenn der eingefügte Link einem regulären Ausdruck entspricht, der vom Entwickler des Drittanbieters festgelegt wurde.

Wenn eine Lehrkraft im Pop-up die Option „Jetzt testen“ auswählt (siehe Abbildung 3), werden sie zum iFrame der Anhangerkennung Ihres Add-ons weitergeleitet.