Szczegóły elementu iframe i parametrów zapytania

Dodatki do Classroom są wczytywane w elemencie iframe, aby zapewnić użytkownikom płynną i wygodną obsługę. Istnieją 4 różne typy iframe. Aby dowiedzieć się więcej o celu i wyglądzie każdego z nich, zapoznaj się z stronami iframe w katalogu ścieżek użytkownika.

Wytyczne dotyczące bezpieczeństwa iframe

Partnerzy powinni stosować sprawdzone metody branżowe, aby zabezpieczyć swoje tagi iframe. Nasz zespół ds. zabezpieczeń zaleca następujące sposoby ochrony elementu iframe:

• Protokół HTTPS jest wymagany. Zdecydowanie zalecamy używanie protokołu TLS 1.2 lub nowszego oraz włączenie HTTP Strict Transport Security. Zapoznaj się z artykułem MDN na temat MTA-STS.

• Włącz Strict Content Security Policy. Zapoznaj się z tym artykułem OWASP i powiązanym artykułem MDN na temat polityki bezpieczeństwa treści.

• Włącz atrybut pliku cookie Secure. Zapoznaj się z atrybutem HttpOnly oraz z artykułem MDN o plikach cookie.

Konfiguracja identyfikatora URI iframe

Identyfikator URI konfiguracji załączników zawiera element iframe wykrywania załączników i tam nauczyciele rozpoczynają proces tworzenia załączników dodatków w poście w Classroom. Możesz go ustawić w konsoli projektu Google Cloud. Ustaw ten identyfikator URI w projekcie Google Cloud w sekcji Interfejs API i usługa > 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 do dosłownego prefiksu ciągu znaków i obecnie nie pozwala na używanie symboli wieloznacznych.

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ą dodatku informacje o zajęciach, projekcie, załączniku dodatku, przesłanych przez ucznia i tokenie autoryzacji.

Identyfikator zajęć

Wartość courseId jest identyfikatorem zajęć.

Uwzględniony we wszystkich elementach iframe.

Identyfikator produktu

Wartość itemId jest identyfikatorem elementu Announcement,

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

Dostępne we wszystkich tagach iframe.

Typ elementu

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

załącznik. Przekazana wartość ciągu to "announcements", "courseWork" lub "courseWorkMaterials".

Dostępne we wszystkich tagach iframe.

Identyfikator załącznika

Wartość attachmentId jest identyfikatorem załącznika.

Dostępne w przypadku ramek iframe teacherViewUri, studentViewUri i studentWorkReviewUri.

Identyfikator zadania

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: możesz użyć klucza złożonego submissionId i attachmentId, aby zidentyfikować pracę ucznia w sytuacji, gdy ten sam załącznik jest przypisany temu samemu uczniowi na różnych zajęciach. Więcej informacji znajdziesz w artykule o kopiowaniu treści.

Token dodatku

Wartość addOnToken to token autoryzacji używany do

addOnAttachments.create wywołania, aby utworzyć dodatek.

Uwzględnione w elemencie iframe wykrywania załączników i elemencie iframe uaktualnienia linku.

URL do uaktualnienia

Obecność wartości urlToUpgrade oznacza, że

nauczyciel dodał do projektu załącznik linka i zgodził się na przekształcenie go w załącznik dodatku. Jeśli ta funkcja nie jest jeszcze skonfigurowana, więcej informacji znajdziesz w przewodniku ulepszania linków do załączników w dodatku.

Dołączony do elementu iframe Link Upgrade.

Parametry związane z logowaniem

Parametr zapytania login_hint zawiera informacje o tym, że użytkownik Classroom odwiedza stronę internetową dodatku. Ten parametr zapytania jest podawany w adresie URL elementu iframe src. Jest on wysyłany, gdy użytkownik wcześniej korzystał z Twojego dodatku, aby ułatwić mu logowanie. W ramach 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ł podawać 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ć jego wartość z wartościami wszystkich użytkowników, którzy mogą być 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.

Uwzględniony we wszystkich elementach iframe.

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

Element iframe usługi Attachment Discovery

