iframe 및 쿼리 매개변수 세부정보

클래스룸 부가기능은 iframe 내에 로드되어 최종 사용자에게 원활하고 편리한 사용자 환경을 제공합니다. 머신러닝 모델에 iframe 유형 사용자 경험 디렉터리의 iframe 페이지에서 각 iframe의 목적과 모양에 대한 개요가 나와 있습니다.

iframe 보안 가이드라인

파트너는 업계 권장사항에 따라 iframe을 보호해야 합니다. iframe을 보호하려면 Google 보안팀에서 다음을 권장합니다.

iFrame URI 구성

첨부파일 설정 URI는 첨부파일 검색 iframe이 로드하는 것입니다. 교사가 클래스룸에서 부가기능 첨부파일을 만드는 과정을 클래스룸 게시물 Google Cloud 프로젝트 콘솔에서 설정할 수 있습니다. Google Cloud 프로젝트의 API에서 이 URI를 설정하고 서비스 > Google Workspace Marketplace SDK > App Configuration(앱 구성) 페이지

iFrame URI 구성

허용된 첨부파일 URI 프리픽스AddOnAttachment 다음을 사용하여 *.addOnAttachments.create*.addOnAttachments.patch 메서드와 함께 사용할 수 있습니다. 유효성 검사는 리터럴 문자열 접두사입니다. 일치하며 현재는 와일드 카드 사용을 허용하지 않습니다.

쿼리 매개변수

iframe은 중요한 정보를 부가기능에 쿼리 매개변수로 전달합니다. 매개변수에는 첨부파일 관련 매개변수와 로그인 관련 매개변수라는 두 가지 카테고리가 있습니다. 매개변수입니다.

첨부파일 관련 매개변수는 부가기능에 과제, 부가기능 첨부파일, 학생의 제출물, 토큰입니다.

수업 ID

courseId 값은 과정의 식별자입니다.

모든 iframe에 포함됩니다.

상품 ID

itemId 값은 Announcement의 식별자입니다.

이 첨부파일이 있는 CourseWork 또는 CourseWorkMaterial 첨부되어 있습니다.

모든 iframe에 포함됩니다.

항목 유형

itemType 값은 이 필드가 실행되는 리소스 유형을 식별합니다.

첨부파일이 첨부되었습니다. 전달된 문자열 값은 "announcements" 중 하나입니다. "courseWork" 또는 "courseWorkMaterials"입니다.

모든 iframe에 포함됩니다.

첨부파일 ID

attachmentId 값은 첨부파일의 식별자입니다.

teacherViewUri, studentViewUristudentWorkReviewUri 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 매개변수의 용도는 두 가지입니다.

  1. 인증 흐름 중에 login_hint 값을 전달하여 사용자가 로그인 대화상자에 사용자 인증 정보를 입력하지 않아도 됨 표시됩니다. 사용자는 자동으로 로그인되지 않습니다.
  2. 사용자가 로그인한 후 이 매개변수를 사용하여 이미 부가 기능에 로그인한 모든 사용자에게 제공할 수 있습니다. 만약 일치하는 콘텐츠를 찾으면 사용자를 로그인 상태로 두고 로그인 흐름을 통해 이를 수행할 수 있습니다. 매개변수가 로그인한 계정과 일치하지 않는 경우 사용자에게 Google 브랜드 로그인 버튼을 클릭합니다.

모든 iframe에 포함됩니다.

를 통해 개인정보처리방침을 정의할 수 있습니다.
를 통해 개인정보처리방침을 정의할 수 있습니다.

첨부파일 검색 iframe

측정기준 설명
필수
URI 부가기능 메타데이터에 제공
쿼리 매개변수 courseId, itemId, itemType addOnToken, login_hint
높이 상단 헤더의 80% 창 높이 - 60px
너비 최대 1600px
, 창 너비가 600px 이하일 때 90% 창 너비 넓음
80% 창 너비(창 > 경우) 600픽셀 너비

첨부파일 검색 시나리오 예

  1. 클래스룸 부가기능이 Google Workspace에 등록됨 첨부파일 검색 URI가 https://example.com/addon인 Marketplace
  2. 교사가 이 부가기능을 설치하고 새 공지사항, 과제 또는 자료를 볼 수 있습니다 예를 들면 itemId=234입니다. itemType=courseWorkcourseId=123.
  3. 항목을 구성하는 동안 교사가 새로 설치된 부가기능을 선택합니다. 첨부파일로 저장해 두세요.
  4. 클래스룸에서 src URL이 https://example.com/addon?courseId=123&itemId=234&itemType=courseWork&addOnToken=456
    1. 교사는 iframe 내에서 첨부파일을 선택하는 작업을 수행합니다.
  5. 첨부파일을 선택하면 부가기능이 postMessage을 클래스룸을 클릭하여 iframe을 닫습니다.

TeachingViewUri 및studentViewUri 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픽셀

측정기준 설명
필수 예, 부가기능 첨부파일 링크 업그레이드가 부가기능에서 지원되는지 확인하세요
URI 부가기능 메타데이터에 제공
쿼리 매개변수 courseId, itemId, itemType addOnToken, urlToUpgrade, login_hint
높이 상단 헤더의 80% 창 높이 - 60px
너비 최대 1600px
, 창 너비가 600px 이하일 때 90% 창 너비 넓음
80% 창 너비(창 > 경우) 600픽셀 너비
  1. 클래스룸 부가기능이 다음 링크 업그레이드 URI로 등록됩니다. https://example.com/upgrade 다음 호스트와 경로를 제공했습니다. 클래스룸에서 사용해야 하는 링크 첨부파일의 접두사 패턴 부가기능 첨부파일로 업그레이드를 시도합니다. <ph type="x-smartling-placeholder">
      </ph>
    • 호스트는 example.com이고 경로 프리픽스는 /quiz입니다.
  2. 선생님이 수업 중 하나에 새 공지사항, 과제 또는 자료를 만든 경우 학습합니다. 예를 들면 itemId=234, itemType=courseWork, courseId=123입니다.
  3. 교사가 링크(https://example.com/quiz/5678)를 링크에 붙여넣습니다. 첨부파일 대화상자가 표시됩니다. 교사는 링크를 부가기능 첨부파일로 업그레이드하라는 메시지가 표시됩니다.
  4. 클래스룸에서 URL이 설정된 링크 업그레이드 iframe 실행 ~ https://example.com/upgrade?courseId=123&itemId=234&itemType=courseWork&addOnToken=456&urlToUpgrade=https%3A%2F%2Fexample.com%2Fquiz%2F5678

  5. iframe에 전달된 쿼리 매개변수를 평가하고 다음을 호출합니다. CreateAddOnAttachment 엔드포인트. urlToUpgrade 쿼리는 매개변수는 iframe으로 전달될 때 URI로 인코딩됩니다. 이 디코딩 함수는 매개변수를 사용하여 원래 형식으로 가져옵니다. 예를 들어 JavaScript는 decodeURIComponent() 함수

  6. 링크에서 부가기능 첨부파일이 성공적으로 생성되면 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으로 리디렉션됩니다.