Details zu iFrames und Suchparametern

Classroom-Add-ons werden in einem iFrame geladen, eine nahtlose und praktische User Experience bieten. Es gibt vier verschiedene iFrame-Typen die iFrame-Seiten im Verzeichnis „User Journeys“ Überblick über den Zweck und das Aussehen der einzelnen iFrames.

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 die Verwendung von TLS 1.2 oder höher sowie HTTP Strict Transport Security aktivieren Weitere Informationen zu diesem MDN zu Strict Transport Security.

• Aktivieren Sie Strict Content Security Policy. OWASP ansehen Artikel und diesem zugehörigen MDN-Artikel zur Content Security Policy.

• Aktivieren Sie das Attribut „Sicheres Cookie“. Siehe das HttpOnly-Attribut und dieses Weitere Informationen finden Sie im Artikel Cookies MDN (Cookies MDN) (in englischer Sprache).

iFrame-URI-Konfiguration

Der URI für die Anhangeinrichtung ist das, was der iFrame für die Anhangerkennung geladen wird, und können Lehrkräfte Add-on-Anhänge zu einem Beitrag in Classroom. Er kann in der Google Cloud-Projektkonsole festgelegt werden. Legen Sie diesen URI in der API Ihres Google Cloud-Projekts fest und Dienst > Google Workspace Marketplace SDK > App-Konfiguration.

Die zulässigen URI-Präfixe für Anhänge werden verwendet, um die URIs zu validieren, die in AddOnAttachment mithilfe von *.addOnAttachments.create und *.addOnAttachments.patch-Methoden. Die Validierung ist ein literales Stringpräfix übereinstimmen und die Verwendung von Platzhaltern derzeit nicht zulässig ist.

Abfrageparameter

Die iFrames übergeben wichtige Informationen als Abfrageparameter an das Add-on. Es gibt zwei Kategorien von Parametern: anhangs- und anmeldebezogen. Parameter.

Anhangsbezogene Parameter

Die anhangsbezogenen Parameter liefern dem Add-on Informationen zum Kurs, der Aufgabe, des Add-on-Anhangs, der abgegebenen Aufgabe des Schülers oder Studenten und einer 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, auf dem sich dieser Anhang befindet angehängt.

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 teacherViewUri, studentViewUri und studentWorkReviewUri iFrames

Einreichungs-ID

Der Wert submissionId ist eine Kennzeichnung der Aufgabe des Schülers/Studenten. sollte aber in Kombination mit dem attachmentId verwendet werden, um das die Arbeit eines Schülers/Studenten für eine bestimmte Aufgabe.

Im studentWorkReviewUri enthalten.

Hinweis: Sie können einen zusammengesetzten Schlüssel aus submissionId und attachmentId verwenden, um die Aufgabe des Schülers/Studenten identifizieren, wenn ihm derselbe Anhang zugewiesen wurde für denselben Schüler oder Studenten in verschiedenen Kursen verfügbar sind. Weitere Informationen finden Sie unter Inhalte.

Add-on-Token

Der Wert addOnToken ist ein Autorisierungstoken, mit dem

addOnAttachments.create-Aufrufe, um das Add-on zu erstellen.

Im iFrame zur Anhangserkennung und im Link-Upgrade enthalten iFrame.

Umzustellende URL

Das Vorhandensein des Werts urlToUpgrade impliziert, dass der Wert

Die Lehrkraft hat der Aufgabe einen Linkanhang hinzugefügt und zugestimmt um sie in einen Add-on-Anhang umzuwandeln. Falls Sie diese konfiguriert haben, lesen Sie die Anleitung zum Aktualisieren von Links für ein Add-on. Anhänge.

Im iFrame für das Linkupgrade enthalten.

Anmeldebezogene Parameter

Der Abfrageparameter login_hint liefert Informationen zum Classroom-Nutzer, der die Webseite des Add-ons aufruft. Dieser Suchparameter wird in der iFrame-src-URL bereitgestellt. Sie wird gesendet, wenn der Nutzer um die Anmeldung von Endnutzern zu vereinfachen. Sie sind für die diesen Suchparameter in Ihrer Add-on-Implementierung verwenden.

Anmeldehinweis

Die login_hint ist eine eindeutige Kennung für das Google-Konto des Nutzers

Konto. Nachdem sich der Nutzer zum ersten Mal bei Ihrem Add-on angemeldet hat, wird das Symbol Der Parameter login_hint wird bei jedem nachfolgenden Besuch Ihres Add-ons von über denselben Nutzer.

Für den Parameter login_hint gibt es zwei mögliche Anwendungsfälle:

