이제 Google 클래스룸 부가기능이 일반적으로 개발자에게 제공됩니다. 자세한 내용은 부가기능 문서를 참고하세요.

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

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

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

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 및 서비스 > Google Workspace Marketplace SDK > 앱 구성 페이지에서 이 URI를 설정합니다.

iFrame URI 구성

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

쿼리 매개변수

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

로그인 힌트

login_hint는 사용자의 Google

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

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

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

모든 iframe에 포함됩니다.

첨부파일 검색 iframe

측정기준	설명
필수	예
URI	부가기능 메타데이터에 제공
쿼리 매개변수	`courseId`, `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을 닫습니다.

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픽셀입니다.

링크 업그레이드 iframe

측정기준	설명
필수	예. 부가기능에서 부가기능 첨부파일에 대한 링크 업그레이드를 지원하는 경우
URI	부가기능 메타데이터에 제공
쿼리 매개변수	`courseId`, `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&itemId=234&itemType=courseWork&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과 새 탭 간의 통신을 직접 처리하고 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 *"

서드 파티 쿠키 차단

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

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

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

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

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

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

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

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

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

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

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