Szczegóły elementu iframe i parametrów zapytania

Dodatki do Classroom są ładowane w elemencie iframe, aby zapewnić użytkownikom wygodę i płynność korzystania. Istnieje 5 różnych typów elementów iframe. Aby dowiedzieć się więcej o ich przeznaczeniu i wyglądzie, zapoznaj się ze stronami poświęconymi elementom iframe w katalogu Ścieżki użytkowników, gdzie znajdziesz ich przegląd.

Wskazówki dotyczące bezpieczeństwa elementów iframe

Oczekujemy, że programiści będą stosować sprawdzone metody w branży, aby zabezpieczyć swoje elementy iframe. Warto jednak uwzględnić w ścieżce użytkownika pewne interakcje z interfejsem API, aby potwierdzić, że masz prawidłowe dane logowania i możesz poprawnie określić rolę użytkownika w zajęciach.

Konfiguracja aplikacji serwera

Aby chronić element iframe, zalecamy te konfiguracje serwera:

• Wymagany jest protokół HTTPS. Zdecydowanie zalecamy używanie protokołu TLS 1.2 lub nowszego oraz włączenie mechanizmu HSTS (HTTP Strict Transport Security). Więcej informacji znajdziesz w tym MDN artykule na temat mechanizmu HSTS.
• Włącz ścisłe zasady bezpieczeństwa treści (Strict CSP). Więcej informacji znajdziesz w tym artykule OWASP i tym powiązanym artykule MDN na temat (standardu) Content Security Policy.
• Włącz atrybut Secure pliku cookie. Więcej informacji znajdziesz w artykule na temat atrybutu HttpOnly i tym powiązanym artykule MDN na temat plików cookie.

Parametry zapytania

Elementy iframe przekazują do dodatku ważne informacje jako parametry zapytania. Istnieją 2 kategorie parametrów: związane z załącznikami i związane z logowaniem.

Parametry związane z załącznikami

Parametry związane z załącznikami przekazują do dodatku informacje o zajęciach, projekcie, załączniku dodatku, zadaniu przesłanym przez ucznia i tokenie autoryzującym.

Identyfikator zajęć

Wartość courseId to identyfikator zajęć.

Uwzględniony we wszystkich elementach iframe.

Identyfikator produktu

Wartość itemId to identyfikator elementu Announcement, CourseWork lub CourseWorkMaterial, do którego jest dołączony ten załącznik.

Uwzględniony we wszystkich elementach iframe.

Typ elementu

Wartość itemType określa typ zasobu, do którego jest dołączony ten załącznik. Przekazywana wartość ciągu znaków to jeden z tych ciągów: "announcements", "courseWork", lub "courseWorkMaterials".

Uwzględniony we wszystkich elementach iframe.

Identyfikator załącznika

Wartość attachmentId to identyfikator załącznika.

Uwzględniony w elementach iframe teacherViewUri, studentViewUri i studentWorkReviewUri.

Identyfikator przesłanej próbki

Wartość submissionId to identyfikator pracy ucznia, ale należy go używać w połączeniu z wartością attachmentId, aby zidentyfikować pracę ucznia w ramach konkretnego projektu.

Uwzględniony w elemencie studentWorkReviewUri.

Token dodatku

Wartość addOnToken to token autoryzacji używany do wykonywania wywołań addOnAttachments.create w celu utworzenia dodatku.

Uwzględniony w elem0}elemencie iframe wykrywania załączników i elemencie iframe uaktualniania linków.

Adres URL do uaktualnienia

Obecność wartości urlToUpgrade oznacza, że nauczyciel dołączył do projektu załącznik z linkiem i zgodził się na uaktualnienie go do załącznika dodatku. Jeśli nie masz jeszcze skonfigurowanej tej funkcji, zapoznaj się z przewodnikiem na temat uaktualniania linków do załączników dodatków.

Uwzględniony w elem0}elemencie iframe uaktualniania linków.

Parametry związane z logowaniem

Parametr zapytania login_hint zawiera informacje o użytkowniku Classroom, który odwiedza stronę internetową dodatku. Ten parametr zapytania jest podawany w adresie URL src elementu iframe. Jest wysyłany, gdy użytkownik wcześniej używał Twojego dodatku, aby zmniejszyć trudności związane z logowaniem. Musisz obsługiwać ten parametr zapytania w implementacji dodatku.