1. Übergeben Sie den login_hint-Wert während des Authentifizierungsvorgangs, sodass der Nutzer müssen im Anmeldedialogfeld ihre Anmeldedaten nicht eingeben. angezeigt wird. Der Nutzer wird nicht automatisch angemeldet.
2. Nachdem der Nutzer angemeldet ist, verwenden Sie diesen Parameter, um die Werte für alle Nutzer, die Sie möglicherweise bereits im Add-on angemeldet haben. Wenn wenn der Nutzer eine Übereinstimmung findet, bleibt er angemeldet und es wird vermieden, zur Anmeldung. Wenn der Parameter mit keinem Ihrer angemeldeten fordern Sie den Nutzer auf, sich mit einer Anmeldung mit Google-Branding anzumelden. .

Bei allen iFrames enthalten.

Hinweis: Weitere Informationen zur Implementierung der login_hint und dem Anmeldevorgang für SSO, Reibungslose Anmeldung und Handle mit Schritt-für-Schritt-Anleitung zur wiederholten Anmeldung.

iFrame für die Anhangserkennung

Dimension	Beschreibung
Erforderlich	Ja
URI	In den Add-on-Metadaten angegeben
Abfrageparameter	courseId, itemId, itemType addOnToken und login_hint.
Höhe	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 Pixel breit

Beispielszenario für die Anhangerkennung

1. Ein Classroom-Add-on ist in Google Workspace registriert Marktplatz mit dem URI für die Anhangserkennung https://example.com/addon.
2. Eine Lehrkraft installiert dieses Add-on und erstellt eine neue Ankündigung, Aufgabe oder in einem Kurs behandelt. Beispiel: itemId=234, itemType=courseWork und courseId=123.
3. Bei der Konfiguration dieses Elements wählt die Lehrkraft das neu installierte Add-on aus. als Anhang hinzufügen.
4. In Classroom wird ein iFrame erstellt, bei dem die src-URL auf https://example.com/addon?courseId=123&itemId=234&itemType=courseWork&addOnToken=456
   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 „TeacherViewUri“ und „studentViewUri“

Dimension	Beschreibung
Erforderlich	Ja
URI	teacherViewUri oder studentViewUri
Abfrageparameter	courseId, itemId, itemType attachmentId und login_hint.
Höhe	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 des Typs „Aktivität“ handelt)
URI	studentWorkReviewUri
Abfrageparameter	courseId, itemId, itemType attachmentId, submissionId und login_hint.
Höhe	100% Fensterhöhe minus 168 Pixel für den oberen Header
Breite	100% Fensterbreite minus Breite der Seitenleiste<> Seitenleiste ist 312 Pixel groß im maximierten Zustand und 56 Pixel im minimierten Zustand

Hinweis :Lehrkräfte können den iFrame „Aufgaben von Schülern/Studenten“ für einen Schüler oder Studenten öffnen, der hat sich den Add-on-Anhang bisher noch nicht angesehen. In diesem Fall kann das Add-on noch nicht auf diesen Schüler/Studenten aufmerksam geworden ist und sollte eine entsprechende Nachricht anzeigen.

iFrame für Linkupgrade

Dimension	Beschreibung
Erforderlich	Ja, sofern das Upgrade von Links auf Add-on-Anhänge durchgeführt wird. die von Ihrem Add-on unterstützt werden.
URI	In den Add-on-Metadaten angegeben
Abfrageparameter	courseId, itemId, itemType addOnToken, urlToUpgrade und login_hint.
Höhe	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 Pixel breit

Beispiel für ein Szenario für ein Linkupgrade

1. Ein Classroom-Add-on ist mit dem URI für das Upgrade des Links registriert: https://example.com/upgrade Sie haben den folgenden Host und Pfad angegeben Präfix-Muster für Linkanhänge, die in Classroom zu sehen sein sollen. Versuchen Sie, ein Upgrade auf einen Add-on-Anhang durchzuführen: <ph type="x-smartling-placeholder">
   </ph>
   • 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 der ihre Kurse. Beispiel: itemId=234, itemType=courseWork und courseId=123
