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 vonAnnouncement
.CourseWork
oderCourseWorkMaterial
, auf dem sich dieser Anhang befindet angehängt.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
teacherViewUri
,studentViewUri
undstudentWorkReviewUri
iFrames- Einreichungs-ID
Der Wert
submissionId
ist eine Kennzeichnung der Aufgabe des Schülers/Studenten. sollte aber in Kombination mit demattachmentId
verwendet werden, um das die Arbeit eines Schülers/Studenten für eine bestimmte Aufgabe.Im
studentWorkReviewUri
enthalten.
- Add-on-Token
Der Wert
addOnToken
ist ein Autorisierungstoken, mit demaddOnAttachments.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 WertDie 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 NutzersKonto. 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:- Ü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. - 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.
- Übergeben Sie den
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
- Ein Classroom-Add-on ist in Google Workspace registriert
Marktplatz mit dem URI für die Anhangserkennung
https://example.com/addon
. - Eine Lehrkraft installiert dieses Add-on und erstellt eine neue Ankündigung, Aufgabe oder
in einem Kurs behandelt. Beispiel:
itemId=234
,itemType=courseWork
undcourseId=123
. - Bei der Konfiguration dieses Elements wählt die Lehrkraft das neu installierte Add-on aus. als Anhang hinzufügen.
- In Classroom wird ein iFrame erstellt, bei dem die src-URL auf
https://example.com/addon?courseId=123&itemId=234&itemType=courseWork&addOnToken=456
- 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 . |
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 vom Typ „Aktivität“ handelt) |
URI | studentWorkReviewUri |
Abfrageparameter | courseId , itemId , itemType
attachmentId , submissionId und login_hint . |
Höhe | 100% Fensterhöhe minus 168 Pixel für die obere Kopfzeile |
Breite | 100% Fensterbreite minus Breite der Seitenleiste<> Seitenleiste ist 312 Pixel groß im maximierten Zustand und 56 Pixel im minimierten Zustand |
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
- 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
.
- Der Host ist
- Eine Lehrkraft erstellt eine neue Ankündigung, Aufgabe oder ein neues Material in einem der
ihre Kurse. Beispiel:
itemId=234
,itemType=courseWork
undcourseId=123
- 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. 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
Sie werten die an den iFrame übergebenen Suchparameter aus und rufen eine den
CreateAddOnAttachment
-Endpunkt. Beachten Sie, dass dieurlToUpgrade
-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 FunktiondecodeURIComponent()
.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.
Im Folgenden finden Sie einige allgemeine Problemumgehungen:
- Ö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, stärker abgegrenzt 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.