Szczegóły elementu iframe i parametrów zapytania

Dodatki do Classroom są wczytywane w elemencie iframe, aby zapewnić użytkownikom wygodę i płynność działania. Istnieje 5 rodzajów elementów iframe. Na stronach dotyczących elementów iframe w katalogu ścieżek użytkownika znajdziesz omówienie ich przeznaczenia i wyglądu.

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

Programiści powinni stosować sprawdzone metody branżowe, aby zabezpieczyć ramkę iframe. W przepływie użytkownika należy jednak uwzględnić pewne interakcje z interfejsem API, aby potwierdzić, że masz prawidłowe dane logowania i możesz poprawnie określić rolę użytkownika w kursie.

Konfiguracja aplikacji serwera

Aby zabezpieczyć element iframe, zalecamy te konfiguracje serwera:

• Wymagany jest protokół HTTPS. Zdecydowanie zalecamy używanie protokołu TLS w wersji 1.2 lub nowszej oraz włączenie mechanizmu HTTP Strict Transport Security (HSTS). Przeczytaj ten artykuł w MDN na temat protokołu Strict Transport Security.
• Włącz ścisły standard Content Security Policy (Strict CSP). Zapoznaj się z tym artykułem OWASP i tym artykułem MDN na temat Content Security Policy.
• Włącz atrybut bezpiecznego pliku cookie. Zobacz atrybut HttpOnly i powiązany artykuł MDN na temat plików cookie.

Parametry zapytania

Ramki 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łącznikiem dostarczają dodatkowi informacji o zajęciach, projekcie, załączniku dodatku, przesłanym przez ucznia zadaniu i tokenie autoryzującym.

Identyfikator zajęć

Wartość courseId to identyfikator kursu.

Jest on uwzględniany we wszystkich elementach iframe.

Identyfikator produktu

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

Jest on uwzględniany we wszystkich elementach iframe.

Typ elementu

Wartość itemType określa typ zasobu, do którego jest dołączony ten załącznik. Przekazana wartość ciągu tekstowego to "announcements", "courseWork" lub "courseWorkMaterials".

Jest on uwzględniany we wszystkich elementach iframe.

Identyfikator załącznika

Wartość attachmentId to identyfikator załącznika.

Dostępne w przypadku elementó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 zadania.

Dostępne w ramach studentWorkReviewUri.

Token dodatku

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

Dostępne w ramce iframe wykrywania załączników i ramce 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 przekształcenie go w załącznik z dodatkiem. Jeśli nie masz jeszcze skonfigurowanej tej funkcji, więcej informacji znajdziesz w przewodniku na temat ulepszania linków w celu dodawania załączników.

Dostępne w elemencie iframe Link Upgrade.

Parametry związane z logowaniem

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

Podpowiedź logowania

login_hint to unikalny identyfikator konta Google użytkownika. Po pierwszym zalogowaniu się użytkownika w dodatku parametr login_hint jest 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 użytkownikami, 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ś użytkownika o zalogowanie się za pomocą przycisku logowania oznaczonego logo Google.

Jest on uwzględniany we wszystkich elementach iframe.

Element iframe do wykrywania załączników

Przykładowy scenariusz 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 jednym ze swoich 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 źródła 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;

studentWorkReviewUri iframe

Element iframe Uaktualnij link

Przykładowy scenariusz uaktualnienia linku

1. Dodatek do Classroom jest zarejestrowany z adresem URI uaktualnienia linku https://example.com/upgrade. Podano te wzorce hostów i przedrostków ścieżek dla załączników z linkami, które Classroom powinien spróbować przekształcić w załączniki dodatków:
   • Host to example.com, a prefiksem ścieżki jest /quiz.
2. Nauczyciel tworzy nowe ogłoszenie, projekt lub materiał w jednym ze swoich kursów. Na przykład: itemId=234, itemType=courseWork i courseId=123.
3. Nauczyciel wkleja link https://example.com/quiz/5678 w oknie dialogowym Załącznik linku, który pasuje do podanego przez Ciebie wzorca adresu URL. Nauczyciel otrzyma wtedy prośbę o uaktualnienie linku do załącznika dodatku.

4. Classroom uruchamia element iframe Ulepsz link z ustawionym adresem URL 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 przekazywane w ramce iframe i wywołujesz CreateAddOnAttachment punkt końcowy. Pamiętaj, że parametr zapytania urlToUpgrade jest zakodowany w formacie URI, gdy jest przekazywany w elemencie iframe. Aby uzyskać parametr w oryginalnej postaci, musisz go zdekodować. Na przykład JavaScript udostępnia funkcję decodeURIComponent().

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

Zamknij element iframe

Ramkę iframe można zamknąć z poziomu narzędzia do nauki, wysyłając komunikat postMessage z ładunkiem {type: 'Classroom', action: 'closeIframe'}. Classroom akceptuje tylko ten postMessage z host_name+port odpowiadający oryginalnemu otwartemu 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 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 wiadomość zostanie zignorowana. Obejście tego problemu polega na przekierowaniu z powrotem na stronę w oryginalnej domenie, która nie robi nic poza wysyłaniem zdarzenia postMessage.

Zamykanie elementu iframe z nowej karty

Ochrona przed atakami w wielu domenach uniemożliwia takie działanie. Obejście tego problemu polega na samodzielnym obsłużeniu komunikacji między elementem iframe a nową kartą i umożliwieniu elementowi iframe ostatecznego wyemitowania zdarzenia zamknięcia postMessage. Na marginesie dodamy, że hiperlink „Otwórz w usłudze Partner Name” zostanie usunięty, aby użytkownicy nie mogli w ten sposób tworzyć kart w najbliższej przyszłości.

Ograniczenia

Wszystkie elementy 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 te zasady dotyczące 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 bieżącym 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 wszystkich witryn, które osadzają w ramkach treści innych firm. Wielu naszych partnerów już spotkało się z tym problemem.

Oto kilka ogólnych sposobów obejścia tego problemu:

• Otwórz nową kartę, aby utworzyć plik cookie w kontekście własnym. Niektóre przeglądarki udostępniają pliki cookie utworzone w kontekście własnym 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 internetowe aplikacje SPA, które nie opierają się na plikach cookie.

W przyszłych wersjach przeglądarek spodziewamy się kolejnych ograniczeń dotyczących plików cookie. Twórz prośby o funkcje, aby przesyłać do Google opinie o tym, 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 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 dodatku. Gdy nauczyciel dołącza link pasujący do jednego z Twoich wyrażeń regularnych, wyświetla się okno z możliwością zamknięcia, które zachęca go do wypróbowania dodatku. Okno dialogowe jest widoczne tylko wtedy, gdy dodatek jest już zainstalowany na koncie użytkownika.

Jeśli chcesz udostępnić to działanie nauczycielom, przekaż odpowiednie wyrażenia regularne swoim kontaktom 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 ich zakresu lub odróżnienia ich od innych wyrażeń.

Rysunek 1. Nauczyciel wybiera link załączony do nowego zadania.

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

Rysunek 3. Interaktywne okno dialogowe wyświetlane nauczycielowi, gdy wklejony link pasuje do wyrażenia regularnego określonego przez dewelopera zewnętrznego.

Jeśli nauczyciel wybierze „Wypróbuj teraz” w wyskakującym okienku widocznym na ilustracji 3, zostanie przekierowany do ramki iframe wykrywania załączników dodatku.