Szczegóły elementu iframe i parametrów zapytania

Dodatki do Classroom są wczytywane w ramach ramki iframe, aby zapewnić użytkownikom płynne i wygodne wrażenia. Istnieje 5 różnych typów iframe. Aby dowiedzieć się więcej o celu i wyglądzie poszczególnych iframe, zapoznaj się z stronami iframe w katalogu ścieżek użytkownika.

Ważne: gdy użytkownik otworzy jeden z widoków wtyczki, otrzymasz różne informacje. Używaj tych informacji do identyfikowania załączników, sprawdzania danych logowania i roli użytkownika oraz wykonywania niektórych żądań interfejsu API.

Wytyczne dotyczące bezpieczeństwa iframe

Programiści powinni stosować sprawdzone metody branżowe, aby zabezpieczyć iframe. Musisz jednak też uwzględnić w swoim scenariuszu interakcji z użytkownikiem określone interakcje z interfejsem API, aby mieć ważne dane uwierzytelniające i móc poprawnie zidentyfikować rolę użytkownika w programie.

Konfiguracja aplikacji serwera

Aby chronić iframe, zalecamy użycie tych konfiguracji serwera:

• Protokół HTTPS jest wymagany. Zdecydowanie zalecamy używanie protokołu TLS 1.2 lub nowszego oraz włączenie mechanizmu HTTP Strict Transport Security (HSTS). Zapoznaj się z artykułem MDN na temat protokołu MTA-STS.
• Włącz ścisły standard Content Security Policy (CSP). Zapoznaj się z tym artykułem OWASP i powiązanym artykułem MDN na temat zasad bezpieczeństwa treści.
• Włącz atrybut Bezpieczne pliki cookie. Zapoznaj się z atrybutem HttpOnly oraz z powiązanym artykułem MDN o plikach cookie.

Parametry zapytania

Ramki iframe przekazują ważne informacje do dodatku jako parametry zapytania. Parametry dzielą się na 2 kategorie: parametry związane z załącznikami i parametry związane z logowaniem.

Parametry dotyczące załączników

Parametry związane z załącznikami dostarczają dodatkowi informacji o zajęciach, projekcie, załączniku dodatku, przesłaniu ucznia i autoryzującym tokenie.

Identyfikator zajęć

Wartość courseId to identyfikator zajęć.

Dostępne we wszystkich tagach iframe.

Identyfikator produktu

Wartość itemId to identyfikator Announcement,

CourseWork lub CourseWorkMaterial, do których jest dołączony ten załącznik.

Dostępne we wszystkich tagach iframe.

Typ elementu

Wartość itemType określa typ zasobu, w którym

Załącznik jest dołączony. Przekazywana wartość ciągu tekstowego to "announcements", "courseWork" lub "courseWorkMaterials".

Dostępne we wszystkich tagach iframe.

Identyfikator załącznika

Wartość attachmentId to identyfikator załącznika.

Dostępne w ramach interfejsów iframe teacherViewUri, studentViewUri i studentWorkReviewUri.

Identyfikator zgłoszenia

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.

Dołączone do studentWorkReviewUri.

Uwaga: aby zidentyfikować pracę ucznia w przypadku przypisania tego samego załącznika do tego samego ucznia w różnych kursach, możesz użyć klucza złożonego submissionId i attachmentId. Więcej informacji znajdziesz w artykule o kopiowaniu treści.

Token dodatku

Wartość addOnToken to token autoryzacji używany do

addOnAttachments.create, aby utworzyć dodatek.

Dostępny w elementach iframe z funkcją Discovery dla załączników i elementach iframe z funkcją Link Upgrade.

Adres URL do uaktualnienia

Obecność wartości urlToUpgrade oznacza, że

nauczyciel dołączył do projektu załącznik linka i zgodził się na przekształcenie go w załącznik dodatku. Jeśli ta funkcja nie jest jeszcze skonfigurowana, zapoznaj się z poniższym przewodnikiem ulepszania linków do załączników w dodatku, aby dowiedzieć się więcej.

Dostępny w elementzie iframe Link Upgrade.

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 podany w adresie URL iframe src. Jest on wysyłany, gdy użytkownik wcześniej korzystał z Twojego dodatku, aby ułatwić mu logowanie. W implementacji dodatku musisz obsługiwać ten parametr zapytania.

Wskazówka dotycząca logowania

login_hint to unikalny identyfikator konta Google użytkownika.

