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. Auf den Iframe-Seiten im Verzeichnis „User Journeys“ finden Sie einen Überblick über den Zweck und das Erscheinungsbild der einzelnen Iframes.

iFrame-Sicherheitsrichtlinien

Partner müssen die Best Practices der Branche einhalten, um ihren Iframe zu schützen. Zum Schutz des iframe empfiehlt unser Sicherheitsteam Folgendes:

• HTTPS ist erforderlich. Wir empfehlen dringend, TLS 1.2 oder höher zu verwenden und HTTP Strict Transport Security zu aktivieren. Weitere Informationen finden Sie in diesem MDN-Artikel zu Strict Transport Security.

• Aktivieren Sie Strict Content Security Policy. Weitere Informationen finden Sie in diesem OWASP-Artikel und diesem zugehörigen MDN-Artikel zur Content Security Policy.

• Aktivieren Sie das Attribut „Sichere Cookies“. Weitere Informationen finden Sie im Abschnitt zum HttpOnly-Attribut und in diesem Artikel zu Cookies MDN.

iFrame-URI-Konfiguration

Der Anhangeinrichtungs-URI wird vom Attachment Discovery-Iframe geladen. Hier beginnen Lehrkräfte mit dem Erstellen von Add-on-Anhängen in einem Classroom-Beitrag. Sie 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.

Mit den zulässigen Präfixen für Anhangs-URIs werden die in AddOnAttachment festgelegten URIs mithilfe der Methoden *.addOnAttachments.create und *.addOnAttachments.patch validiert. Die Validierung erfolgt anhand eines Präfix-Strings und erlaubt derzeit keine Platzhalter.

Abfrageparameter

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

Parameter für Anhänge

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

Kurs-ID

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

In allen Iframes enthalten.

Artikel-ID

Der itemId-Wert ist eine Kennung der Announcement.

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

In allen Iframes enthalten.

Elementtyp

Der Wert itemType gibt den Ressourcentyp an, auf den sich

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 Kennung für die Arbeit des Schülers oder Studenten, sollte aber in Kombination mit dem Wert 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 für

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

Im iframe für die Attachment Discovery und im iframe für die Link-Upgrade-Funktion enthalten.

URL, die umgestellt werden soll

Wenn der Wert urlToUpgrade vorhanden ist, bedeutet das, dass

hat in der Aufgabe einen Link-Anhang hinzugefügt und ist damit einverstanden, ihn in einen Add-on-Anhang umzuwandeln. Wenn Sie diese Funktion noch nicht konfiguriert haben, finden Sie weitere Informationen im Leitfaden zum Upgrade von Links zu Add-on-Anhängen.

Im iFrame für das Linkupgrade enthalten.

Parameter zur Anmeldung

Der Abfrageparameter login_hint enthält Informationen zum Classroom-Nutzer, der die Webseite des Add-ons besucht. Dieser Abfrageparameter wird in der iframe-src-URL angegeben. Sie wird gesendet, wenn der Nutzer Ihr Add-on bereits verwendet hat, um die Anmeldung für Endnutzer 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.

Der Parameter login_hint kann auf zwei Arten verwendet werden:

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 sich der Nutzer angemeldet hat, können Sie mit diesem Parameter den Wert mit allen Nutzern vergleichen, die sich bereits im Add-on angemeldet haben. Wenn Sie eine Übereinstimmung finden, können Sie den Nutzer angemeldet lassen und die Anmeldeprozedur überspringen. Wenn der Parameter keinem deiner angemeldeten Nutzer entspricht, bitte den Nutzer, sich mit einer Anmeldeschaltfläche mit Google-Logo anzumelden.

In allen Iframes enthalten.

iFrame für die Suche nach Anhängen

Beispielszenario für die Anhängeerkennung

1. Ein Classroom-Add-on ist im Google Workspace Marketplace mit dem URI für die Suche nach Anhängen 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. In Classroom wird ein IFrame mit der Src-URL https://example.com/addon?courseId=123&itemId=234&itemType=courseWork&addOnToken=456 erstellt.
   1. Die Lehrkraft führt Aufgaben innerhalb des iFrames aus, um einen Anhang auszuwählen.