3. Eine Lehrkraft fügt einen Link (https://example.com/quiz/5678) in den Link ein Dialogfeld für Anhänge, das einem von Ihnen angegebenen URL-Muster entspricht. Die Lehrkraft ist und werden dann aufgefordert, den Link auf einen Add-on-Anhang zu aktualisieren.

4. Der iFrame für das Linkupgrade mit der festgelegten URL wird in Classroom gestartet. bis 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 Suchparameter aus und rufen eine den CreateAddOnAttachment-Endpunkt. Beachten Sie, dass die urlToUpgrade-Abfrage wird URI-codiert, wenn er an den iFrame übergeben wird. Sie müssen die um sie in ihrer ursprünglichen Form abzurufen. JavaScript bietet z. B. Angebote die Funktion decodeURIComponent().

6. Wenn Sie einen Add-on-Anhang über einen Link erstellen, senden Sie eine Nachricht postMessage zu Classroom, um den iFrame zu schließen.

iFrame schließen

Der iFrame kann vom Lerntool aus geschlossen werden, indem ein postMessage mit die Nutzlast {type: 'Classroom', action: 'closeIframe'}. Classroom akzeptiert nur diese postMessage vom Hostname+Port entspricht dem ursprünglichen URI, 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

Die Domain und der Port der Seite, von der das postMessage-Ereignis gesendet wird, müssen dieselben Domain+Port als den URI verwenden, der zum Starten des iFrames verwendet wurde. Andernfalls wird die Nachricht wird ignoriert. Sie können das Problem umgehen, indem Sie zurück auf eine Seite in der ursprünglichen Domain weiterleiten. das lediglich das Ereignis postMessage sendet.

iFrame in einem neuen Tab schließen

Domainübergreifende Schutzmaßnahmen verhindern das. Eine Problemumgehung besteht darin, zwischen dem iFrame und dem neuen Tab selbst kommunizieren und ist letztendlich für das Auslösen des postMessage-Ereignisses für die Schließung verantwortlich. Als Seite über den Hyperlink „In Partnername öffnen“ wird entfernt, damit Nutzer in naher Zukunft auf diese Weise Tabs 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 Funktionsrichtlinie

• allow="microphone *"

Drittanbieter-Cookies blockieren

Beachten Sie, dass das Blockieren von Drittanbieter-Cookies es schwierig macht, in einem iFrame angemeldet sind. Weitere Informationen finden Sie unter https://www.cookiestatus.com in der der aktuelle Status der Cookie-Blockierung in verschiedenen Browsern. Natürlich ist nicht auf Google Classroom-Add-ons beschränkt und betrifft alle Websites, Drittanbieter-iFrames verwenden. Viele unserer Partner haben dieses Problem bereits festgestellt.

Hier einige allgemeine Behelfslösungen:

• Öffnen Sie einen neuen Tab, um das Cookie in einem eigenen Kontext zu erstellen. Einige Browser Zugriff auf Cookies zu gewähren, die in Erstanbieter-Cookies erstellt wurden, Kontext von Drittanbietern.
• Nutzer bitten, Drittanbieter-Cookies zuzulassen Das ist nicht immer möglich. mit allen Nutzenden.
• Entwerfen Sie Single-Page-Webanwendungen, die keine Cookies benötigen.

In zukünftigen Browserversionen sind weitere Cookie-Einschränkungen zu erwarten. Erstellen Funktionsanfragen, um Feedback an Google zu senden, wie die erforderliche Steigerung reduziert werden kann von Partnern.

Sichtbarkeit von Add-ons mithilfe regulärer URL-Ausdrücke aktivieren

Lehrkräfte erstellen häufig Aufgaben mit Linkanhängen. Um die Verwendung zu bewerben Ihres Add-ons können Sie reguläre Ausdrücke angeben, die mit den URLs von Ressourcen übereinstimmen. auf die Sie in Ihrem Add-on zugreifen können. Eine Lehrkraft hängt einen Link an, der mit einem übereinstimmt Ihrer regulären Ausdrücke wird ein Dialogfeld angezeigt, das sie schließen können. für Ihr Add-on. Das Dialogfeld wird nur angezeigt, wenn das Add-on bereits für sein Konto.

Wenn Sie Lehrkräften dieses Verhalten zur Verfügung stellen möchten, teilen Sie ihnen Ihre Google mit den entsprechenden regulären Ausdrücken. Wenn die regulären Ausdrücke zu allgemein gefasst sind oder mit einem anderen Add-on in Konflikt stehen, eingeschränkt oder abgeändert werden.

Abbildung 1: Lehrkraft wählt einen Link aus an eine neue Aufgabe anhängen.

Abbildung 2: Die Lehrkraft fügt einen Link von einem Drittanbieter ein. Quelle. Die Lehrkraft hat bereits die Classroom-Add-on.

Abbildung 3: Das interaktive Dialogfeld an die Lehrkraft gesendet, wenn der eingefügte Link mit einem regulären Ausdruck übereinstimmt, der den Drittanbieter-Entwickler.

Wenn eine Lehrkraft „Jetzt ausprobieren“ auswählt wie in Abbildung 3 gezeigt, sind sie an den iFrame der Anhangserkennung Ihres Add-ons weitergeleitet werden.