Konto. Gdy użytkownik zaloguje się do Twojego dodatku po raz pierwszy, parametr login_hint będzie przekazywany przy każdej kolejnej wizycie tego samego użytkownika w dodatku.

Parametr login_hint może być używany na 2 sposoby:

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

Dostępne we wszystkich tagach iframe.

Uwaga: dodatkowe informacje o wdrażaniu parametru login_hint i procesu logowania znajdziesz na stronach SSO, logowania bez tarcia i przeglądu procedury logowania.

Element iframe usługi Attachment Discovery

Wymiar	Opis
Wymagane	Tak
Identyfikator URI	podać w metadanych dodatku,
Parametry zapytania	courseId, itemId, itemType, addOnToken i login_hint.
Wysokość	80% wysokości okna minus 60 pikseli na nagłówek
Szerokość	Maksymalnie 1600 pikseli 90% szerokości okna, jeśli okno ma szerokość do 600 pikseli 80% szerokości okna, jeśli okno ma szerokość powyżej 600 pikseli

Przykładowy scenariusz wykrywania załączników

1. Dodatek do Classroom jest zarejestrowany w Google Workspace Marketplace z identyfikatorem URI usługi rozpoznawania załączników https://example.com/addon.
2. Nauczyciel instaluje ten dodatek i tworzy nowe ogłoszenie, projekt lub materiał w ramach jednego z kursów. 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 czynności w elemencie iframe, aby wybrać załącznik.
5. Po wybraniu załącznika dodatek wysyła do Classroom wiadomość postMessage, aby zamknąć ramkę iframe.

Elementy iframe teacherViewUri i studentViewUri

Wymiar	Opis
Wymagane	Tak
Identyfikator URI	teacherViewUri lub studentViewUri
Parametry zapytania	courseId, itemId, itemType, attachmentId i login_hint.
Wysokość	100% wysokości okna pomniejszone o 140 pikseli na nagłówek górny
Szerokość	100% szerokości okna

studentWorkReviewUri iframe

Wymiar	Opis
Wymagane	Nie (określa, czy jest to załącznik typu Aktywność)
Identyfikator URI	studentWorkReviewUri
Parametry zapytania	courseId, itemId, itemType, attachmentId, submissionId i login_hint.
Wysokość	100% wysokości okna pomniejszonej o 168 pikseli na nagłówek
Szerokość	100% szerokości okna minus szerokość paska bocznego<> pasek boczny ma 312 pikseli w rozwiniętej formie i 56 pikseli w zwiniętej.

Uwaga: nauczyciele mogą otworzyć iframe Sprawdzanie zadań uczniów dla ucznia, który nie wyświetlił wcześniej załączonego dodatku. W takim przypadku wtyczka może nie znać jeszcze tego ucznia i wyświetlić odpowiedni komunikat.

Link Upgrade iframe

Wymiar	Opis
Wymagane	Tak, jeśli uaktualnianie linków do załączników dodatków jest obsługiwane przez Twój dodatek.
Identyfikator URI	podać w metadanych dodatku,
Parametry zapytania	courseId, itemId, itemType, addOnToken, urlToUpgrade i login_hint.
Wysokość	80% wysokości okna minus 60 pikseli na nagłówek
Szerokość	Maksymalnie 1600 pikseli 90% szerokości okna, jeśli okno ma szerokość do 600 pikseli 80% szerokości okna, jeśli okno ma szerokość powyżej 600 pikseli

Przykładowy scenariusz przejścia na nową wersję

1. Dodatek do Classroom jest zarejestrowany z identyfikatorem URI Link Upgrade o wartości https://example.com/upgrade. W przypadku załączników linkowanych przesłano następujące wzorce hosta i ścieżki prefiksów, które Classroom powinna spróbować przekształcić w załącznik dodatku:
   • Host to example.com, a prefiks ścieżki to /quiz.
