이 페이지는 Cloud Translation API를 통해 번역되었습니다.

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

클래스룸 부가기능은 iframe 내에 로드되어 최종 사용자에게 원활하고 편리한 사용자 환경을 제공합니다. iframe 유형에는 네 가지가 있습니다. 각 iframe의 목적과 모양에 관한 개요는 사용자 여정 디렉터리의 iframes 페이지를 참고하세요.

iframe 보안 가이드라인

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

HTTPS는 필수 항목입니다. TLS 1.2 이상을 사용하고 HTTP Strict Transport Security를 사용 설정하는 것이 좋습니다. Strict Transport Security에 관한 이 관련 MDN 도움말을 참고하세요.
엄격한 콘텐츠 보안 정책을 사용 설정합니다. 이 OWASP 도움말 및 관련 콘텐츠 보안 정책 MDN 도움말을 참고하세요.
보안 쿠키 속성을 사용 설정합니다. HttpOnly 속성 및 관련 쿠키 MDN 도움말을 참고하세요.

iFrame URI 구성

첨부파일 설정 URI는 첨부파일 검색 iframe에서 로드하며 교사는 클래스룸 게시물에 부가기능 첨부파일을 만드는 흐름을 시작하는 역할을 합니다. Google Cloud 프로젝트 콘솔에서 설정할 수 있습니다. Google Cloud 프로젝트의 API 및 서비스 > Google Workspace Marketplace SDK > 앱 구성 페이지에서 이 URI를 설정합니다.

iFrame URI 구성

허용된 연결 URI 프리픽스는 *.addOnAttachments.create 및 *.addOnAttachments.patch 메서드를 사용하여 AddOnAttachment에 설정된 URI를 검증하는 데 사용됩니다. 유효성 검사는 리터럴 문자열 프리픽스 일치 항목이며 현재 와일드 카드 사용을 허용하지 않습니다.

쿼리 매개변수

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

첨부파일 관련 매개변수

첨부파일 관련 매개변수는 과정, 과제, 부가기능 첨부파일, 학생 제출물, 승인 토큰에 대한 정보를 부가기능에 제공합니다.

수업 ID

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

모든 iframe에 포함됩니다.

게시물 ID (지원 중단됨)

postId 값은 이 연결이 첨부된 게시물(공지사항, 학습 과정 또는 학습 과제 자료)의 식별자입니다.

모든 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에서 제공됩니다. 최종 사용자 로그인 문제를 줄이기 위해 사용자가 이전에 부가기능을 사용한 경우 전송됩니다. 부가기능 구현에서 이 쿼리 매개변수를 처리해야 합니다.

로그인 힌트

login_hint는 사용자의 Google

계정을 탭합니다. 사용자가 부가기능에 처음 로그인하면 이후 동일한 사용자가 부가기능을 방문할 때마다 login_hint 매개변수가 전달됩니다.

login_hint 매개변수의 용도는 두 가지입니다.

로그인 대화상자가 표시될 때 사용자가 사용자 인증 정보를 입력할 필요가 없도록 인증 흐름에서 login_hint 값을 전달합니다. 사용자가 자동으로 로그인되지 않습니다.
사용자가 로그인한 후 이 매개변수를 사용하여 부가기능에 이미 로그인한 사용자와 값을 비교합니다. 일치하는 항목이 있으면 해당 사용자를 로그인한 상태로 두고 로그인 과정이 표시되지 않도록 할 수 있습니다. 매개변수가 로그인한 사용자와 일치하지 않으면 사용자에게 Google 브랜드의 로그인 버튼으로 로그인하라는 메시지를 표시합니다.

모든 iframe에 포함됩니다.

첨부파일 검색 iframe

측정기준	설명
필수	예
URI	부가기능 메타데이터에 제공됨
쿼리 매개변수	`courseId`, `postId` (지원 중단됨), `itemId`, `itemType`, `addOnToken`, `login_hint`.
키	상단 헤더의 경우 창 높이 80% - 60px
너비	최대 1600px 창 너비 600px 이하일 때 90% 창 너비 600px 초과 시 80%