5. Wenn ein Anhang ausgewählt wird, sendet das Add-on eine postMessage an Classroom, um den Iframe zu schließen.

iFrames von „TeacherViewUri“ und „studentViewUri“

iFrame für studentWorkReviewUri

iFrame für Link-Upgrade

Beispiel für ein Link-Upgrade

1. Ein Classroom-Add-on ist mit dem Link-Upgrade-URI https://example.com/upgrade registriert. Sie haben die folgenden Muster für Host- und Pfadpräfixe 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. 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 in einen Add-on-Anhang umzuwandeln.

4. In Classroom wird der iFrame für die Linkaktualisierung 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 bewerten die über den Iframe übergebenen Suchparameter und rufen den CreateAddOnAttachment-Endpunkt 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 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 über den 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. Eine Lösung besteht darin, zu einer Seite auf der ursprünglichen Domain weiterzuleiten, die nur das Ereignis postMessage sendet.

IFrame über einen neuen Tab schließen

Domainübergreifende Schutzmaßnahmen verhindern dies. Eine Lösung besteht darin, die Kommunikation zwischen dem Iframe und dem neuen Tab selbst zu verwalten und den Iframe letztendlich für das Auslösen des postMessage-Ereignisses zum Schließen verantwortlich zu machen. Der Hyperlink „In Partnername öffnen“ wird entfernt, damit Nutzer in Zukunft keine Tabs mehr 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 der folgenden Funktionsrichtlinie

• allow="microphone *"

Drittanbieter-Cookies blockieren

Beachten Sie, dass das Blockieren von Drittanbieter-Cookies es erschwert, eine angemeldete Sitzung in einem Iframe aufrechtzuerhalten. Informationen zum aktuellen Status der Cookie-Blockierung in verschiedenen Browsern finden Sie unter https://www.cookiestatus.com. Dieses Problem ist natürlich nicht auf Google Classroom-Add-ons beschränkt, sondern betrifft alle Websites, die iframes von Drittanbietern enthalten. Viele unserer Partner sind bereits auf dieses Problem gestoßen.

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 von selbst erhobenen Daten erstellt wurden, während sie sich in einem Drittanbieterkontext befinden.
• Bitten Sie den Nutzer, Drittanbieter-Cookies zuzulassen. Dies ist nicht immer bei allen Nutzenden möglich.
• Entwerfen Sie einseitige Webanwendungen, die nicht auf Cookies basieren.

In zukünftigen Browserversionen sind weitere Cookie-Einschränkungen zu erwarten. Erstellen Sie Funktionsanfragen, um Google Feedback dazu zu geben, wie der von Partnern erforderliche Anstieg reduziert werden kann.

Sichtbarkeit von Add-ons mit regulären Ausdrücken für URLs aktivieren

Lehrkräfte erstellen häufig Aufgaben mit angehängten Links. Sie können 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 Dialogfeld angezeigt, das sie schließen können und aufgefordert werden, das Add-on auszuprobieren. Das Dialogfeld wird nur angezeigt, wenn das Add-on bereits für sein Konto installiert ist.

Wenn Sie Lehrkräften diese Funktion zur Verfügung stellen möchten, teilen Sie Ihren Google-Kontakten die entsprechenden regulären Ausdrücke mit. 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 so geändert, dass sie eingeschränkter oder spezifischer sind.

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

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

Abbildung 3 Der interaktive Dialog, der der Lehrkraft angezeigt wird, wenn der eingefügte Link mit einem vom Drittanbieter angegebenen regulären Ausdruck übereinstimmt.

Wenn eine Lehrkraft im Pop-up wie in Abbildung 3 „Jetzt ausprobieren“ auswählt, wird sie zum Iframe für die Suche nach Anhängen Ihres Add-ons weitergeleitet.