클래스룸 부가기능은 iframe 내에 로드되어 최종 사용자에게 원활하고 편리한 사용자 환경을 제공합니다. 머신러닝 모델에 iframe 유형 사용자 경험 디렉터리의 iframe 페이지에서 각 iframe의 목적과 모양에 대한 개요가 나와 있습니다.
iframe 보안 가이드라인
파트너는 업계 권장사항에 따라 iframe을 보호해야 합니다. iframe을 보호하려면 Google 보안팀에서 다음을 권장합니다.
HTTPS는 필수 항목입니다. TLS 1.2 이상을 사용하고 HTTP Strict Transport Security를 사용 설정합니다. 관련 MDN 보기 도움말을 참조하세요.
Strict Content Security Policy를 사용 설정합니다. 이 OWASP를 참조하세요. 도움말과 관련 콘텐츠 보안 정책 MDN 문서를 참조하세요.
보안 쿠키 속성을 사용 설정합니다. HttpOnly 속성 및 다음을 참조하세요. 관련 쿠키 MDN 문서를 참조하세요.
iFrame URI 구성
첨부파일 설정 URI는 첨부파일 검색 iframe이 로드하는 것입니다. 교사가 클래스룸에서 부가기능 첨부파일을 만드는 과정을 클래스룸 게시물 Google Cloud 프로젝트 콘솔에서 설정할 수 있습니다. Google Cloud 프로젝트의 API에서 이 URI를 설정하고 서비스 > Google Workspace Marketplace SDK > App Configuration(앱 구성) 페이지
허용된 첨부파일 URI 프리픽스는
AddOnAttachment 다음을 사용하여 *.addOnAttachments.create
및
*.addOnAttachments.patch
메서드와 함께 사용할 수 있습니다. 유효성 검사는 리터럴 문자열 접두사입니다.
일치하며 현재는 와일드 카드 사용을 허용하지 않습니다.
쿼리 매개변수
iframe은 중요한 정보를 부가기능에 쿼리 매개변수로 전달합니다. 매개변수에는 첨부파일 관련 매개변수와 로그인 관련 매개변수라는 두 가지 카테고리가 있습니다. 매개변수입니다.
첨부파일 관련 매개변수
첨부파일 관련 매개변수는 부가기능에 과제, 부가기능 첨부파일, 학생의 제출물, 토큰입니다.
- 수업 ID
courseId
값은 과정의 식별자입니다.모든 iframe에 포함됩니다.
- 상품 ID
itemId
값은Announcement
의 식별자입니다.이 첨부파일이 있는
CourseWork
또는CourseWorkMaterial
첨부되어 있습니다.모든 iframe에 포함됩니다.
- 항목 유형
itemType
값은 이 필드가 실행되는 리소스 유형을 식별합니다.첨부파일이 첨부되었습니다. 전달된 문자열 값은
"announcements"
중 하나입니다."courseWork"
또는"courseWorkMaterials"
입니다.모든 iframe에 포함됩니다.
- 첨부파일 ID
attachmentId
값은 첨부파일의 식별자입니다.teacherViewUri
,studentViewUri
및studentWorkReviewUri
iframe.- 제출 ID
submissionId
값은 학생 과제물의 식별자입니다. 하지만attachmentId
와 함께 사용하여 확인할 수 있습니다.studentWorkReviewUri
에 포함됩니다. 를 통해 개인정보처리방침을 정의할 수 있습니다.
- 부가기능 토큰
addOnToken
값은 다음을 실행하는 데 사용되는 승인 토큰입니다.addOnAttachments.create
가 있어야 합니다.첨부파일 검색 iframe 및 링크 업그레이드에 포함 iframe을 사용하세요.
- 업그레이드할 URL
urlToUpgrade
값이 있으면선생님이 과제에 링크 첨부파일을 포함하고 이에 동의했습니다. 부가기능 첨부파일로 업그레이드하세요. 계정이 없는 경우 부가기능으로 링크 업그레이드에 대한 가이드를 참조하세요. 첨부파일을 참고하세요.
링크 업그레이드 iframe에 포함됩니다.
로그인 관련 매개변수
login_hint
쿼리 매개변수는
부가기능 웹페이지를 방문하는 클래스룸 사용자 이 쿼리 매개변수
iframe src
URL에서 제공됩니다. 사용자가 이전에 사용한 적이 있는 경우
최종 사용자의 로그인 문제를 줄이는 데 도움이 됩니다 kubectl 명령어
이 쿼리 매개변수를 추가하세요.
- 로그인 힌트
login_hint
는 사용자의 Google계정을 탭합니다. 사용자가 부가기능에 처음 로그인한 후
login_hint
매개변수는 이후에 부가기능을 방문할 때마다 생성할 수 있습니다.login_hint
매개변수의 용도는 두 가지입니다.- 인증 흐름 중에
login_hint
값을 전달하여 사용자가 로그인 대화상자에 사용자 인증 정보를 입력하지 않아도 됨 표시됩니다. 사용자는 자동으로 로그인되지 않습니다. - 사용자가 로그인한 후 이 매개변수를 사용하여 이미 부가 기능에 로그인한 모든 사용자에게 제공할 수 있습니다. 만약 일치하는 콘텐츠를 찾으면 사용자를 로그인 상태로 두고 로그인 흐름을 통해 이를 수행할 수 있습니다. 매개변수가 로그인한 계정과 일치하지 않는 경우 사용자에게 Google 브랜드 로그인 버튼을 클릭합니다.
모든 iframe에 포함됩니다.
를 통해 개인정보처리방침을 정의할 수 있습니다.
- 인증 흐름 중에
첨부파일 검색 iframe
측정기준 | 설명 |
---|---|
필수 | 예 |
URI | 부가기능 메타데이터에 제공 |
쿼리 매개변수 | courseId , itemId , itemType
addOnToken , login_hint |
높이 | 상단 헤더의 80% 창 높이 - 60px |
너비 | 최대 1600px , 창 너비가 600px 이하일 때 90% 창 너비 넓음 80% 창 너비(창 > 경우) 600픽셀 너비 |
첨부파일 검색 시나리오 예
- 클래스룸 부가기능이 Google Workspace에 등록됨
첨부파일 검색 URI가
https://example.com/addon
인 Marketplace - 교사가 이 부가기능을 설치하고 새 공지사항, 과제 또는
자료를 볼 수 있습니다 예를 들면
itemId=234
입니다.itemType=courseWork
및courseId=123
. - 항목을 구성하는 동안 교사가 새로 설치된 부가기능을 선택 첨부파일로 저장해 두세요.
- 클래스룸에서 src URL이
https://example.com/addon?courseId=123&itemId=234&itemType=courseWork&addOnToken=456
- 교사는 iframe 내에서 첨부파일을 선택하는 작업을 수행합니다.
- 첨부파일을 선택하면 부가기능이
postMessage
을 클래스룸을 클릭하여 iframe을 닫습니다.
선생 보기 URI 및 학생 보기 URI iframe
측정기준 | 설명 |
---|---|
필수 | 예 |
URI | teacherViewUri 또는 studentViewUri |
쿼리 매개변수 | courseId , itemId , itemType
attachmentId , login_hint |
높이 | 상단 헤더의 100% 창 높이 - 140px |
너비 | 100% 창 너비 |
학생 작업 검토 URI iframe
측정기준 | 설명 |
---|---|
필수 | 아니요 (활동 유형 첨부파일인지 확인) |
URI | studentWorkReviewUri |
쿼리 매개변수 | courseId , itemId , itemType
attachmentId , submissionId , login_hint |
높이 | 상단 헤더의 100% 창 높이 - 168px |
너비 | 100% 창 너비 - 사이드바 너비<> 사이드바 312픽셀 펼쳐졌을 때, 접힐 때 56픽셀 |
링크 업그레이드 iframe
측정기준 | 설명 |
---|---|
필수 | 예, 부가기능 첨부파일 링크 업그레이드가 부가기능에서 지원되는지 확인하세요 |
URI | 부가기능 메타데이터에 제공 |
쿼리 매개변수 | courseId , itemId , itemType
addOnToken , urlToUpgrade , login_hint |
높이 | 상단 헤더의 80% 창 높이 - 60px |
너비 | 최대 1600px , 창 너비가 600px 이하일 때 90% 창 너비 넓음 80% 창 너비(창 > 경우) 600픽셀 너비 |
링크 업그레이드 시나리오 예
- 클래스룸 부가기능이 다음 링크 업그레이드 URI로 등록됩니다.
https://example.com/upgrade
다음 호스트와 경로를 제공했습니다. 클래스룸에서 사용해야 하는 링크 첨부파일의 접두사 패턴 부가기능 첨부파일로 업그레이드를 시도합니다. <ph type="x-smartling-placeholder">- </ph>
- 호스트는
example.com
이고 경로 프리픽스는/quiz
입니다.
- 호스트는
- 선생님이 수업 중 하나에 새 공지사항, 과제 또는 자료를 만든 경우
학습합니다. 예를 들면
itemId=234
,itemType=courseWork
,courseId=123
입니다. - 교사가 링크(
https://example.com/quiz/5678
)를 링크에 붙여넣습니다. 첨부파일 대화상자가 표시됩니다. 교사는 링크를 부가기능 첨부파일로 업그레이드하라는 메시지가 표시됩니다. 클래스룸에서 URL이 설정된 링크 업그레이드 iframe 실행 ~
https://example.com/upgrade?courseId=123&itemId=234&itemType=courseWork&addOnToken=456&urlToUpgrade=https%3A%2F%2Fexample.com%2Fquiz%2F5678
iframe에 전달된 쿼리 매개변수를 평가하고 다음을 호출합니다.
CreateAddOnAttachment
엔드포인트.urlToUpgrade
쿼리는 매개변수는 iframe으로 전달될 때 URI로 인코딩됩니다. 이 디코딩 함수는 매개변수를 사용하여 원래 형식으로 가져옵니다. 예를 들어 JavaScript는decodeURIComponent()
함수링크에서 부가기능 첨부파일이 성공적으로 생성되면
postMessage
를 클릭하여 클래스룸으로 이동하여 iframe을 닫습니다.
iframe 닫기
iframe이 학습 도구에서 닫힐 수 있습니다. postMessage
페이로드 {type: 'Classroom', action: 'closeIframe'}
.
클래스룸은 host_name+포트에서 이 postMessage
만 수락합니다.
원래의 URI에 해당합니다.
<button id="close">Send message to close iframe</button>
<script>
document.querySelector('#close')
.addEventListener('click', () => {
window.parent.postMessage({
type: 'Classroom',
action: 'closeIframe',
}, '*');
});
</script>
iframe에서 iframe 닫기
postMessage
이벤트를 전송하는 페이지의 도메인+포트가 동일해야 합니다.
iframe을 시작하는 데 사용되는 URI의 도메인+포트입니다. 그렇지 않으면 메시지가
무시됩니다. 해결 방법은 원래 도메인의 페이지로 다시 리디렉션하는 것입니다.
오직 postMessage
이벤트만 전송하지는 않습니다.
새 탭에서 iframe 닫기
교차 도메인 보호 조치를 사용하면 이 기능이 작동하지 않습니다. 해결 방법은
iframe과 새 탭 간의 통신을 직접 제어하고 iframe이
닫기 postMessage
이벤트의 실행에 대한 최종적인 책임입니다. 측면
'파트너 이름에서 열기' 하이퍼링크를 사용자가 특정 콘텐츠를
사용할 수 없도록
조만간 이런 식으로 탭을 만들게 될 것입니다.
제한사항
모든 iframe은 다음 샌드박스 속성으로 열립니다.
allow-popups
allow-popups-to-escape-sandbox
allow-forms
allow-scripts
allow-storage-access-by-user-activation
allow-same-origin
및 다음 기능 정책
allow="microphone *"
서드 파티 쿠키 차단
서드 파티 쿠키를 차단하면 로그인한 상태로 표시할 수 있습니다. https://www.cookiestatus.com 페이지에서 쿠키의 현재 상태에 대해 자세히 알아보세요. 물론 이 문제는 Google 클래스룸 부가기능에만 해당하는 것이 아니며 있습니다. 이미 많은 파트너가 이 문제를 경험했습니다.
일반적인 해결 방법은 다음과 같습니다.
- 새 탭을 열어 퍼스트 파티 맥락에서 쿠키를 만듭니다. 일부 브라우저 퍼스트 파티 맥락에서 생성된 쿠키에 대한 액세스 권한을 서드 파티 맥락에 따라 다릅니다.
- 사용자에게 서드 파티 쿠키를 허용해 달라고 요청합니다. 가끔은 가능하지 않을 수 있음 공유할 수 있습니다.
- 쿠키를 사용하지 않는 단일 페이지 웹 애플리케이션을 설계합니다.
향후 브라우저 버전에서는 더 많은 쿠키 제한이 적용될 예정입니다. 만들기 필요한 광고효과를 줄이는 방법에 관한 의견을 Google에 보내기 위한 기능 요청 제공합니다.
URL 정규 표현식을 사용하여 부가기능의 검색 가능 여부 사용 설정
교사는 종종 링크 첨부파일이 포함된 과제를 만듭니다. 앱 사용을 촉진하기 위해 리소스 URL과 일치하는 정규 표현식을 지정할 수 있습니다. 확인할 수 있습니다 교사가 일치하는 링크를 첨부함 닫을 수 있는 대화상자가 표시되어 확인할 수 있습니다 부가기능이 이미 설치된 경우에만 대화상자가 표시됩니다. 계정을 만들 수 있습니다.
교사에게 이러한 행동을 제공하려면 Google 적절한 정규 표현식을 사용하여 연락처를 찾을 수 있습니다. 정규식이 너무 광범위하거나 다른 부가 기능과 충돌한다면 더 제한되거나 명확하게 수정됩니다.
그림 1. 링크를 선택하는 교사
새 과제에 첨부할 수 있습니다.
그림 2. 교사가 서드 파티의 링크를 붙여넣는 경우
있습니다. 교사가 이미 서드 파티의
클래스룸 부가기능.
그림 3. 화면에 표시된 대화형 대화상자는
붙여넣은 링크가
서드 파티 개발자에게 문의하세요.
교사가 '지금 사용해 보기'를 선택하는 경우 팝의 경우 그림 3과 같이 부가기능의 첨부파일 검색 iframe으로 리디렉션됩니다.