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 elementów iframe. Na stronach iframe w katalogu User Journeys znajdziesz informacje o przeznaczeniu i wyglądzie poszczególnych elementów iframe.

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

Partnerzy powinni stosować sprawdzone metody branżowe w celu zabezpieczenia elementów iframe. Nasz zespół ds. zabezpieczeń zaleca następujące sposoby ochrony elementu iframe:

• Wymagany jest protokół HTTPS. Zdecydowanie zalecamy korzystanie z protokołu TLS 1.2 lub nowszego i włączenie HTTP Strict Transport Security. Przeczytaj ten powiązany artykuł w MDN na temat rygorystycznego zachowania bezpieczeństwa transportu (Strict Transport Security).

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

• Włącz atrybut Bezpieczne pliki cookie. Zobacz atrybut HttpOnly i ten artykuł w MDN na temat plików cookie.

Konfiguracja identyfikatora URI elementu 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żna 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 to dopasowanie prefiksu ciągu znaków dosłownego i nie zezwala obecnie na używanie symboli wieloznacznych.

Parametry zapytania

Elementy iframe przekazują ważne informacje do dodatku w postaci parametrów zapytania. Istnieją 2 kategorie parametrów: związane z przyłączami i związane z logowaniem.

Parametry związane z załącznikami

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 elementu

Wartość itemId jest identyfikatorem elementu Announcement,

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

Uwzględniony we wszystkich elementach iframe.

Typ elementu

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

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

Uwzględniony we wszystkich elementach iframe.

Identyfikator załącznika

Wartość attachmentId jest identyfikatorem załącznika.

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

Identyfikator zadania

Wartość submissionId jest identyfikatorem zadania ucznia, ale należy jej używać w połączeniu z wartością attachmentId, aby zidentyfikować zadanie ucznia w danym projekcie.

W pakiecie z 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 kopiowanych treściach.

Token dodatku

Wartość addOnToken to token autoryzacji używany do

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

Uwzględniono w elemencie iframe Odkrywanie załączników i elemencie iframe uaktualniania linków.

URL do uaktualnienia

Obecność wartości urlToUpgrade oznacza, że

nauczyciel dołączył do projektu załącznik z linkiem i zgodził się uaktualnić go do załącznika dodatku. Jeśli nie masz jeszcze skonfigurowanej tej funkcji, zapoznaj się z przewodnikiem na temat aktualizacji linków do dodatków, w którym znajdziesz więcej informacji.

Uwzględnione w elemencie iframe uaktualniania linków.

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 ona wysyłana, gdy użytkownik wcześniej skorzystał z Twojego dodatku, aby ułatwić użytkownikowi logowanie. Musisz obsługiwać ten parametr zapytania w swojej implementacji dodatku.

Wskazówka dotycząca logowania

login_hint to unikalny identyfikator konta Google użytkownika

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

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

1. Przekaż wartość login_hint podczas procesu uwierzytelniania, aby użytkownik nie musiał wpisywać swoich danych logowania w oknie logowania. Użytkownik nie zaloguje się automatycznie.
2. Gdy użytkownik się zaloguje, użyj tego parametru, aby porównać wartość ze wszystkimi użytkownikami, którzy byli już zalogowani w dodatku. Jeśli znajdziesz dopasowanie, możesz pozostawić użytkownika zalogowanym i uniknąć procesu logowania. Jeśli parametr nie pasuje do żadnego z zalogowanych użytkowników, poproś go o zalogowanie się za pomocą przycisku logowania z logo Google.

Uwzględniony we wszystkich elementach iframe.

Uwaga: dodatkowe informacje o implementowaniu parametru login_hint i procesie logowania można znaleźć na stronach SSO, Bezproblemowe logowanie i Obsługa powtarzanych logowania.

Element iframe wykrywania załączników

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, gdy okno ma <= 600 pikseli szerokość 80% szerokości, gdy okno jest > 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 ze swoich 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 źródła ustawionym na https://example.com/addon?courseId=123&itemId=234&itemType=courseWork&addOnToken=456.
   1. Nauczyciel dokonuje wyboru w elemencie iframe, aby wybrać załącznik.
5. Po wybraniu załącznika dodatek wysyła postMessage do Classroom, aby zamknąć element 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ść	wysokość okna 100% minus 140 pikseli w przypadku górnego nagłówka.
Szerokość	Szerokość okna: 100%

Element iframe studentWorkReviewUri

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

Uwaga: nauczyciele mogą otworzyć element iframe Sprawdzanie pracy ucznia, 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 zaktualizowanie linków do załączników dodatków.
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 uaktualnienia linku

1. Dodatek do Classroom jest zarejestrowany przy użyciu identyfikatora URI uaktualnienia linku https://example.com/upgrade. Podane zostały te wzorce hostów i prefiksów ścieżek dla załączników linków, które Classroom ma spró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 ze swoich zajęć. 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 „Uaktualnienie linku” 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 przekazywane w elemencie iframe i wywołujesz punkt końcowy CreateAddOnAttachment. Pamiętaj, że parametr zapytania urlToUpgrade jest zakodowany w identyfikatorze URI podczas przekazywania w elemencie iframe. Musisz go zdekodować, by uzyskać go w pierwotnej postaci. Na przykład JavaScript oferuje 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 element postMessage z ładunkiem {type: 'Classroom', action: 'closeIframe'}. Classroom akceptuje tylko ten identyfikator postMessage z nazwy hosta i portu odpowiadającego 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ą takie działanie. Można obejść ten problem, samodzielnie zarządzając komunikacją między elementem iframe a nową kartą i pozostawiając odpowiedzialność elementu iframe za wywołanie zdarzenia zamknięcia postMessage. Na marginesie informujemy, że hiperlink „Otwórz w nazwie partnera” jest usuwany, aby użytkownicy nie mogli w najbliższej przyszłości 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. Oczywiście ten problem nie dotyczy tylko dodatków do Google Classroom i dotyczy wszystkich stron internetowych 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 własnym. Niektóre przeglądarki przyznają dostęp do plików cookie utworzonych we własnym kontekście w kontekście danych innych firm.
• Poproś użytkownika o zgodę na używanie plików cookie innych firm. Nie zawsze jest to możliwe w przypadku niektórych użytkowników.
• Projektuj jednostronicowe aplikacje internetowe, które nie opierają się na plikach cookie.

W przyszłych wersjach przeglądarek spodziewamy się większej liczby 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.

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

Nauczyciele często tworzą projekty z załączonymi linkami. 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łącza link, który pasuje do jednego z Twoich wyrażeń regularnych, i widzi okno dialogowe, które można zamknąć, zachęcające do wypróbowania dodatku. To okno wyświetli się tylko wtedy, gdy dodatek jest już zainstalowany na ich koncie.

Jeśli chcesz umożliwić nauczycielom korzystanie z takich funkcji, użyj odpowiednich wyrażeń regularnych. 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 link 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 programistę zewnętrznego.

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