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 elementuAnnouncement
,CourseWork
lubCourseWorkMaterial
, 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 jestzałą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
istudentWorkReviewUri
.- 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
.
- Token dodatku
Wartość
addOnToken
to token autoryzacji używany doaddOnAttachments.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, żenauczyciel 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żytkownikaUstawienia. 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:- 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. - 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.
- Przekaż wartość
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
- 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
. - 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
icourseId=123
. - Podczas konfigurowania tego elementu nauczyciel wybiera nowo zainstalowany dodatek jako załącznik.
- Classroom tworzy element iframe z adresem URL źródła ustawionym na
https://example.com/addon?courseId=123&itemId=234&itemType=courseWork&addOnToken=456
.- Nauczyciel dokonuje wyboru w elemencie iframe, aby wybrać załącznik.
- 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 |
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
- 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
.
- Host to
- Nauczyciel tworzy nowe ogłoszenie, projekt lub materiał w ramach jednego ze swoich zajęć. Na przykład:
itemId=234
,itemType=courseWork
icourseId=123
. - 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. 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
.Oceniasz parametry zapytania przekazywane w elemencie iframe i wywołujesz punkt końcowy
CreateAddOnAttachment
. Pamiętaj, że parametr zapytaniaurlToUpgrade
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()
.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.