첨부파일 검색 시나리오 예시

클래스룸 부가기능이 https://example.com/addon의 연결 검색 URI로 Google Workspace Marketplace에 등록됩니다.
교사가 이 부가기능을 설치하고 강의 중 하나에서 새로운 공지사항, 과제 또는 자료를 만듭니다. 예를 들면 itemId=234, itemType=courseWork, courseId=123입니다.
교사는 항목을 구성하는 동안 새로 설치된 부가기능을 첨부파일로 선택합니다.
클래스룸에서 src URL이 https://example.com/addon?courseId=123&itemId=234&itemType=courseWork&addOnToken=456로 설정된 iframe을 만듭니다.
1. 교사는 iframe 내에서 작업을 수행하여 첨부파일을 선택합니다.
첨부파일을 선택하면 부가기능에서 postMessage를 클래스룸으로 전송하여 iframe을 닫습니다.

교사 보기 URI 및 학생 보기 URI iframe

측정기준	설명
필수	예
URI	`teacherViewUri` 또는 `studentViewUri`
쿼리 매개변수	`courseId`, `postId` (지원 중단됨), `itemId`, `itemType`, `attachmentId`, `login_hint`.
키	상단 헤더의 경우 창 높이 100% 에서 140픽셀을 뺀 값
너비	100% 창 너비

학생 작업 검토 URI iframe

측정기준	설명
필수	아니요 (활동 유형 첨부파일인지 여부 결정)
URI	`studentWorkReviewUri`
쿼리 매개변수	`courseId`, `postId` (지원 중단됨), `itemId`, `itemType`, `attachmentId`, `submissionId`, `login_hint`
키	상단 헤더의 경우 창 높이 100% 에서 168픽셀을 뺀 값
너비	창 너비 100% - 사이드바 너비를 뺀 100% - 사이드바는 펼쳤을 때 312픽셀, 접었을 때 56픽셀임

링크 업그레이드 iframe

측정기준	설명
필수	예, 부가기능에서 부가기능 첨부파일로 연결되는 링크 업그레이드를 지원하는 경우
URI	부가기능 메타데이터에 제공됨
쿼리 매개변수	`courseId`, `postId` (지원 중단됨), `itemId`, `itemType`, `addOnToken`, `urlToUpgrade`, `login_hint`
키	상단 헤더의 경우 창 높이 80% - 60px
너비	최대 1600px 창 너비 600px 이하일 때 90% 창 너비 600px 초과 시 80%

링크 업그레이드 시나리오의 예

클래스룸 부가기능은 https://example.com/upgrade의 링크 업그레이드 URI로 등록됩니다. 클래스룸에서 부가기능 첨부파일로 업그레이드하려고 시도해야 하는 다음과 같은 연결 연결의 호스트 및 경로 접두사 패턴을 제공했습니다.
- 호스트는 example.com이고 경로 접두사는 /quiz입니다.
교사가 과정 중 하나에서 새 공지사항, 과제 또는 자료를 만듭니다. 예를 들면 itemId=234, itemType=courseWork, courseId=123입니다.
교사가 제공된 URL 패턴과 일치하는 링크 연결 대화상자에 링크 https://example.com/quiz/5678를 붙여넣습니다. 그러면 교사에게 링크를 부가기능 첨부파일로 업그레이드하라는 메시지가 표시됩니다.
클래스룸에서 URL이 https://example.com/upgrade?courseId=123&postId=234&addOnToken=456&urlToUpgrade=https%3A%2F%2Fexample.com%2Fquiz%2F5678로 설정된 링크 업그레이드 iframe을 실행합니다.
iframe에 전달된 쿼리 매개변수를 평가하고 CreateAddOnAttachment 엔드포인트를 호출합니다. urlToUpgrade 쿼리 매개변수는 iframe에 전달될 때 URI 인코딩됩니다. 매개변수를 디코딩하여 원래 형식으로 얻어야 합니다. 예를 들어 JavaScript는 decodeURIComponent() 함수를 제공합니다.
링크에서 부가기능 첨부파일이 성공적으로 생성되면 postMessage를 클래스룸으로 전송하여 iframe을 닫습니다.

