Szczegóły elementu iframe i parametrów zapytania

Dodatki do Classroom są ładowane w elemencie iframe, aby zapewnić użytkownikowi wygodę i wygodę pracy. Istnieją 4 różne typy elementów iframe. Na stronach elementów iframe w katalogu Ścieżki użytkownika znajdziesz omówienie przeznaczenia i wyglądu poszczególnych elementów iframe.

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

Partnerzy powinni przestrzegać sprawdzonych metod branżowych, aby zabezpieczyć swoje elementy iframe. Aby chronić element iframe, nasz zespół ds. zabezpieczeń zaleca wykonanie tych czynności:

• Protokół HTTPS jest wymagany. Zdecydowanie zalecamy korzystanie z protokołu TLS w wersji 1.2 lub nowszej i włączenie HTTP Strict Transport Security. Zapoznaj się z tym artykułem w MDN dotyczącym rygorystycznego bezpieczeństwa transportu.

• Włącz Strict Content Security Policy. Zapoznaj się z tym artykułem OWASP i powiązanym artykułem Content Security Policy MDN.

• Włącz Atrybut bezpiecznego pliku cookie. Zapoznaj się z atrybutem HttpOnly i tym artykułem na temat plików cookie w MDN.

Konfiguracja identyfikatora URI elementu iFrame

Identyfikator URI konfiguracji załączników wczytuje element iframe wykrywania załączników i od którego nauczyciele rozpoczynają proces tworzenia załączników dodatków do postów w Classroom. Można go ustawić w konsoli projektu Google Cloud. Ustaw ten identyfikator URI na stronie Interfejsy API i usługa w projekcie Google Cloud > Pakiet SDK Google Workspace Marketplace > Konfiguracja aplikacji.

Dozwolone prefiksy identyfikatorów URI załączników służą do weryfikowania identyfikatorów URI ustawionych w AddOnAttachment przy użyciu metod *.addOnAttachments.create i *.addOnAttachments.patch. Weryfikacja polega na dopasowaniu prefiksu ciągu znaków dosłownego i obecnie nie można używać symboli wieloznacznych.

Parametry zapytania

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

Parametry związane z załącznikami

Parametry związane z załącznikami dostarczają do dodatku informacje o zajęciach, projekcie, załączniku dodatku, zadaniach ucznia i tokenie autoryzacji.

Identyfikator zajęć

Wartość courseId to identyfikator zajęć.

Uwzględnione we wszystkich elementach iframe.

Identyfikator posta (wycofany)

Wartość postId to identyfikator posta (ogłoszenia, zadania lub materiału na zajęciach), do którego dołączony jest ten załącznik.

Uwzględnione we wszystkich elementach iframe.

Wycofane: identyfikator posta został wycofany. Użyj identyfikatora produktu.

Identyfikator elementu

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

Uwzględnione we wszystkich elementach iframe.

Typ elementu

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

Uwzględnione we wszystkich elementach iframe.

Identyfikator załącznika

Wartość attachmentId jest identyfikatorem załącznika.

Obejmuje elementy iframe teacherViewUri, studentViewUri i studentWorkReviewUri.

Identyfikator zadania

Wartość submissionId to identyfikator pracy ucznia, ale należy jej używać w połączeniu z wartością attachmentId do identyfikowania pracy ucznia w konkretnym projekcie.

Dostępne w studentWorkReviewUri.

Uwaga: jeśli ten sam załącznik zostanie przypisany temu samemu uczniowi na różnych zajęciach, możesz użyć klucza złożonego submissionId i attachmentId, aby zidentyfikować zadanie ucznia. Więcej informacji znajdziesz w sekcji Skopiowane treści.

Token dodatku

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

Zawiera element iframe wykrywania załączników i element iframe uaktualnienia linku.

URL do uaktualnienia

Obecność wartości urlToUpgrade oznacza, że nauczyciel umieścił w projekcie załącznik z linkiem i zgodził się uaktualnić go do postaci załącznika dodatku. Jeśli ta funkcja nie jest jeszcze skonfigurowana, więcej informacji znajdziesz w przewodniku dotyczącym uaktualniania linków do załączników.

Wraz z elementem iframe uaktualnienia linku.

Parametry dotyczące logowania

Parametr zapytania login_hint zawiera informacje o użytkowniku Classroom odwiedzającym stronę internetową dodatku. Ten parametr zapytania jest dostarczany w adresie URL elementu iframe src. Jest ona wysyłana, gdy użytkownik wcześniej używał Twojego dodatku, aby ułatwić użytkownikom logowanie się. Musisz obsługiwać ten parametr zapytania w swojej implementacji dodatku.