Wskazówka dotycząca logowania

Wartość login_hint to unikalny identyfikator konta Google użytkownika. Gdy użytkownik zaloguje się w Twoim dodatku po raz pierwszy, parametr login_hint będzie przekazywany przy każdej kolejnej wizycie tego samego użytkownika.

Parametr login_hint można wykorzystać na 2 sposoby:

1. Przekaż wartość login_hint podczas procesu uwierzytelniania, aby użytkownik nie musiał wpisywać danych logowania, gdy pojawi się okno logowania. Użytkownik nie jest logowany automatycznie.
2. Gdy użytkownik się zaloguje, użyj tego parametru, aby porównać jego wartość z wartościami użytkowników, którzy są już zalogowani w dodatku. Jeśli znajdziesz dopasowanie, możesz pozostawić użytkownika zalogowanego i uniknąć wyświetlania procesu logowania. Jeśli parametr nie pasuje do żadnego z zalogowanych użytkowników, poproś użytkownika o zalogowanie się za pomocą przycisku logowania z logo Google.

Uwzględniony we wszystkich elementach iframe.

Element iframe wykrywania załączników

Przykład scenariusza wykrywania załączników

1. Dodatek do Classroom jest zarejestrowany w Google Workspace Marketplace z adresem URI wykrywania załączników https://example.com/addon.
2. Nauczyciel instaluje ten dodatek i tworzy nowe ogłoszenie, projekt lub materiał w ramach jednego z zajęć. Na przykład itemId=234, itemType=courseWork i courseId=123.
3. Podczas konfigurowania tego elementu nauczyciel wybiera nowo zainstalowany dodatek jako załącznik.
4. Classroom tworzy element iframe z adresem URL src ustawionym na https://example.com/addon?courseId=123&itemId=234&itemType=courseWork&addOnToken=456.
   1. Nauczyciel wykonuje działania w elemencie iframe, aby wybrać załącznik.
5. Po wybraniu załącznika dodatek wysyła do Classroom komunikat postMessage, aby zamknąć element iframe.

Elementy iframe teacherViewUri i studentViewUri

Element iframe studentWorkReviewUri

Element iframe uaktualniania linków

Przykład scenariusza uaktualniania linków

1. Dodatek do Classroom jest zarejestrowany z adresem URI uaktualniania linków https://example.com/upgrade. Podano te wzorce prefiksów hosta i ścieżki dla załączników z linkami, które Classroom powinien próbować uaktualnić do załącznika dodatku:
   • Host to example.com, a prefiks ścieżki to /quiz.
2. Nauczyciel tworzy nowe ogłoszenie, projekt lub materiał w ramach jednego z zajęć. Na przykład itemId=234, itemType=courseWork i courseId=123.
3. Nauczyciel wkleja link https://example.com/quiz/5678 w oknie załącznika z linkiem, który pasuje do podanego przez Ciebie wzorca adresu URL. Następnie nauczyciel jest proszony o uaktualnienie linku do załącznika dodatku.

4. Classroom uruchamia element iframe uaktualniania linków z adresem URL ustawionym na https://example.com/upgrade?courseId=123&itemId=234&itemType=courseWork&addOnToken=456&urlToUpgrade=https%3A%2F%2Fexample.com%2Fquiz%2F5678.

5. Oceniasz parametry zapytania przekazane w elemencie iframe i wywołujesz punkt końcowy CreateAddOnAttachment. Pamiętaj, że parametr zapytania urlToUpgrade jest kodowany na potrzeby adresu URL podczas przekazywania w elemencie iframe. Aby uzyskać go w oryginalnej postaci, musisz go zdekodować. Na przykład w JavaScript jest dostępna funkcja decodeURIComponent().

6. Po pomyślnym utworzeniu załącznika dodatku z linku wysyłasz do Classroom komunikat postMessage, aby zamknąć element iframe.

Zamykanie elementu iframe

Element iframe można zamknąć z poziomu narzędzia do nauki, wysyłając postMessage z ładunkiem {type: 'Classroom', action: 'closeIframe'}. Classroom akceptuje ten komunikat postMessage tylko z nazwy hosta i portu odpowiadających oryginalnemu adresowi URI, który został otwarty.

<button id="close">Send message to close iframe</button>
<script>
  document.querySelector('#close')
    .addEventListener('click', () => {
        window.parent.postMessage({
            type: 'Classroom',
            action: 'closeIframe',
        }, '*');
    });