iframe 닫기

iframe은 페이로드 {type: 'Classroom', action: 'closeIframe'}와 함께 postMessage를 전송하여 학습 도구에서 닫을 수 있습니다. 클래스룸은 열려 있는 원래 URI에 해당하는 host_name+port에서만 이 postMessage를 허용합니다.

<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과 새 탭 간의 통신을 자체적으로 처리하고 궁극적으로 postMessage 닫기 이벤트 실행을 iframe이 담당하도록 하는 것입니다. 참고로 '파트너 이름에서 열기' 하이퍼링크는 사용자가 가까운 시일 내에 이러한 방식으로 탭을 만들지 않도록 삭제됩니다.

제한사항

모든 iframe은 다음 샌드박스 속성으로 열립니다.

allow-popups
allow-popups-to-escape-sandbox
allow-forms
allow-scripts
allow-storage-access-by-user-activation
allow-same-origin

및 다음 기능 정책

allow="microphone *"

서드 파티 쿠키 차단

서드 파티 쿠키를 차단하면 iframe에서 로그인한 세션을 유지하기가 어려워집니다. 여러 브라우저에서 쿠키를 차단하는 현재 상태는 https://www.cookiestatus.com을 참조하세요. 물론 이 문제는 Google 클래스룸 부가기능에 국한된 것이 아니며 서드 파티에 iframe을 사용하는 모든 웹사이트에 영향을 미칩니다. 이미 많은 파트너에게 이 문제가 발생했습니다.

일반적인 해결 방법은 다음과 같습니다.

새 탭을 열어 퍼스트 파티 맥락에서 쿠키를 만듭니다. 일부 브라우저는 서드 파티 컨텍스트에서 퍼스트 파티 컨텍스트에서 생성된 쿠키에 대한 액세스 권한을 부여합니다.
사용자에게 서드 파티 쿠키를 허용하도록 요청합니다. 모든 사용자가 이 기능을 사용하지 못할 수도 있습니다.
쿠키를 사용하지 않는 단일 페이지 웹 애플리케이션을 설계합니다.

향후 브라우저 버전에서 더 많은 쿠키 제한이 적용될 예정입니다. 기능 요청을 만들어 파트너가 요구하는 광고효과를 줄이는 방법에 관한 의견을 Google에 보냅니다.

URL 정규 표현식을 사용하여 부가기능의 검색 기능 사용 설정

교사는 자주 링크 첨부파일을 사용하여 과제를 만듭니다. 부가기능 사용을 촉진하려면 부가기능에서 액세스할 수 있는 리소스의 URL과 일치하는 정규 표현식을 지정하면 됩니다. 정규 표현식 중 하나와 일치하는 링크를 첨부하는 교사에게 부가기능을 사용해 보도록 권장하는 닫을 수 있는 대화상자가 표시됩니다. 계정에 부가기능이 이미 설치된 경우에만 대화상자가 표시됩니다.

교사에게 이 동작을 제공하려면 Google 담당자에게 적절한 정규 표현식을 제공하세요. 제공하는 정규 표현식이 지나치게 광범위하거나 다른 부가기능과 충돌하는 경우 좀 더 제한되거나 구분되도록 수정될 수 있습니다.

링크 첨부파일을 선택하는 교사 그림 1. 교사가 새 과제의 링크 첨부파일을 선택합니다.

교사가 링크를 붙여넣음 그림 2. 교사가 서드 파티 소스의 링크를 붙여넣습니다. 교사가 서드 파티의 클래스룸 부가기능을 이미 설치했습니다.

정규식 검색 가능 대화상자 그림 3. 붙여넣은 링크가 서드 파티 개발자가 지정한 정규 표현식과 일치하는 경우 교사에게 표시되는 대화형 대화상자입니다.

교사가 그림 3과 같이 팝업에서 '사용해 보기'를 선택하면 부가기능의 첨부파일 검색 iframe으로 리디렉션됩니다.