Podpowiedź dotycząca logowania

login_hint to unikalny identyfikator Google

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

Parametr login_hint może mieć dwa możliwe zastosowania:

1. Przekaż wartość login_hint w procesie uwierzytelniania, aby użytkownik nie musiał wpisywać danych logowania, gdy pojawi się okno logowania. Użytkownik nie jest zalogowany automatycznie.
2. Gdy użytkownik się zaloguje, użyj tego parametru, aby porównać wartość z użytkownikami, którzy byli już zalogowani w dodatku. Jeśli znajdziesz odpowiedniki, możesz pozostawić użytkownika zalogowanego i uniknąć wyświetlania ekranu logowania. Jeśli parametr nie jest zgodny z żadnym z zalogowanych użytkowników, poproś go o zalogowanie się za pomocą przycisku logowania marki Google.

Uwzględnione we wszystkich elementach iframe.

Uwaga: dodatkowe informacje na temat wdrażania parametru login_hint oraz procesu logowania można znaleźć na stronach SSO, Bezproblemowe logowanie i Obsługa powtarzania logowania.

Element iframe wykrywania załączników

Wymiar	Opis
Wymagane	Tak
Identyfikator URI	Podane w metadanych dodatku
Parametry zapytania	courseId, postId (wycofany), itemId, itemType, addOnToken i login_hint.
Wzrost	80% wysokości okna minus 60 pikseli dla górnego nagłówka
Szerokość	Maksymalnie 1600 pikseli 90% szerokości okna przy szerokości <= 600 pikseli 80% szerokości okna powyżej 600 pikseli

Przykładowy scenariusz wykrywania załączników

1. Dodatek do Classroom został zarejestrowany w Google Workspace Marketplace przy użyciu identyfikatora URI Attachment Discovery o identyfikatorze https://example.com/addon.
2. Nauczyciel instaluje ten dodatek i tworzy nowe ogłoszenie, projekt lub materiał w jednym ze swoich zajęć. np. 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 źródłowym adresem URL ustawionym na https://example.com/addon?courseId=123&itemId=234&itemType=courseWork&addOnToken=456.
   1. Nauczyciel wykonuje pracę w elemencie iframe, wybierając załącznik.
5. Po wybraniu załącznika dodatek wysyła do Classroom element postMessage, aby zamknąć element iframe.

Elementy iframe TeacherViewUri i studentViewUri

Wymiar	Opis
Wymagane	Tak
Identyfikator URI	teacherViewUri lub studentViewUri
Parametry zapytania	courseId, postId (wycofany), itemId, itemType, attachmentId i login_hint.
Wzrost	100% wysokości okna minus 140 pikseli dla górnego nagłówka
Szerokość	100% szerokości okna

Element iframe studentWorkReviewUri

Wymiar	Opis
Wymagane	Nie (określa, czy jest to załącznik typu aktywność)
Identyfikator URI	studentWorkReviewUri
Parametry zapytania	courseId, postId (wycofany), itemId, itemType, attachmentId, submissionId i login_hint.
Wzrost	100% wysokości okna minus 168 pikseli dla górnego nagłówka
Szerokość	100% szerokości okna pomniejszona o szerokość paska bocznego<> pasek boczny ma 312 pikseli po rozwinięciu i 56 pikseli po zwiniętym

Uwaga: nauczyciele mogą otworzyć element iframe z oceną zadań uczniów, który nie widział wcześniej załącznika dodatku. W takim przypadku dodatek może jeszcze nie wiedzieć o tym uczniu i powinien wyświetlić odpowiedni komunikat.

Element iframe uaktualnienia linku

Wymiar	Opis
Wymagane	Tak, jeśli dodatek obsługuje uaktualnianie linków do załączników dodatków.
Identyfikator URI	Podane w metadanych dodatku
Parametry zapytania	courseId, postId (wycofany), itemId, itemType, addOnToken, urlToUpgrade i login_hint.
Wzrost	80% wysokości okna minus 60 pikseli dla górnego nagłówka
Szerokość	Maksymalnie 1600 pikseli 90% szerokości okna przy szerokości <= 600 pikseli 80% szerokości okna powyżej 600 pikseli

Przykładowy scenariusz uaktualnienia linku

1. Dodatek do Classroom został zarejestrowany przy użyciu identyfikatora URI uaktualnienia linku https://example.com/upgrade. Podano te wzorce prefiksów hostów i ścieżek dla załączników do linków, które usługa Classroom powinna starać się 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 ze swoich zajęć. Na przykład itemId=234, itemType=courseWork i courseId=123.
3. Nauczyciel wkleja w oknie Załącznika link https://example.com/quiz/5678, który pasuje do podanego przez Ciebie wzorca adresu URL. Następnie nauczyciel zostanie poproszony o uaktualnienie linku do załącznika dodatku.