Wymiar	Opis
Wymagane	Tak
Identyfikator URI	Podane w metadanych dodatku
Parametry zapytania	courseId, itemId, itemType, addOnToken i login_hint.
Wysokość	wysokość okna 80% minus 60 pikseli w przypadku górnego nagłówka.
Szerokość	Maksymalnie 1600 pikseli 90% szerokości okna, jeśli okno ma mniej niż 600 pikseli 80% szerokości okna, jeśli okno ma więcej niż 600 pikseli

Przykładowy scenariusz wykrywania załączników

1. Dodatek do Classroom jest zarejestrowany w Google Workspace Marketplace przy użyciu identyfikatora URI wykrywania załączników o wartości 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 educationViewUri 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ść	Szerokość okna: 100%

Element iframe studentWorkReviewUri

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	Podane w metadanych dodatku
Parametry zapytania	courseId, itemId, itemType, addOnToken, urlToUpgrade i login_hint.
Wysokość	wysokość okna 80% minus 60 pikseli w przypadku górnego nagłówka.
Szerokość	Maksymalnie 1600 pikseli 90% szerokości okna, gdy okno ma <= 600 pikseli szerokość 80% szerokości, gdy okno jest > 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 prefiksów hosta i ścieżki, 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 w oknie załączania linku link (https://example.com/quiz/5678), który pasuje do podanego przez Ciebie wzorca adresu URL. Nauczyciel zobaczy prośbę 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 ramce 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ć pierwotną postać parametru, musisz go odkodować. Na przykład JavaScript udostępnia funkcję decodeURIComponent().

6. Po utworzeniu załącznika dodatku za pomocą linku wyślesz do Classroom element postMessage, aby zamknąć element iframe.

Zamknij element iframe

Element iframe można zamknąć w narzędziu do nauki, wysyłając obiekt postMessage z ładunkiem {type: 'Classroom', action: 'closeIframe'}. Classroom akceptuje tylko tę wartość postMessage z host_name+port odpowiadającą pierwotnemu 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>

Zamykanie elementu iframe

Domena+port strony wysyłającej zdarzenie postMessage musi mieć ten sam port domeny co identyfikator URI użyty do uruchomienia elementu iframe. W przeciwnym razie wiadomość zostanie zignorowana. Można obejść ten problem, przekierowując z powrotem na stronę w pierwotnej domenie, która jest poza wysyłaniem zdarzenia postMessage.

Zamykanie elementu iframe w nowej karcie

Zabezpieczenia w wielu domenach uniemożliwiają to. Aby obejść ten problem, musisz samodzielnie obsługiwać komunikację między iframe a nową kartą i pozostawić iframe odpowiedzialność 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

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 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 już to napotkało.

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

• 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 zewnętrznym.
• Poproś użytkownika o zezwolenie na pliki cookie innych firm. Nie zawsze jest to możliwe w przypadku wszystkich użytkowników.
• Projektuj jednostronicowe aplikacje internetowe, które nie opierają się na plikach cookie.

W przyszłych wersjach przeglądarek pojawi się więcej ograniczeń dotyczących plików cookie. tworzyć prośby o dodanie funkcji, aby przesyłać do Google opinie na temat sposobu zmniejszenia wzrostu wymaganego 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 ułatwić korzystanie z dodatku, możesz określić wyrażenia regularne pasujące do adresów URL zasobów, do których ten dodatek ma dostęp. Nauczyciel dołączający link pasujący do jednego z Twoich wyrażeń regularnych zobaczy okno, które zachęca do wypróbowania dodatku. To okno jest widoczne tylko wtedy, gdy dodatek jest już zainstalowany na ich koncie.

Jeśli chcesz udostępnić tę funkcję nauczycielom, prześlij odpowiednie wyrażenia regularne do kontaktów Google. Jeśli podane przez Ciebie wyrażenia regularne są zbyt ogólne lub kolidują z innym dodatkiem, mogą zostać zmodyfikowane tak, aby były bardziej ograniczone lub bardziej zróżnicowane.

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. Interaktywne okno wyświetlane nauczycielowi, gdy wklejony link pasuje do wyrażenia regularnego określonego przez programistę 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.