2. Nauczyciel tworzy nowe ogłoszenie, projekt lub materiał w ramach jednego z kursów. na przykład: itemId=234, itemType=courseWork i courseId=123.
3. Nauczyciel wkleja link (https://example.com/quiz/5678) w oknie „Link do załącznika”, który pasuje do podanego przez Ciebie wzorca adresu URL. Nauczyciel zostanie poproszony o uaktualnienie linku do załącznika dodatku.

4. Classroom uruchamia element iframe Link Upgrade 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. Sprawdzaj parametry zapytania przekazane w iframe i wywołuj punkt końcowy CreateAddOnAttachment. Pamiętaj, że parametr zapytania urlToUpgrade jest zakodowany na potrzeby adresu URL, gdy jest przekazywany w ramce iframe. Aby uzyskać parametr w pierwotnym formacie, musisz go odkodować. Na przykład JavaScript udostępnia funkcję decodeURIComponent().

6. Po utworzeniu załącznika dodatku z linku wysyłasz do Classroom wiadomość postMessage, aby zamknąć ramkę osadzona.

Zamknij element iframe

iframe może zostać zamknięty z poziomu narzędzia do nauki przez wysłanie postMessage z ładunkiem {type: 'Classroom', action: 'closeIframe'}. Classroom akceptuje tylko tę wartość postMessage z host_name+port odpowiadającą pierwotnemu identyfikatorowi URI.

<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 tego elementu

Domena i port strony wysyłającej zdarzenie postMessage muszą być takie same jak domena i port adresu URI użytego do uruchomienia ramki, w przeciwnym razie wiadomość zostanie zignorowana. Aby obejść ten problem, możesz przekierować użytkownika z powrotem na stronę w pierwotnej domenie, która nie robi nic więcej, tylko wysyła zdarzenie postMessage.

Zamykanie iframe z nowej karty

Zapobiegają temu zabezpieczenia między domenami. Aby obejść ten problem, musisz samodzielnie obsługiwać komunikację między iframe i nową kartą, a iframe musi być ostatecznie odpowiedzialny za wysłanie zdarzenia zamknięcia postMessage. Dodatkowo informujemy, że hiperlink „Otwórz w usłudze Nazwa partnera” zostanie usunięty, aby użytkownicy nie mogli w najbliższej przyszłości tworzyć w ten sposób kart.

Ograniczenia

Wszystkie ramki iframe są otwierane z tymi atrybutami piaskownicy:

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

i z zasadami dotyczącymi funkcji

• allow="microphone *"

Blokowanie plików cookie innych firm

Pamiętaj, że blokowanie plików cookie innych firm utrudnia utrzymanie sesji logowania w ramce iframe. Informacje o obecnym stanie blokowania plików cookie w różnych przeglądarkach znajdziesz na stronie https://www.cookiestatus.com. Oczywiście ten problem nie dotyczy tylko dodatków do Google Classroom, ale wszystkie witryny, które używają ramek iframe innych firm. Wielu naszych partnerów napotkało już ten problem.

Oto kilka ogólnych obejść:

• Otwórz nową kartę, aby utworzyć plik cookie w kontekście pierwszej strony. Niektóre przeglądarki udzielają dostępu do plików cookie utworzonych w kontekście własnym, gdy są w kontekście strony trzeciej.
• Poproś użytkownika o zezwolenie na pliki cookie innych firm. Nie zawsze jest to możliwe w przypadku wszystkich użytkowników.
• Projektuj internetowe aplikacje jednostronicowe, które nie opierają się na plikach cookie.

W przyszłych wersjach przeglądarek pojawi się więcej ograniczeń dotyczących plików cookie. Utwórz propozycje funkcji, aby przesłać do Google opinię na temat tego, jak zmniejszyć wzrost wymaganych przez partnerów.

Umożliwienie znajdowania dodatków za pomocą wyrażeń regularnych adresów 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 pasujące do adresów URL zasobów, do których można uzyskać dostęp w Twoim dodatku. Nauczyciel dołączający link, który pasuje do jednego z Twoich wyrażeń regularnych, zobaczy okno, które zachęca do wypróbowania dodatku. Widzi ono to okno tylko wtedy, gdy dodatek jest już zainstalowany na jego koncie.

Jeśli chcesz udostępnić tę funkcję nauczycielom, przekaż kontaktom Google odpowiednie wyrażenia regularne. Jeśli podane przez Ciebie wyrażenia regularne są zbyt ogólne lub kolidują z innym dodatkiem, możemy je zmodyfikować, aby były bardziej restrykcyjne lub bardziej specyficzne.

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

Rysunek 2. Nauczyciel wkleja link z zewnętrznego źródła. Nauczyciel ma już zainstalowany dodatek Classroom innej firmy.

Rysunek 3. Interaktywny dialog wyświetlany nauczycielowi, gdy wklejony link pasuje do wyrażenia regularnego określonego przez dewelopera zewnętrznego.

Jeśli nauczyciel kliknie „Wypróbuj teraz” w wyskakującym okienku, jak pokazano na rysunku 3, zostanie przekierowany do ramki Attachment Discovery Twojego dodatku.