4. Classroom uruchamia element iframe uaktualnienia linku z adresem URL ustawionym na https://example.com/upgrade?courseId=123&postId=234&addOnToken=456&urlToUpgrade=https%3A%2F%2Fexample.com%2Fquiz%2F5678.

5. Oceniasz parametry zapytania przekazane w elemencie iframe i wywołujesz wywołanie do punktu końcowego CreateAddOnAttachment. Pamiętaj, że parametr zapytania urlToUpgrade przekazywany w elemencie iframe jest zakodowany jako identyfikator URI. Aby uzyskać go w pierwotnej postaci, musisz go zdekodować. Na przykład JavaScript udostępnia funkcję decodeURIComponent().

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

Zamknij element iframe

Element iframe można zamknąć z poziomu narzędzia do uczenia się, wysyłając element postMessage z ładunkiem {type: 'Classroom', action: 'closeIframe'}. Classroom akceptuje tylko ten identyfikator postMessage z nazwy hosta i portu odpowiadającego oryginalnemu identyfikatorowi 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>

Zamknij element iframe z elementu iframe

Domena i port strony wysyłającej zdarzenie postMessage muszą mieć ten sam port domeny i portu co identyfikator URI użyty do uruchomienia elementu iframe. W przeciwnym razie komunikat zostanie zignorowany. Obejściem tego problemu jest przekierowanie z powrotem na stronę w pierwotnej domenie, która nie robi nic więcej niż wysyła zdarzenie postMessage.

Zamykanie elementu iframe w nowej karcie

Zabezpieczenia w wielu domenach uniemożliwiają działanie tej funkcji. Obejściem jest samodzielne zarządzanie komunikacją między elementem iframe a nową kartą i pozwolenie elementowi iframe na wywołanie zdarzenia zamykającego postMessage. Uwaga: usuwamy hiperlink „Otwórz w nazwie partnera”, aby w najbliższej przyszłości użytkownicy nie mogli tworzyć kart w ten sposób.

Ograniczenia

Wszystkie elementy iframe są otwierane za pomocą tych atrybutów piaskownicy:

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

oraz następujące zasady dotyczące funkcji

• allow="microphone *"

Blokowanie plików cookie innych firm

Pamiętaj, że blokowanie plików cookie innych firm utrudnia utrzymanie sesji zalogowanej w elemencie iframe. Informacje o bieżącym stanie blokowania plików cookie w różnych przeglądarkach znajdziesz na stronie https://www.cookiestatus.com. Ten problem nie dotyczy oczywiście dodatków do Google Classroom i dotyczy wszystkich stron internetowych innych firm iframe. Wielu naszych partnerów spotkało się już z tym problemem.

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

• Otwórz nową kartę, aby utworzyć plik cookie we własnym kontekście. Niektóre przeglądarki przyznają dostęp do plików cookie utworzonych w kontekście własnym, gdy działają w kontekście innych firm.
• Poproś użytkownika o zezwolenie na pliki cookie innych firm. Nie zawsze jest to możliwe w przypadku niektórych użytkowników.
• Projektuj aplikacje internetowe jednostronicowe, które nie korzystają z plików cookie.

W przyszłych wersjach przeglądarek wprowadzimy więcej ograniczeń dotyczących plików cookie. Utwórz prośby o dodanie funkcji, aby przesłać do Google opinię o tym, jak obniżyć wyniki wymagane przez partnerów.

Włącz wykrywalność dodatków za pomocą wyrażeń regularnych w URL-ach

Nauczyciele często tworzą projekty z załącznikami. 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. Nauczyciel, który dołączy link pasujący do jednego z wyrażeń regularnych, zobaczy okno, które można zamknąć, zachęcające do wypróbowania dodatku. Zobaczą je tylko wtedy, gdy dodatek jest już zainstalowany na ich koncie.

Jeśli chcesz umożliwić nauczycielom zachowanie takiego zachowania, udostępnij swoim kontaktom Google odpowiednie wyrażenia regularne. Jeśli podane wyrażenia regularne są zbyt ogólne lub kolidują z innym dodatkiem, mogą zostać zmodyfikowane, aby były bardziej ograniczone lub inne.

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 innej firmy.

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

Jeśli nauczyciel wybierze w wyskakującym okienku „Wypróbuj teraz” (tak jak na rys. 3), zostanie przekierowany do elementu iframe wykrywania załączników dodatku.