</script>

Zamykanie elementu iframe z poziomu elementu iframe

Domena i port strony wysyłającej zdarzenie postMessage muszą być takie same jak domena i port adresu URI użytego do uruchomienia elementu iframe. W przeciwnym razie komunikat zostanie zignorowany. Obejście polega na przekierowaniu z powrotem na stronę w oryginalnej domenie, która nie robi nic poza wysłaniem zdarzenia postMessage.

Zamykanie elementu iframe z poziomu nowej karty

Uniemożliwiają to zabezpieczenia między domenami. Obejście polega na samodzielnym obsłużeniu komunikacji między elementem iframe a nową kartą i pozostawieniu elementu iframe odpowiedzialnego za wysłanie zdarzenia postMessage zamykającego. Na marginesie dodamy, że hiperlink „Otwórz w Nazwie partnera” zostanie usunięty, aby użytkownicy nie tworzyli w ten sposób kart w najbliższej przyszłości.

Ograniczenia

Wszystkie elementy iframe są otwierane z tymi atrybutami sandbox:

• allow-popups
• allow-popups-to-escape-sandbox
• allow-forms
• allow-scripts
• allow-storage-access-by-user-activation
• allow-same-origin

i tymi zasadami dotyczącymi funkcji:

• allow="microphone *"

Blokowanie plików cookie innych firm

Pamiętaj, że blokowanie plików cookie innych firm utrudnia utrzymanie sesji zalogowanego użytkownika w elemencie iframe. Aktualny stan blokowania plików cookie w różnych przeglądarkach znajdziesz na stronie https://www.cookiestatus.com. Ten problem nie dotyczy tylko dodatków do Google Classroom, ale wszystkich witryn, które używają elementów iframe innych firm. Wielu naszych partnerów już się z nim spotkało.

Oto kilka ogólnych obejść:

• Otwórz nową kartę, aby utworzyć plik cookie w kontekście (pochodzącym) z własnych danych. Niektóre przeglądarki przyznają dostęp do plików cookie utworzonych w kontekście (pochodzące) z własnych danych, gdy są w kontekście innej firmy.
• Poproś użytkownika o zezwolenie na pliki cookie innych firm. Nie zawsze jest to możliwe w przypadku wszystkich użytkowników.
• Twórz jednostronicowe aplikacje internetowe, które nie korzystają z plików cookie.

W przyszłych wersjach przeglądarek spodziewamy się kolejnych ograniczeń dotyczących plików cookie. Twórz prośby o dodanie funkcji, aby przesyłać do Google opinie na temat tego, jak zmniejszyć nakład pracy wymagany od partnerów.

Włączanie wykrywalności dodatków za pomocą wyrażeń regularnych w adresach URL

Nauczyciele często tworzą projekty z załącznikami w postaci linków. Aby promować korzystanie z Twojego dodatku, możesz określić wyrażenia regularne, które pasują do adresów URL zasobów dostępnych w Twoim dodatku. Gdy nauczyciel dołączy link pasujący do jednego z Twoich wyrażeń regularnych, zobaczy okno z możliwością zamknięcia, które zachęca go do wypróbowania Twojego dodatku. Okno to będzie widoczne tylko wtedy, gdy dodatek jest już zainstalowany na jego koncie.

Jeśli chcesz udostępnić nauczycielom tę funkcję, prześlij odpowiednie wyrażenia regularne do swoich kontaktów w Google. Jeśli podane przez Ciebie wyrażenia regularne są zbyt ogólne lub powodują konflikt z innym dodatkiem, mogą zostać zmodyfikowane w celu ograniczenia lub rozróżnienia.

Rysunek 1. Nauczyciel wybiera załącznik z linkiem do nowego projektu.

Rysunek 2. Nauczyciel wkleja link ze źródła zewnętrznego. Nauczyciel zainstalował już dodatek do Classroom firmy zewnętrznej.

Rysunek 3. Interaktywne okno, które wyświetla się nauczycielowi, gdy wklejony link pasuje do wyrażenia regularnego określonego przez programistę firmy zewnętrznej.

Jeśli nauczyciel kliknie "Wypróbuj teraz" w wyskakującym okienku widocznym na rysunku 3, zostanie przekierowany do elementu iframe wykrywania załączników w Twoim dodatku.